@fepro/workhub-app-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Future Edge Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @fepro/workhub-app-sdk
+
+Client SDK for apps embedded inside the WorkHub portal.
+
+## Install
+
+```bash
+npm install @fepro/workhub-app-sdk
+# or
+pnpm add @fepro/workhub-app-sdk
+# or
+yarn add @fepro/workhub-app-sdk
+```
+
+## The bundle format
+
+A WorkHub developer-app is a `.zip` archive with this layout:
+
+```
+my-app.zip
+├── workhub.json     ← manifest (required, at root)
+├── index.html       ← entry HTML (or whatever `entry` in the manifest names)
+└── assets/
+    ├── app.js
+    └── app.css
+```
+
+### `workhub.json`
+
+```json
+{
+  "key": "my-tools",
+  "name": "My Tools",
+  "version": "1.0.0",
+  "description": "Internal tools dashboard",
+  "entry": "index.html",
+  "icon": "assets/icon.svg",
+  "scopes": [
+    "identity:read",
+    "storage:read",
+    "storage:write",
+    "notifications:send",
+    "events:listen"
+  ]
+}
+```
+
+| field | purpose |
+| --- | --- |
+| `key` | stable identifier; new uploads with the same `key` upgrade in place |
+| `version` | informational; surfaced in the upload list |
+| `entry` | path to the entry HTML (default `index.html`) |
+| `scopes` | capabilities the app needs; operator approves at upload |
+
+## Using the SDK
+
+```ts
+import { workhub } from '@fepro/workhub-app-sdk';
+
+// On boot
+const me = await workhub.identity.current();
+console.log(`Hi ${me.user?.displayName}, you're in ${me.tenant?.name}`);
+
+// Storage — KV scoped to (tenant, installation)
+await workhub.storage.set('lastView', { page: 7 });
+const last = await workhub.storage.get<{ page: number }>('lastView');
+
+// Toast
+await workhub.notifications.toast('Saved!', { variant: 'success' });
+
+// Listen for theme changes
+workhub.events.on('theme:change', ({ mode }) => document.body.dataset.theme = mode);
+
+// Escape hatch — call any /v1 endpoint
+const dbs = await workhub.api.call('GET /v1/databases');
+```
+
+## Scopes
+
+| scope | grants |
+| --- | --- |
+| `identity:read` | `workhub.identity.current()` |
+| `storage:read` | `workhub.storage.get/list` |
+| `storage:write` | `workhub.storage.set/delete` |
+| `notifications:send` | `workhub.notifications.toast` |
+| `events:listen` | `workhub.events.on` |
+| `api:proxy` | `workhub.api.call(...)` — gated on the user's existing permissions |
+
+## Upload
+
+Upload via the portal at **/apps/development → Upload bundle**, or via the API:
+
+```bash
+curl -X POST https://your-host/v1/apps/dev/upload \
+  -H "Authorization: Bearer $TOKEN" \
+  -F bundle=@my-app.zip
+```
+
+After upload, the app appears in the sidebar under **Apps** and at `/apps/<slug>`.

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fepro/workhub-app-sdk — client SDK for apps embedded
+ * inside the WorkHub portal.
+ *
+ * Apps run as a sandboxed iframe served from /v1/apps/runtime/<installationId>/.
+ * They cannot call the WorkHub API directly — every request crosses the
+ * iframe boundary via `window.postMessage` to the host portal, which
+ * validates the request against the manifest's declared scopes and forwards
+ * it to the API. The SDK is the typed, ergonomic wrapper for that channel.
+ *
+ * Usage:
+ *
+ *   import { workhub } from '@fepro/workhub-app-sdk';
+ *
+ *   const me  = await workhub.identity.current();
+ *   await workhub.storage.set('lastView', { page: 7 });
+ *   await workhub.notifications.toast('Saved');
+ *   workhub.events.on('theme:change', applyTheme);
+ *
+ * Capability scopes (declared in workhub.json `scopes`) are enforced by
+ * the host bridge, not here — the SDK fires the request, the host either
+ * returns a result or rejects with `ERR_SCOPE_DENIED`.
+ */
+export interface Identity {
+    user: {
+        id: string;
+        displayName: string | null;
+        email: string | null;
+    } | null;
+    tenant: {
+        id: string;
+        name: string;
+    } | null;
+    installation: {
+        id: string;
+        slug: string;
+        displayName: string;
+    };
+    manifest: unknown;
+    scopes: string[];
+}
+export type StorageValue = unknown;
+export interface StorageEntry {
+    key: string;
+    value: StorageValue;
+    updatedAt: string;
+}
+export type WorkhubEventName = 'theme:change' | 'route:change' | 'tenant:switch';
+export interface WorkhubEventPayload {
+    'theme:change': {
+        mode: 'light' | 'dark';
+    };
+    'route:change': {
+        path: string;
+    };
+    'tenant:switch': {
+        tenantId: string;
+    };
+}
+export declare const workhub: {
+    /** Identity — read-only user / tenant / installation context. */
+    readonly identity: {
+        readonly current: () => Promise<Identity>;
+    };
+    /** KV storage scoped to (tenant, installation). Survives reloads but
+     *  not uninstall. ttlSeconds is optional — omit for permanent. */
+    readonly storage: {
+        readonly get: <T = unknown>(key: string) => Promise<T | null>;
+        readonly set: <T = unknown>(key: string, value: T, opts?: {
+            ttlSeconds?: number;
+        }) => Promise<void>;
+        readonly delete: (key: string) => Promise<void>;
+        readonly list: (prefix?: string) => Promise<StorageEntry[]>;
+    };
+    /** Host-rendered UI primitives — keep apps visually consistent without
+     *  every app having to ship its own toast component. */
+    readonly notifications: {
+        readonly toast: (message: string, opts?: {
+            variant?: "info" | "success" | "warning" | "danger";
+        }) => Promise<void>;
+    };
+    /** Pub/sub for host → app events. The host emits when relevant
+     *  (theme switch, route change, tenant switch). */
+    readonly events: {
+        readonly on: {
+            <T extends WorkhubEventName>(name: T, cb: (payload: WorkhubEventPayload[T]) => void): () => void;
+            (name: string, cb: (payload: unknown) => void): () => void;
+        };
+    };
+    /** Escape hatch — call any /v1/* verb the user has permission for, gated
+     *  on the `api:proxy` scope at the host bridge. As we identify common
+     *  verbs they graduate into typed SDK methods. */
+    readonly api: {
+        readonly call: <T = unknown>(verb: string, body?: unknown) => Promise<T>;
+    };
+};
+export default workhub;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAChF,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5C,YAAY,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAQ,MAAM,CAAC;IAClB,KAAK,EAAM,YAAY,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,cAAc,GACd,eAAe,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAG;QAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAA;KAAE,CAAC;IAC5C,cAAc,EAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,eAAe,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAsGD,eAAO,MAAM,OAAO;IAClB,iEAAiE;;gCAEpD,OAAO,CAAC,QAAQ,CAAC;;IAK9B;sEACkE;;uBAE5D,CAAC,iBAAsB,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;uBAGjD,CAAC,iBAAsB,MAAM,SAAS,CAAC,SAAS;YAAE,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,KAAG,OAAO,CAAC,IAAI,CAAC;+BAG/E,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iCAGpB,MAAM,KAAG,OAAO,CAAC,YAAY,EAAE,CAAC;;IAKhD;4DACwD;;kCAEvC,MAAM,SAAS;YAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;SAAE,KAAG,OAAO,CAAC,IAAI,CAAC;;IAKvG;uDACmD;;;aApDhD,CAAC,SAAS,gBAAgB,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;mBACzF,MAAM,MAAM,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;;;IAwD5D;;sDAEkD;;wBAE3C,CAAC,kBAAkB,MAAM,SAAS,OAAO,KAAG,OAAO,CAAC,CAAC,CAAC;;CAIrD,CAAC;AAGX,eAAe,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,147 @@
+/**
+ * @fepro/workhub-app-sdk — client SDK for apps embedded
+ * inside the WorkHub portal.
+ *
+ * Apps run as a sandboxed iframe served from /v1/apps/runtime/<installationId>/.
+ * They cannot call the WorkHub API directly — every request crosses the
+ * iframe boundary via `window.postMessage` to the host portal, which
+ * validates the request against the manifest's declared scopes and forwards
+ * it to the API. The SDK is the typed, ergonomic wrapper for that channel.
+ *
+ * Usage:
+ *
+ *   import { workhub } from '@fepro/workhub-app-sdk';
+ *
+ *   const me  = await workhub.identity.current();
+ *   await workhub.storage.set('lastView', { page: 7 });
+ *   await workhub.notifications.toast('Saved');
+ *   workhub.events.on('theme:change', applyTheme);
+ *
+ * Capability scopes (declared in workhub.json `scopes`) are enforced by
+ * the host bridge, not here — the SDK fires the request, the host either
+ * returns a result or rejects with `ERR_SCOPE_DENIED`.
+ */
+const RPC_TIMEOUT_MS = 10_000;
+class HostChannel {
+    nextId = 1;
+    pending = new Map();
+    // Listeners: each event name maps to a Set of callbacks.
+    listeners = new Map();
+    // Lazy-init flag — we only attach the message listener on first use.
+    wired = false;
+    wire() {
+        if (this.wired)
+            return;
+        this.wired = true;
+        if (typeof window === 'undefined')
+            return;
+        window.addEventListener('message', (event) => {
+            const data = event.data;
+            if (!data || typeof data !== 'object' || data.__workhub === undefined)
+                return;
+            // We trust window.parent for message origin — the iframe is loaded by
+            // the portal, frame-ancestors CSP locks us to the portal origin, and
+            // we don't accept any verbs that would meaningfully harm the app from
+            // a malicious sibling.
+            if (data.__workhub === 'rpc-response') {
+                const pending = this.pending.get(data.id);
+                if (!pending)
+                    return;
+                this.pending.delete(data.id);
+                if (data.ok)
+                    pending.resolve(data.result);
+                else
+                    pending.reject(Object.assign(new Error(data.error?.message ?? 'rpc_failed'), { code: data.error?.code ?? 'unknown' }));
+            }
+            else if (data.__workhub === 'rpc-event') {
+                const set = this.listeners.get(data.name);
+                if (!set)
+                    return;
+                for (const cb of set) {
+                    try {
+                        cb(data.payload);
+                    }
+                    catch { /* swallow listener errors */ }
+                }
+            }
+        });
+    }
+    call(verb, payload) {
+        this.wire();
+        if (typeof window === 'undefined' || window.parent === window) {
+            return Promise.reject(new Error('not_embedded: workhub SDK only works inside the portal iframe'));
+        }
+        const id = String(this.nextId++);
+        const msg = { __workhub: 'rpc-request', id, verb, payload };
+        window.parent.postMessage(msg, '*');
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                reject(Object.assign(new Error(`rpc_timeout: ${verb}`), { code: 'timeout' }));
+            }, RPC_TIMEOUT_MS);
+            this.pending.set(id, {
+                resolve: (v) => { clearTimeout(timeout); resolve(v); },
+                reject: (e) => { clearTimeout(timeout); reject(e); },
+            });
+        });
+    }
+    on(name, cb) {
+        this.wire();
+        let set = this.listeners.get(name);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(name, set);
+        }
+        set.add(cb);
+        return () => set.delete(cb);
+    }
+}
+const channel = new HostChannel();
+// ─── Surface ────────────────────────────────────────────────────────────────
+export const workhub = {
+    /** Identity — read-only user / tenant / installation context. */
+    identity: {
+        current() {
+            return channel.call('identity.current', {});
+        },
+    },
+    /** KV storage scoped to (tenant, installation). Survives reloads but
+     *  not uninstall. ttlSeconds is optional — omit for permanent. */
+    storage: {
+        get(key) {
+            return channel.call('storage.get', { key });
+        },
+        set(key, value, opts) {
+            return channel.call('storage.set', { key, value, ttlSeconds: opts?.ttlSeconds });
+        },
+        delete(key) {
+            return channel.call('storage.delete', { key });
+        },
+        list(prefix) {
+            return channel.call('storage.list', { prefix });
+        },
+    },
+    /** Host-rendered UI primitives — keep apps visually consistent without
+     *  every app having to ship its own toast component. */
+    notifications: {
+        toast(message, opts) {
+            return channel.call('notifications.toast', { message, variant: opts?.variant ?? 'info' });
+        },
+    },
+    /** Pub/sub for host → app events. The host emits when relevant
+     *  (theme switch, route change, tenant switch). */
+    events: {
+        on: channel.on.bind(channel),
+    },
+    /** Escape hatch — call any /v1/* verb the user has permission for, gated
+     *  on the `api:proxy` scope at the host bridge. As we identify common
+     *  verbs they graduate into typed SDK methods. */
+    api: {
+        call(verb, body) {
+            return channel.call('api.call', { verb, body });
+        },
+    },
+};
+// Default export for ergonomic single-import usage.
+export default workhub;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@fepro/workhub-app-sdk",
+  "version": "0.1.0",
+  "description": "Client SDK for apps embedded in WorkHub. Use it inside an iframe app to call back into the host (identity, storage, notifications, events, API proxy).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "workhub",
+    "sdk",
+    "iframe",
+    "postmessage",
+    "tenant",
+    "saas"
+  ],
+  "homepage": "https://workhub.dev/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/futureedgetechnologies/workhub.git",
+    "directory": "packages/app-sdk"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,204 @@
+/**
+ * @fepro/workhub-app-sdk — client SDK for apps embedded
+ * inside the WorkHub portal.
+ *
+ * Apps run as a sandboxed iframe served from /v1/apps/runtime/<installationId>/.
+ * They cannot call the WorkHub API directly — every request crosses the
+ * iframe boundary via `window.postMessage` to the host portal, which
+ * validates the request against the manifest's declared scopes and forwards
+ * it to the API. The SDK is the typed, ergonomic wrapper for that channel.
+ *
+ * Usage:
+ *
+ *   import { workhub } from '@fepro/workhub-app-sdk';
+ *
+ *   const me  = await workhub.identity.current();
+ *   await workhub.storage.set('lastView', { page: 7 });
+ *   await workhub.notifications.toast('Saved');
+ *   workhub.events.on('theme:change', applyTheme);
+ *
+ * Capability scopes (declared in workhub.json `scopes`) are enforced by
+ * the host bridge, not here — the SDK fires the request, the host either
+ * returns a result or rejects with `ERR_SCOPE_DENIED`.
+ */
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export interface Identity {
+  user:   { id: string; displayName: string | null; email: string | null } | null;
+  tenant: { id: string; name: string } | null;
+  installation: { id: string; slug: string; displayName: string };
+  manifest: unknown;
+  scopes: string[];
+}
+
+export type StorageValue = unknown;
+
+export interface StorageEntry {
+  key:       string;
+  value:     StorageValue;
+  updatedAt: string;
+}
+
+export type WorkhubEventName =
+  | 'theme:change'
+  | 'route:change'
+  | 'tenant:switch';
+
+export interface WorkhubEventPayload {
+  'theme:change':  { mode: 'light' | 'dark' };
+  'route:change':  { path: string };
+  'tenant:switch': { tenantId: string };
+}
+
+// ─── postMessage envelope ────────────────────────────────────────────────────
+
+interface RpcRequest {
+  __workhub: 'rpc-request';
+  id:        string;
+  verb:      string;
+  payload:   unknown;
+}
+
+interface RpcResponse {
+  __workhub: 'rpc-response';
+  id:        string;
+  ok:        boolean;
+  result?:   unknown;
+  error?:    { code: string; message: string };
+}
+
+interface RpcEvent {
+  __workhub: 'rpc-event';
+  name:      string;
+  payload:   unknown;
+}
+
+type IncomingMessage = RpcResponse | RpcEvent;
+
+const RPC_TIMEOUT_MS = 10_000;
+
+class HostChannel {
+  private nextId = 1;
+  private pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  // Listeners: each event name maps to a Set of callbacks.
+  private listeners = new Map<string, Set<(payload: unknown) => void>>();
+  // Lazy-init flag — we only attach the message listener on first use.
+  private wired = false;
+
+  private wire(): void {
+    if (this.wired) return;
+    this.wired = true;
+    if (typeof window === 'undefined') return;
+    window.addEventListener('message', (event: MessageEvent) => {
+      const data = event.data as IncomingMessage | undefined;
+      if (!data || typeof data !== 'object' || (data as { __workhub?: string }).__workhub === undefined) return;
+      // We trust window.parent for message origin — the iframe is loaded by
+      // the portal, frame-ancestors CSP locks us to the portal origin, and
+      // we don't accept any verbs that would meaningfully harm the app from
+      // a malicious sibling.
+      if (data.__workhub === 'rpc-response') {
+        const pending = this.pending.get(data.id);
+        if (!pending) return;
+        this.pending.delete(data.id);
+        if (data.ok) pending.resolve(data.result);
+        else pending.reject(Object.assign(new Error(data.error?.message ?? 'rpc_failed'), { code: data.error?.code ?? 'unknown' }));
+      } else if (data.__workhub === 'rpc-event') {
+        const set = this.listeners.get(data.name);
+        if (!set) return;
+        for (const cb of set) {
+          try { cb(data.payload); } catch { /* swallow listener errors */ }
+        }
+      }
+    });
+  }
+
+  call<T>(verb: string, payload: unknown): Promise<T> {
+    this.wire();
+    if (typeof window === 'undefined' || window.parent === window) {
+      return Promise.reject(new Error('not_embedded: workhub SDK only works inside the portal iframe'));
+    }
+    const id = String(this.nextId++);
+    const msg: RpcRequest = { __workhub: 'rpc-request', id, verb, payload };
+    window.parent.postMessage(msg, '*');
+    return new Promise<T>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(Object.assign(new Error(`rpc_timeout: ${verb}`), { code: 'timeout' }));
+      }, RPC_TIMEOUT_MS);
+      this.pending.set(id, {
+        resolve: (v) => { clearTimeout(timeout); resolve(v as T); },
+        reject:  (e) => { clearTimeout(timeout); reject(e); },
+      });
+    });
+  }
+
+  on<T extends WorkhubEventName>(name: T, cb: (payload: WorkhubEventPayload[T]) => void): () => void;
+  on(name: string, cb: (payload: unknown) => void): () => void;
+  on(name: string, cb: (payload: unknown) => void): () => void {
+    this.wire();
+    let set = this.listeners.get(name);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(name, set);
+    }
+    set.add(cb);
+    return () => set!.delete(cb);
+  }
+}
+
+const channel = new HostChannel();
+
+// ─── Surface ────────────────────────────────────────────────────────────────
+
+export const workhub = {
+  /** Identity — read-only user / tenant / installation context. */
+  identity: {
+    current(): Promise<Identity> {
+      return channel.call<Identity>('identity.current', {});
+    },
+  },
+
+  /** KV storage scoped to (tenant, installation). Survives reloads but
+   *  not uninstall. ttlSeconds is optional — omit for permanent. */
+  storage: {
+    get<T = StorageValue>(key: string): Promise<T | null> {
+      return channel.call<T | null>('storage.get', { key });
+    },
+    set<T = StorageValue>(key: string, value: T, opts?: { ttlSeconds?: number }): Promise<void> {
+      return channel.call<void>('storage.set', { key, value, ttlSeconds: opts?.ttlSeconds });
+    },
+    delete(key: string): Promise<void> {
+      return channel.call<void>('storage.delete', { key });
+    },
+    list(prefix?: string): Promise<StorageEntry[]> {
+      return channel.call<StorageEntry[]>('storage.list', { prefix });
+    },
+  },
+
+  /** Host-rendered UI primitives — keep apps visually consistent without
+   *  every app having to ship its own toast component. */
+  notifications: {
+    toast(message: string, opts?: { variant?: 'info' | 'success' | 'warning' | 'danger' }): Promise<void> {
+      return channel.call<void>('notifications.toast', { message, variant: opts?.variant ?? 'info' });
+    },
+  },
+
+  /** Pub/sub for host → app events. The host emits when relevant
+   *  (theme switch, route change, tenant switch). */
+  events: {
+    on: channel.on.bind(channel),
+  },
+
+  /** Escape hatch — call any /v1/* verb the user has permission for, gated
+   *  on the `api:proxy` scope at the host bridge. As we identify common
+   *  verbs they graduate into typed SDK methods. */
+  api: {
+    call<T = unknown>(verb: string, body?: unknown): Promise<T> {
+      return channel.call<T>('api.call', { verb, body });
+    },
+  },
+} as const;
+
+// Default export for ergonomic single-import usage.
+export default workhub;