@fepro/workhub-app-sdk 0.2.0 → 0.4.1

package/AGENTS.md

@@ -5,6 +5,63 @@
 > [README.md](./README.md). Both describe the same SDK; this one is denser,
 > includes complete worked examples, and lists the gotchas that bite agents.
 
+## Two SDKs — pick the right one
+
+WorkHub publishes two separate npm packages. Pick by where your code runs:
+
+| Package | Runtime | When to use |
+|---|---|---|
+| **`@fepro/workhub-app-sdk`** (this doc) | Browser, inside the iframe | Frontend SPA — identity, storage, notifications, events, API proxy. Calls into the host via postMessage. |
+| **`@fepro/workhub-app-backend`** | Node, inside a workspace deployment | Server-side routes — JWT verification, scope checks, tenant-scoped database. The frontend reaches it via `workhub.backend.fetch()`. |
+
+A typical app uses both: the frontend SDK in the iframe SPA, the backend SDK
+inside a workspace deployment. They pair through `workhub.backend.fetch(...)`,
+which routes to the deployed workspace and attaches identity + scopes.
+
+- Frontend offline copy: <https://workhubplatform.io/sdk/download>
+- Backend offline copy: <https://workhubplatform.io/sdk/download/backend>
+- Backend reference: see the README inside the backend package — surface,
+  examples, and the deploy lifecycle (upload → auto-build → review → deploy → install).
+
+> **Critical for agents generating backend workspaces:** developers do **NOT**
+> ship a Dockerfile. The platform compiles a vetted Dockerfile from
+> `workspace.json#backend.runtime`. If the user asks you to write a backend
+> workspace, do **not** generate a Dockerfile. The runtime + start command in
+> `workspace.json` is the entire build contract. Supported runtimes are
+> `node:20`, `node:22`, `bun:1`, `python:3.11`, `python:3.12`. A minimal
+> backend `workspace.json#backend` looks like:
+>
+> ```json
+> {
+>   "runtime": "node:20",
+>   "start":   "node dist/index.js"
+> }
+> ```
+>
+> The container's listen port is platform-fixed. Code your server to
+> read `process.env.PORT` (which the platform sets) and bind to it —
+> every framework defaults to this. Don't put `port` in the manifest;
+> it's accepted for backwards compat but ignored.
+>
+> The bundle layout for a backend workspace:
+>
+> ```
+> my-workspace.zip
+> ├── workspace.json
+> ├── backend/
+> │   ├── package.json
+> │   ├── package-lock.json
+> │   └── src/index.ts
+> └── apps/<key>/workhub.json + dist/...
+> ```
+>
+> Lockfile-first install caching is auto-detected: presence of
+> `package-lock.json` → `npm ci`, `pnpm-lock.yaml` → `pnpm install --frozen-lockfile`,
+> `yarn.lock` → `yarn install --frozen-lockfile`, `bun.lockb` → `bun install --frozen-lockfile`.
+
+The rest of this file is about the **frontend** SDK. If you only need server
+routes (no iframe SPA), stop here and read the backend SDK README instead.
+
 ## What you are building
 
 A **WorkHub app** is a `.zip` archive containing a static SPA + a manifest.
@@ -96,19 +153,71 @@ workhub.storage.set<T>(key: string, value: T, opts?: { ttlSeconds?: number }): P
 workhub.storage.delete(key: string): Promise<void>;
 workhub.storage.list(prefix?: string): Promise<Array<{ key: string; value: unknown; updatedAt: string }>>;
 
+// Files — object/blob storage (bytes), NOT the KV above (since 0.4) ----
+//   Persist the returned stable `key`; resolve back to a URL with getUrl(key).
+workhub.files.upload(file: Blob, opts?: { filename?: string; keyHint?: string }): Promise<{ key: string }>;
+workhub.files.presignUpload(opts: { filename: string; contentType?: string; keyHint?: string }):
+  Promise<{ url: string; key: string; headers?: Record<string, string> }>;
+workhub.files.getUrl(key: string, opts?: { expiresInSeconds?: number }): Promise<{ url: string }>;
+workhub.files.delete(key: string): Promise<void>;
+workhub.files.list(prefix?: string): Promise<Array<{ key: string; size: number; lastModified: string | null }>>;
+
+// Org units — sub-tenants / companies (multi-company, since 0.4) -------
+workhub.org.units(): Promise<{ active: OrgUnit | null; units: OrgUnit[] }>;  // OrgUnit = { id, name, parentId, path }
+workhub.org.switch(unitId: string): Promise<void>;  // portal re-issues identity + emits 'org-unit:switch'
+
 // Notifications ---------------------------------------------
 workhub.notifications.toast(
   message: string,
   opts?: { variant?: 'info' | 'success' | 'warning' | 'danger' },
 ): Promise<void>;
 
-// Events — host pushes these as the user navigates / themes -
-type Names = 'theme:change' | 'route:change' | 'tenant:switch';
-workhub.events.on(name: Names, cb: (payload: unknown) => void): () => void; // returns unsubscribe
+// Locale — the portal's active language/timezone (since 0.3) -
+workhub.locale.current(): Promise<{ tag: string; language: string; timezone: string }>;
+
+// Theme — full token set, not just mode (since 0.3) ---------
+workhub.theme.current(): Promise<{
+  mode: 'light' | 'dark';
+  brand: { primary: string; secondary: string };   // #rrggbb
+  cssVars: Record<string, string>;                  // apply as --<name>
+}>;
+
+// Events — host pushes these; events.on returns an unsubscribe fn
+//   Host events:
+//     'theme:change'   → ThemeTokens (mode + brand + cssVars)   [was {mode} pre-0.3]
+//     'locale:change'  → { tag, language, timezone }            [since 0.3]
+//     'route:change'   → { path }
+//     'tenant:switch'  → { tenantId }
+//     'org-unit:switch'→ { unit: OrgUnit }                      [since 0.4]
+//   App events (since 0.3): your backend's ctx.events.emit('customer.created', …)
+//   arrives as 'app:customer.created'. Augment WorkhubAppEventPayload for types.
+workhub.events.on(name: string, cb: (payload: any) => void): () => void;
 
 // Generic API escape hatch ----------------------------------
 workhub.api.call<T>(verb: string, body?: unknown): Promise<T>;
 //   verb format: "METHOD /v1/path"   e.g. "GET /v1/databases"
+
+// Your own workspace backend (pairs with @fepro/workhub-app-backend) -
+workhub.backend.fetch(path: string, init?: RequestInit): Promise<Response>;
+workhub.backend.call<T>(path: string, opts?: {            // JSON in/out wrapper (since 0.3)
+  method?: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE';
+  body?: unknown; headers?: Record<string,string>;
+  idempotencyKey?: string;                                 // safe retries on idempotent routes
+}): Promise<T>;
+//   Throws `WorkhubError { code, message, status?, requestId?, details? }` on a
+//   4xx/5xx — branch on err.code (e.g. 'rate_limited', 'not_found') not status.
+//   backend.* needs `identity:read` (it resolves the installation id first).
+```
+
+### Typing your app events (since 0.3)
+
+```ts
+declare module '@fepro/workhub-app-sdk' {
+  interface WorkhubAppEventPayload {
+    'app:customer.created': { id: string; displayName: string };
+  }
+}
+workhub.events.on('app:customer.created', (e) => e.displayName /* typed */);
 ```
 
 ## Scope → method matrix
@@ -119,9 +228,15 @@ workhub.api.call<T>(verb: string, body?: unknown): Promise<T>;
 | `storage:read`       | `storage.get`, `storage.list`            |
 | `storage:write`      | `storage.set`, `storage.delete`          |
 | `notifications:send` | `notifications.toast`                    |
-| `events:listen`      | `events.on(...)`                         |
+| `events:listen`      | `events.on(...)` — host events AND `app:*` backend events |
+| `storage:files`      | `files.upload`, `files.presignUpload`, `files.getUrl`, `files.delete`, `files.list` (since 0.4) |
+| `org:read`           | `org.units()`, `org.switch()` — multi-company (since 0.4) |
 | `api:proxy`          | `api.call(verb, body)` (still gated on the user's existing /v1 permissions) |
 
+`locale.current()` and `theme.current()` are **ambient** — no scope needed
+(the portal pushes theme/locale to every embedded app anyway). `backend.fetch`
+/ `backend.call` need `identity:read` (they resolve the installation first).
+
 ## Worked examples
 
 ### Example 1 — Minimal hello app (vanilla, zero deps)
@@ -237,7 +352,7 @@ This is a **production security boundary**. A malicious bundle uploaded by tenan
 6. **Storage values are JSON-serialisable.** Functions, `BigInt`, `Date` (use ISO strings), and circular references all fail. Storage payload max is whatever Postgres `jsonb` accepts (~1 GB practical, but keep entries small).
 7. **`storage.list(prefix)`** uses `LIKE 'prefix%'` matching — pick a prefix scheme that doesn't collide.
 8. **Events fire from the host, not from your code.** `workhub.events.on('theme:change', ...)` returns an unsubscribe function — wire it into your component cleanup if you have one.
-9. **CSP locks `connect-src` to `'self'`** by default, meaning `fetch()` to third-party origins from inside the iframe is blocked. Use `workhub.api.call(...)` to reach `/v1/*`. For external HTTP, the host would need a `proxy:fetch` scope (not in v1).
+9. **CSP locks `connect-src` to `'self'`** so `fetch()` to third-party origins from the iframe is blocked — and always will be (it's a security boundary). To call an external API (Stripe, a webhook, a geocoder), do it from your **workspace backend** and expose a route the frontend hits via `workhub.backend.call(...)`. The backend declares allowed destinations in `workspace.json#egress` and uses `ctx.fetch` (see the backend SDK README). Don't try to fetch third parties from the iframe.
 10. **Bundle URLs are short-cached (60s).** Iterate by re-uploading; the bundle key includes a content hash so a fresh upload gets a fresh URL automatically.
 11. **Always import the SDK from `/sdk.js`** — never `https://esm.sh/...`, `https://cdn.jsdelivr.net/...`, or any other CDN. The iframe's CSP blocks them. `/sdk.js` is the platform's same-origin SDK and works under sandbox.
 
@@ -251,6 +366,8 @@ This is a **production security boundary**. A malicious bundle uploaded by tenan
 | `unknown_verb`     | SDK method not implemented in the bridge              | likely an SDK/host version mismatch       |
 | `bridge_400/4xx`   | API rejected the underlying call                      | inspect `error.message` for details       |
 | `http_403`         | `api.call` succeeded but the user lacks `/v1` perms   | tenant grants more permissions to the user |
+| `WorkhubError`     | thrown by `backend.call` on a 4xx/5xx — has `.code` (your backend's AppError code), `.status`, `.requestId` | branch on `err.code`; quote `requestId` in bug reports |
+| `not_installed`    | `backend.fetch/call` but the app isn't installed under a workspace | only developer-workspace apps have a backend |
 
 ## Starter template (copy verbatim)
 

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# @fepro/workhub-app-sdk — Changelog
+
+## 0.4.1
+
+Resolves BMS ERP request #31 — `workhub.identity.current()` second-call
+race that surfaced as `rpc_timeout: identity.current` toasts in apps that
+called `identity.current()` more than once per session (e.g. BMS ERP
+0.5.0 calling it from both App.svelte boot and openSse()).
+
+### Fixed
+- **`workhub.identity.current()` caches the first successful response.**
+  Identity is per-session-immutable (bundle token + JWT minted once at
+  iframe boot; user / tenant / installation cannot change without a full
+  reload), so the second call is a free synchronous return from cache.
+  Previous behaviour issued a fresh postMessage RPC every time, which
+  occasionally timed out against the host bridge under cold-start
+  contention.
+- **In-flight de-duplication** — concurrent callers during cold start
+  (e.g. `Promise.all([identity.current(), identity.current()])`) share a
+  single RPC instead of racing it.
+- **Cache cleared on failure** so a subsequent call actually retries
+  instead of latching onto a poisoned pending promise.
+
+No API change; same return shape, same `Identity` type. Apps that already
+worked keep working; apps that called it twice stop tripping the bridge
+race.
+
+## 0.4.0
+
+Additive — existing apps keep working.
+
+### Added
+- **`workhub.org`** — organization units (sub-tenants / companies):
+  `units()` lists accessible units + the active one; `switch(unitId)` asks the
+  portal to change the active unit. Pairs with the new `org-unit:switch` host
+  event and the backend `ctx.org` claim. (BMS ERP request #22, frontend half.)
+- **`org-unit:switch` host event** — fires when the user switches the active org
+  unit; the portal re-issues the identity token so the next `workhub.backend.*`
+  call is authorized for the new unit.
+- **`workhub.files`** — object/file storage (bytes), distinct from `workhub.storage`
+  (small JSON KV): `presignUpload()`, `upload(file)`, `getUrl(key)`, `delete(key)`,
+  `list(prefix)`. The host bridge mints presigned URLs so the browser uploads/
+  downloads directly. Persist the returned stable `key`. (BMS ERP request #25,
+  frontend half.)
+
+### Platform-side obligations
+- Host-bridge verbs: `org.units`, `org.switch`, `files.presignUpload`,
+  `files.getUrl`, `files.delete`, `files.list`.
+
+## 0.3.0
+- Identity, KV storage, notifications/toast, theme bridge, locale, host + app
+  events (`app:*`), API proxy, `workhub.backend.fetch/call`.

package/README.md

@@ -3,7 +3,7 @@
 Client SDK for apps embedded inside the WorkHub portal.
 
 > **Building with an AI agent?** See [AGENTS.md](./AGENTS.md) (or fetch
-> [https://workhub.dev/sdk/agents.md](https://workhub.dev/sdk/agents.md))
+> [https://workhubplatform.io/sdk/agents.md](https://workhubplatform.io/sdk/agents.md))
 > for a dense, machine-friendly reference with the full SDK surface, three
 > worked examples, the gotcha catalogue, and a copy-paste starter template.
 
@@ -90,11 +90,56 @@ 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);
+// Listen for theme changes — payload now carries full token set
+workhub.events.on('theme:change', (tokens) => {
+  document.documentElement.dataset.theme = tokens.mode;
+  for (const [k, v] of Object.entries(tokens.cssVars)) {
+    document.documentElement.style.setProperty(`--${k}`, v);
+  }
+});
+
+// Locale propagation — react to the user's language preference
+const locale = await workhub.locale.current();           // { tag, language, timezone }
+workhub.events.on('locale:change', (next) => i18n.use(next.tag));
+
+// App-domain events — emitted by your backend via ctx.events.emit(...)
+workhub.events.on('app:customer.created', (e) => refresh());
 
 // Escape hatch — call any /v1 endpoint
 const dbs = await workhub.api.call('GET /v1/databases');
+
+// Call your own workspace backend — JSON in / JSON out, typed errors
+try {
+  const leads = await workhub.backend.call<Lead[]>('/leads');
+  const payment = await workhub.backend.call('/payments', {
+    method: 'POST',
+    body: { amount: 1200, currency: 'usd' },
+    idempotencyKey: crypto.randomUUID(),    // safe retries
+  });
+} catch (err) {
+  if (err instanceof WorkhubError && err.code === 'rate_limited') {
+    // backoff…
+  }
+}
+```
+
+### Typed app events
+
+The default `WorkhubAppEventPayload` interface is empty — augment it from
+your app's types module so each `events.on('app:...')` call gets type
+inference for the payload:
+
+```ts
+declare module '@fepro/workhub-app-sdk' {
+  interface WorkhubAppEventPayload {
+    'app:customer.created': { id: string; displayName: string };
+    'app:invoice.overdue':  { invoiceId: string; daysLate: number };
+  }
+}
+
+workhub.events.on('app:customer.created', (e) => {
+  e.displayName;   // ← inferred as string
+});
 ```
 
 ## Scopes
@@ -108,6 +153,50 @@ const dbs = await workhub.api.call('GET /v1/databases');
 | `events:listen` | `workhub.events.on` |
 | `api:proxy` | `workhub.api.call(...)` — gated on the user's existing permissions |
 
+## Content Security Policy & sandbox
+
+Your app runs in a **sandboxed iframe** with a strict CSP. Knowing the rules
+up front saves a debugging session — most "why won't my font/script load?"
+issues are the CSP doing its job.
+
+**Sandbox** (set by the host on the `<iframe>`): production grants only
+`allow-scripts allow-forms`. So your app can run JS and submit forms, but
+cannot do top-level navigation, open popups, or break out of the frame.
+(Local dev additionally grants `allow-same-origin` so cookies flow to the
+dev bundle server — production keeps the iframe on a separate origin and
+omits it.)
+
+**CSP** applied to your served bundle:
+
+| directive | value | what it means for you |
+| --- | --- | --- |
+| `frame-ancestors` | the portal origin | only the WorkHub portal can embed your app |
+| `default-src` | `'self' 'unsafe-inline' 'unsafe-eval' data: blob:` | scripts/styles must come from **your bundle** (inline is allowed); **no external origins** |
+| `img-src` | `'self' data: blob: https:` | images may load from any `https` origin |
+| `connect-src` | `'self'` | `fetch`/XHR/WebSocket only to your own origin |
+
+What this means in practice:
+
+- **Bundle everything.** External CDNs (Google Fonts, jsdelivr, unpkg, an
+  analytics snippet) are blocked — `default-src` has no external origins.
+  Self-host your fonts and vendor your scripts/styles into the bundle. Images
+  are the one exception: any `https` URL works.
+- **`workhub.backend.fetch()` / `workhub.backend.call()` work** — they hit
+  `/v1/apps/runtime/<id>/api…` on your own origin, which `connect-src 'self'`
+  permits. No extra config.
+- **You cannot call third-party APIs from the browser** (Stripe, a geocoder,
+  a webhook target) — `connect-src 'self'` blocks them. Call them from your
+  **workspace backend** instead and expose a route your frontend hits via
+  `workhub.backend.call(...)`. (Outbound egress from the backend is a
+  separate, server-side concern.)
+- Inline `<script>`/`<style>` and `eval` are allowed in the default policy
+  (most SPA bundlers need them), bounded by the sandbox. A stricter
+  no-`unsafe-inline`/no-`unsafe-eval` policy is applied to apps that opt in
+  (bundles that emit hashed/nonced inline code).
+
+CSP violations are reported to the platform (`report-uri`) and surfaced to
+operators, so a misbehaving app shows up in the apps-anomaly view.
+
 ## Upload
 
 Upload via the portal at **/apps/development → Upload bundle**, or via the API:

package/dist/index.d.ts

@@ -16,6 +16,9 @@
  *   await workhub.storage.set('lastView', { page: 7 });
  *   await workhub.notifications.toast('Saved');
  *   workhub.events.on('theme:change', applyTheme);
+ *   workhub.events.on('app:customer.created', (e) => refresh());
+ *   const { tokens } = await workhub.theme.current();
+ *   const locale = await workhub.locale.current();
  *
  * Capability scopes (declared in workhub.json `scopes`) are enforced by
  * the host bridge, not here — the SDK fires the request, the host either
@@ -45,23 +48,173 @@ export interface StorageEntry {
     value: StorageValue;
     updatedAt: string;
 }
-export type WorkhubEventName = 'theme:change' | 'route:change' | 'tenant:switch';
-export interface WorkhubEventPayload {
-    'theme:change': {
-        mode: 'light' | 'dark';
+/** Portal-level theme tokens — the portal forwards its active theme so apps
+ *  can repaint instead of guessing colors. Light/dark mode plus the tenant's
+ *  brand palette and a CSS-variable map ready for `<style>` injection. */
+export interface ThemeTokens {
+    mode: 'light' | 'dark';
+    /** Hex strings, lowercase, `#rrggbb`. */
+    brand: {
+        primary: string;
+        secondary: string;
     };
+    /** Map of CSS variable names (without the leading `--`) to values.
+     *  Apply via:
+     *    for (const [k, v] of Object.entries(tokens.cssVars))
+     *      document.documentElement.style.setProperty(`--${k}`, v);
+     */
+    cssVars: Record<string, string>;
+}
+export interface LocaleInfo {
+    /** BCP 47 tag, e.g. `en-US`, `fr-CA`. */
+    tag: string;
+    /** Convenience — the language subtag, e.g. `en`. */
+    language: string;
+    /** IANA timezone, e.g. `America/Toronto`. */
+    timezone: string;
+}
+/** Organization unit (sub-tenant / company / department). Mirrors the backend
+ *  SDK's `OrgUnit`. Resolves BMS ERP request #22 (frontend half). */
+export interface OrgUnit {
+    id: string;
+    name: string;
+    parentId: string | null;
+    /** Materialized path from the root unit, or null. */
+    path: string | null;
+}
+export interface OrgContext {
+    /** The unit the user is currently acting as, or null. */
+    active: OrgUnit | null;
+    /** All units this user may access (includes the active one). */
+    units: OrgUnit[];
+}
+/** Built-in portal-emitted events. */
+export type WorkhubHostEventName = 'theme:change' | 'route:change' | 'tenant:switch' | 'locale:change' | 'org-unit:switch';
+export interface WorkhubHostEventPayload {
+    'theme:change': ThemeTokens;
     'route:change': {
         path: string;
     };
     'tenant:switch': {
         tenantId: string;
     };
+    'locale:change': LocaleInfo;
+    /** The user switched the active org unit in the portal. The platform also
+     *  re-issues the identity token, so the next `workhub.backend.*` call is
+     *  authorized for the new unit. Re-fetch unit-scoped data on this event. */
+    'org-unit:switch': {
+        unit: OrgUnit;
+    };
+}
+/** App-domain events emitted by the workspace backend via `ctx.events.emit`.
+ *  Subscribe with `workhub.events.on('app:<kind>', cb)` — the prefix
+ *  separates host events from app events so the channel namespace stays
+ *  clean as more events graduate to the platform-emitted set.
+ *
+ *  Apps SHOULD declare a global module augmentation to type their event
+ *  payloads, e.g.:
+ *
+ *    declare module '@fepro/workhub-app-sdk' {
+ *      interface WorkhubAppEventPayload {
+ *        'app:customer.created': { id: string; displayName: string };
+ *      }
+ *    }
+ */
+export interface WorkhubAppEventPayload {
+    [key: `app:${string}`]: unknown;
+}
+export type WorkhubEventName = WorkhubHostEventName | `app:${string}`;
+export type WorkhubEventPayload = WorkhubHostEventPayload & WorkhubAppEventPayload;
+/** Typed error rethrown from RPC failures and backend.fetch() error envelopes.
+ *  `code` matches the backend SDK's `AppError.code`, so apps can branch on
+ *  string codes rather than http status. */
+export declare class WorkhubError extends Error {
+    readonly code: string;
+    readonly status: number | undefined;
+    readonly requestId: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, extras?: {
+        status?: number;
+        requestId?: string;
+        details?: Record<string, unknown>;
+    });
 }
 export declare const workhub: {
     /** Identity — read-only user / tenant / installation context. */
     readonly identity: {
         readonly current: () => Promise<Identity>;
     };
+    /** Session. `logout()` ends the WorkHub session by navigating the HOST (top)
+     *  window to the platform sign-out — the only exit for full-page / app-only
+     *  users who have no portal chrome. Fire-and-forget: the page unloads, so
+     *  there's no result to await. */
+    readonly auth: {
+        readonly logout: () => void;
+    };
+    /** Locale propagation — read the portal's active locale so the app can
+     *  match it. Apps SHOULD also subscribe to `locale:change` to update
+     *  live when the user switches languages. */
+    readonly locale: {
+        readonly current: () => Promise<LocaleInfo>;
+    };
+    /** Organization units (sub-tenants / companies). `units()` lists what the
+     *  user may access plus the active one; pair with `events.on('org-unit:switch')`
+     *  to keep an in-app company switcher in sync with the portal. The active
+     *  unit is also a signed claim on the backend (`ctx.org`), so authorization
+     *  rides the identity token — the frontend value is for display + switching.
+     *  Resolves BMS ERP request #22 (frontend half). */
+    readonly org: {
+        /** List accessible units + the active one. */
+        readonly units: () => Promise<OrgContext>;
+        /** Ask the portal to switch the active unit. The portal validates access,
+         *  re-issues the identity token, and emits `org-unit:switch`. */
+        readonly switch: (unitId: string) => Promise<void>;
+    };
+    /** Theme tokens — the portal pushes light/dark mode + the active tenant's
+     *  brand palette so embedded apps repaint without each maintaining their
+     *  own theme store. Combine with `events.on('theme:change')` for live
+     *  updates when the user toggles dark mode. */
+    readonly theme: {
+        readonly current: () => Promise<ThemeTokens>;
+    };
+    /** Object / file storage (bytes) — distinct from `storage` (small JSON KV).
+     *  Backed by the workspace's platform-provisioned bucket; the host bridge
+     *  mints presigned URLs so the browser uploads/downloads directly without
+     *  routing bytes through the portal. Persist the returned `key` (e.g. on a
+     *  row) and resolve it back to a URL with `getUrl(key)` when rendering.
+     *  Resolves BMS ERP request #25 (frontend half). */
+    readonly files: {
+        /** Get a presigned PUT URL + the stable key to persist. Upload the file
+         *  yourself with a plain `fetch(url, { method: 'PUT', body: file })`. */
+        readonly presignUpload: (opts: {
+            filename: string;
+            contentType?: string;
+            keyHint?: string;
+        }) => Promise<{
+            url: string;
+            key: string;
+            headers?: Record<string, string>;
+        }>;
+        /** Convenience: presign + PUT in one call. Returns the stable key. */
+        readonly upload: (file: Blob, opts?: {
+            filename?: string;
+            keyHint?: string;
+        }) => Promise<{
+            key: string;
+        }>;
+        /** Presigned, time-limited GET URL for a stored key. */
+        readonly getUrl: (key: string, opts?: {
+            expiresInSeconds?: number;
+        }) => Promise<{
+            url: string;
+        }>;
+        readonly delete: (key: string) => Promise<void>;
+        readonly list: (prefix?: string) => Promise<Array<{
+            key: string;
+            size: number;
+            lastModified: string | null;
+        }>>;
+    };
     /** KV storage scoped to (tenant, installation). Survives reloads but
      *  not uninstall. ttlSeconds is optional — omit for permanent. */
     readonly storage: {
@@ -79,8 +232,17 @@ export declare const workhub: {
             variant?: "info" | "success" | "warning" | "danger";
         }) => Promise<void>;
     };
-    /** Pub/sub for host → app events. The host emits when relevant
-     *  (theme switch, route change, tenant switch). */
+    /** Pub/sub.
+     *
+     *  Host events (`theme:change`, `route:change`, `tenant:switch`,
+     *  `locale:change`) come from the portal directly.
+     *
+     *  App events (`app:<kind>`) are emitted by the workspace backend via
+     *  `ctx.events.emit('customer.created', ...)`; the platform's tenant-event
+     *  bridge forwards them to subscribed iframes. Replaces the polling shim
+     *  documented in BMS ERP request #1.
+     *
+     *  Returns an unsubscribe function. */
     readonly events: {
         readonly on: {
             <T extends WorkhubEventName>(name: T, cb: (payload: WorkhubEventPayload[T]) => void): () => void;
@@ -108,6 +270,18 @@ export declare const workhub: {
          *  required. The host SDK builds the full URL `/v1/apps/runtime/<installationId>/api<path>`
          *  and uses same-origin credentialed fetch — no extra auth wiring. */
         readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+        /** Convenience wrapper — JSON in, JSON out, with automatic error
+         *  envelope detection. A 2xx response is parsed and returned. A 4xx/5xx
+         *  carrying a `__workhub_error: true` payload is rethrown as
+         *  `WorkhubError` so apps can `try/catch` by code instead of inspecting
+         *  the response object. Pass `idempotencyKey` to deduplicate retries on
+         *  idempotent backend routes. */
+        readonly call: <T = unknown>(path: string, opts?: {
+            method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+            body?: unknown;
+            headers?: Record<string, string>;
+            idempotencyKey?: string;
+        }) => Promise<T>;
     };
 };
 export default workhub;

package/dist/index.d.ts.map

@@ -1 +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;;IAK7D;;;;;;+CAM2C;;QAEzC;;;;;8EAKsE;+BACpD,MAAM,SAAS,WAAW,KAAG,OAAO,CAAC,QAAQ,CAAC;;CAgB1D,CAAC;AAGX,eAAe,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}