Malet App SDK & Developer Platform

Mallnline operates as a web-based operating system for commerce. The platform provides the OS (identity, storage, networking, UI chrome), the public GraphQL API becomes the system framework, and each Malet becomes an app. Two coexisting tracks serve different personas:

Track	Name	Audience	Rendering
Track 1	Malet Verticals	Non-technical Malet Owners	Platform-rendered — StorefrontRenderer + widget slots
Track 2	Malet Apps	Developers & technical creatives	Sandboxed SPA via `<iframe>` + `@mallnline/sdk` bridge

All existing Malets default to Track 1 (Verticals) — the zero-code system is unchanged. Track 2 is opt-in for developers who want full creative control.

Architecture Overview

┌──────────────────────────────────────────────────────┐
│  Mallnline Platform Shell (Host Page)                │
│                                                      │
│  ┌────────────────────┐    ┌──────────────────────┐  │
│  │  StorefrontRenderer │    │  MaletAppViewport    │  │
│  │  (Track 1)         │    │  (Track 2)           │  │
│  │                    │    │                      │  │
│  │  Widget Slots      │    │  <iframe sandbox>    │  │
│  │  ThemeConfig       │    │    ┌──────────────┐  │  │
│  │  LayoutConfig      │    │    │ Your SPA     │  │  │
│  │                    │    │    │ @mallnline/  │  │  │
│  │                    │    │    │   sdk        │  │  │
│  │                    │    │    └──────────────┘  │  │
│  └────────────────────┘    └──────────────────────┘  │
│                                                      │
│  ┌─────────────�## The `@mallnline/sdk` Package

The SDK is a zero-dependency TypeScript library that runs inside the Malet App iframe. Every API call is serialized as a `postMessage` request, validated by the platform shell, and forwarded to the [GraphQL Gateway](/gateway).

### The Scaffolder CLI (`create-malet-app`)

To streamline Track 2 application development, developers can scaffold a fully configured Malet App starter template in seconds using the official CLI tool:

```bash
# Initialize a new custom Malet App SPA in the current directory
npx -y @mallnline/create-malet-app@latest ./

The scaffolding CLI sets up:

Vite & TypeScript Configuration: Fine-tuned for building isolated SPAs compatible with the platform's Content Security Policies.
mockBridge.ts Parent Simulator: A fully functional mock bridge running in a Web Worker or top-level browser frame to intercept postMessage calls during offline local development (npm run dev), allowing you to simulate products catalog queries and toast notifications without being mounted inside the live Mallnline platform.
Production-Ready Starter Layout: Seamless responsive layout conforming to Mallnline's grid and glassmorphic UI design tokens.

Quick Start

import { MaletApp } from '@mallnline/sdk';

const app = new MaletApp({
  maletId: 'luminara-crafts',
  version: '1.0.0',
});

// Identity via uID
const user = await app.auth.getCurrentUser();

// Commerce
const products = await app.products.list({ first: 20 });
await app.cart.addItem({ itemId: products.edges[0].node.id, quantity: 1 });

// Platform chrome
app.shell.showToast('Added to cart!', 'success');

SDK Modules

Module	Description	Required Scope
`app.auth`	uID identity — login, profile, auth state changes	`read:profile`
`app.products`	Product catalog CRUD (scoped to this Malet)	`read:products`, `write:products`
`app.cart`	uCart operations — add, remove, checkout	`read:cart`, `write:cart`
`app.services`	Service listings and time-slot availability	`read:services`
`app.bookings`	Booking creation	`write:bookings`
`app.blogs`	Blog posts — list and create	`read:blogs`, `write:blogs`
`app.chat`	uChat conversations — open, send messages	`send:uchat`
`app.media`	Media upload and CDN URL generation	`read:media`, `write:media`
`app.search`	Search with faceted filtering	`read:search`
`app.events`	Real-time event subscriptions	— (no scope)
`app.shell`	Platform chrome — title, toasts, navigation, theme tokens	— (no scope)

The Developer Studio & Webhooks Logs

Malet Owners and developers configure Track 2 apps inside the merchant dashboard (The Deck) at /studio.

┌──────────────────────────────────────────────────────────┐
│  Developer Studio Dashboard (/studio)                     │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Credentials & Client Keys Configuration            │  │
│  └────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Webhooks Logs Browser (Svelte 5)                    │  │
│  │                                                    │  │
│  │ ┌───────────────┐ ┌──────────────┐ ┌─────────────┐ │  │
│  │ │ HTTP Payload  │ │ HTTP Headers │ │ Diagnostics │ │  │
│  │ └───────────────┘ └──────────────┘ └─────────────┘ │  │
│  │ 🟢 200 OK - product.updated (12ms ago)             │  │
│  │ 🔴 500 Err - murchase.paid (2m ago)   [Retry ↻]     │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

The Webhooks Logs dashboard provides a high-fidelity interface for monitoring cross-system events:

Live Dispatch Audits: Real-time logging of HTTP events sent to your application's external backend endpoints.
Detailed HTTP Inspection: Multi-tab panels containing syntax-highlighted request/response JSON bodies and full HTTP headers arrays.
Simulated Redispatches (Retry-Toast Flow): Initiate instant retries of failed webhooks via manual dispatch loops, displaying glassmorphic status notifications directly in the workspace interface.

Security Model

The platform enforces a four-layer security sandwich:

Layer 1: Browser Sandbox & CSP Delegation

<iframe
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  allow="payment; camera; microphone; geolocation; clipboard-write;"  <!-- delegated from AppManifest -->
  referrerpolicy="strict-origin"
  loading="lazy"
/>

The iframe runs in a separate browsing context — separate JS heap, separate event loop, and separate DOM. The Malet App cannot access the host page, other Malets, or the platform's cookies.

Furthermore, Mallnline dynamically extracts Content Security Policies (CSP) per app:

Script Origin Guarding: Automatically restricting executable scripts inside the sandbox to approved CDN origins.
Permissions Delegation: Automatically restricting permissions (camera, geolocations, payments) strictly to API hooks authorized in the registered AppManifest.

Layer 2: SDK Bridge (Frontend)

The MaletAppViewport component validates every postMessage:

Origin validation — Only accepts messages from the app's declared CDN origin.
Schema validation — Rejects malformed message structures.
Rate limiting — Enforces AppManifest.resourceLimits.maxApiCallsPerMinute on the postMessage event queue.
Scope enforcement — Checks the scope registry before forwarding to prevent malicious or accidental unauthorized endpoint calls.

Layer 3: Gateway Guard (Backend)

The MaletAppScopeGuard at the GraphQL Gateway level double-checks scopes on every forwarded request. Resolvers annotated with @RequireAppScope('read:products') are blocked if the calling app doesn't have the scope in its active manifest token.

Layer 4: Data Boundary

All GraphQL resolvers filter by maletId — a Malet App can only access its own data. This is enforced at the database query level, not the application layer, preventing cross-tenant data leaks.

Memory & Performance (CPU Jank Tracking)

To maintain a buttery-smooth 60fps experience for visitors as they browse through the virtual mall, the MaletAppViewport employs real-time active system resources monitoring:

Svelte 5 PerformanceObserver Integration: The viewport attaches a lightweight PerformanceObserver detecting Long Animation Frames (LoAF) and blocking JS scripts inside the iframe.
Glassmorphic CPU Jank Warnings: When CPU utilization or thread-blocking exceeds 50ms (standard jank threshold), the platform displays a smooth, non-intrusive glassmorphic warning banner with micro-animations instructing the owner or developer to optimize their SPA's main thread loop.
Resource Constraints:

Concern	Solution
Bundle bloat	`MaletAppViewport` is dynamically imported — zero cost for Track 1 Verticals.
App memory	Separate browsing context — destroying the iframe viewport triggers a full GC sweep.
API abuse	Per-app rate limiting enforced at postMessage bridge and gateway.
CPU abuse	Active resource limits and real-time thread diagnostics using `PerformanceObserver`.

The SDK lives in the @ngwenya/packages monorepo alongside @ngwenya/queries and @ngwenya/ui. It shares no runtime dependencies — the SDK is a pure postMessage bridge.

MaletType Enum

The maletType field on the Malet entity determines rendering:

enum MaletType {
  """Config-driven storefront (widget slots, ThemeConfig, LayoutConfig)"""
  VERTICAL

  """Developer-built SPA loaded in sandboxed iframe"""
  APP
}

All existing Malets have maletType: VERTICAL by default. The field is set when a Malet Owner opts into the developer track via The Studio dashboard.

Shared Query Package (@ngwenya/queries) — The queries package where SDK types are shared
uCart Universal Widget SDK — The embeddable commerce widget (similar pattern, different scope)
Malet Navigation Architecture — How StorefrontRenderer and the Vertical system work
Owner Destinations — The Deck, Register & Pricing — Where Malet Owners manage their presence
Gateway Rate Limiting — Platform-wide rate limiting that complements per-app limits
User Guide: Designing Your Malet Storefront — User-facing guide for the Track 1 decoration system SPA loaded in sandboxed iframe""" APP }


All existing Malets have `maletType: VERTICAL` by default. The field is set when a Malet Owner opts into the developer track via [The Studio](/owner-destinations) (future).

---

## Related

- [Shared Query Package (@ngwenya/queries)](/shared-query-package) — The queries package where SDK types are shared
- [uCart Universal Widget SDK](/ucart-embedded-widget) — The embeddable commerce widget (similar pattern, different scope)
- [Malet Navigation Architecture](/malet-navigation) — How StorefrontRenderer and the Vertical system work
- [Owner Destinations — The Deck, Register & Pricing](/owner-destinations) — Where Malet Owners manage their presence
- [Gateway Rate Limiting](/gateway-rate-limiting) — Platform-wide rate limiting that complements per-app limits
- [User Guide: Designing Your Malet Storefront](https://support.mallnline.com/designing-your-malet-storefront) — User-facing guide for the Track 1 decoration system