@fepro/workhub-app-sdk 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,318 @@
+# AGENTS.md — building WorkHub apps with AI assistance
+
+> Read this once, generate working apps in one shot. This file is optimised
+> for AI coding agents (Claude, GPT, Aider, Cursor, etc.). Humans prefer the
+> [README.md](./README.md). Both describe the same SDK; this one is denser,
+> includes complete worked examples, and lists the gotchas that bite agents.
+
+## What you are building
+
+A **WorkHub app** is a `.zip` archive containing a static SPA + a manifest.
+The host (WorkHub portal) renders it as a sandboxed iframe inside the
+tenant's `/apps/<slug>` route. Apps cannot call the WorkHub API directly —
+every cross-origin call goes through `@fepro/workhub-app-sdk`, which sends
+typed `postMessage` RPCs to the host bridge. The bridge enforces the
+manifest's declared scopes and forwards approved calls to `/v1/*`.
+
+## One-shot mental model
+
+```
+  zip                     post     bridge      api
+  ─────                   ────     ──────      ───
+  index.html  ◄── iframe ── │ ◄── postMessage ── workhub.identity.current()
+  workhub.json             │      │              ▼
+  assets/...               │      └─── HTTP ───► /v1/apps/bridge/context
+```
+
+The agent's job: produce `index.html` (or `dist/`) + `workhub.json`, zip them, upload.
+
+## Install
+
+The platform serves the SDK from the portal origin at **`/sdk.js`** — uploaded
+apps can load it directly without any build step or external CDN. This is the
+recommended path for hand-written and AI-generated bundles:
+
+```html
+<script type="module">
+  import { workhub } from '/sdk.js';
+</script>
+```
+
+For TypeScript projects with a build step:
+
+```bash
+npm install @fepro/workhub-app-sdk
+```
+
+```ts
+import { workhub } from '@fepro/workhub-app-sdk';
+```
+
+> Do **not** use cross-origin CDNs (esm.sh, jsdelivr, unpkg, etc.). Uploaded
+> apps run inside a sandboxed iframe whose CSP is `default-src 'self'`, so
+> external script loads are blocked. `/sdk.js` is same-origin and works.
+
+## Manifest spec — `workhub.json` (zip root)
+
+```json
+{
+  "key":         "lower-kebab-id",
+  "name":        "Display Name",
+  "version":     "1.0.0",
+  "description": "One-line summary",
+  "entry":       "index.html",
+  "icon":        "assets/icon.svg",
+  "scopes": [
+    "identity:read",
+    "storage:read",
+    "storage:write",
+    "notifications:send",
+    "events:listen",
+    "api:proxy"
+  ]
+}
+```
+
+Rules:
+- `key` must match `^[a-z0-9][a-z0-9-]*[a-z0-9]$` (2–80 chars). Stable identifier — re-uploads with the same key upgrade in place.
+- `entry` defaults to `index.html`. Path is relative to the zip root.
+- `scopes` is exact match — only declare what you actually call. Bridge rejects calls whose required scope is missing with `ERR_SCOPE_DENIED`.
+
+## SDK surface — every method, every type
+
+```ts
+// Identity ---------------------------------------------------
+workhub.identity.current(): Promise<{
+  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;       // your workhub.json snapshot
+  scopes:   string[];
+}>;
+
+// Storage — KV scoped to (tenant, installation) -------------
+workhub.storage.get<T = unknown>(key: string): Promise<T | null>;
+workhub.storage.set<T>(key: string, value: T, opts?: { ttlSeconds?: number }): Promise<void>;
+workhub.storage.delete(key: string): Promise<void>;
+workhub.storage.list(prefix?: string): Promise<Array<{ key: string; value: unknown; updatedAt: string }>>;
+
+// 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
+
+// Generic API escape hatch ----------------------------------
+workhub.api.call<T>(verb: string, body?: unknown): Promise<T>;
+//   verb format: "METHOD /v1/path"   e.g. "GET /v1/databases"
+```
+
+## Scope → method matrix
+
+| scope                | unlocks                                  |
+| -------------------- | ---------------------------------------- |
+| `identity:read`      | `identity.current()`                     |
+| `storage:read`       | `storage.get`, `storage.list`            |
+| `storage:write`      | `storage.set`, `storage.delete`          |
+| `notifications:send` | `notifications.toast`                    |
+| `events:listen`      | `events.on(...)`                         |
+| `api:proxy`          | `api.call(verb, body)` (still gated on the user's existing /v1 permissions) |
+
+## Worked examples
+
+### Example 1 — Minimal hello app (vanilla, zero deps)
+
+`workhub.json`:
+```json
+{
+  "key": "hello",
+  "name": "Hello App",
+  "version": "1.0.0",
+  "scopes": ["identity:read", "notifications:send"]
+}
+```
+
+`index.html`:
+```html
+<!doctype html>
+<html><body>
+  <h1 id="greeting">Loading…</h1>
+  <button id="ping">Toast</button>
+  <script type="module">
+    import { workhub } from '/sdk.js';
+    const me = await workhub.identity.current();
+    greeting.textContent = `Hi ${me.user?.displayName ?? 'there'} (${me.tenant?.name})`;
+    ping.onclick = () => workhub.notifications.toast('Hello from your app!', { variant: 'success' });
+  </script>
+</body></html>
+```
+
+### Example 2 — Persistent settings (TS + Vite)
+
+```ts
+import { workhub } from '@fepro/workhub-app-sdk';
+
+interface Settings { darkMode: boolean; pageSize: number }
+
+async function loadSettings(): Promise<Settings> {
+  const stored = await workhub.storage.get<Settings>('settings');
+  return stored ?? { darkMode: false, pageSize: 25 };
+}
+
+async function saveSettings(s: Settings): Promise<void> {
+  await workhub.storage.set('settings', s);
+  await workhub.notifications.toast('Settings saved', { variant: 'success' });
+}
+
+// React to host theme changes so the app follows the portal's light/dark.
+workhub.events.on('theme:change', (p: any) => {
+  document.documentElement.dataset.theme = p.mode;
+});
+```
+
+Manifest scopes: `["identity:read","storage:read","storage:write","notifications:send","events:listen"]`
+
+### Example 3 — App that lists the tenant's databases
+
+```ts
+import { workhub } from '@fepro/workhub-app-sdk';
+
+interface DatabaseInstance { id: string; name: string; engine: string; status: string }
+
+async function listDatabases(): Promise<DatabaseInstance[]> {
+  const res = await workhub.api.call<{ items: DatabaseInstance[] }>('GET /v1/databases');
+  return res.items;
+}
+
+const dbs = await listDatabases();
+document.body.innerHTML = `<ul>${dbs.map((d) => `<li>${d.name} (${d.engine}) — ${d.status}</li>`).join('')}</ul>`;
+```
+
+Manifest scopes: `["api:proxy"]` — note the user must also hold `database.read` for the call to succeed; the bridge does not elevate.
+
+## Build + upload commands
+
+```bash
+# 1. Build your SPA into ./dist (or the directory containing index.html + assets)
+npm run build
+
+# 2. Copy the manifest in next to the built files
+cp workhub.json dist/
+
+# 3. Zip from INSIDE dist/ — the manifest must be at zip root, not nested.
+cd dist && zip -r ../my-app.zip . && cd ..
+
+# 4. Upload via the portal
+open https://your-portal/apps/development
+
+# Or via the API
+curl -X POST https://your-portal-api/v1/apps/dev/upload \
+  -H "Authorization: Bearer $TOKEN" \
+  -F bundle=@my-app.zip
+```
+
+## Security model — what the iframe can and cannot do
+
+WorkHub apps run in a **fully sandboxed iframe** with `sandbox="allow-scripts allow-forms"`. That means:
+
+- **No DOM access to the parent portal** — the iframe gets an opaque origin and cannot reach into `parent.document` or strip its own sandbox.
+- **No cross-origin `fetch`** — `connect-src 'self'` in the iframe's CSP blocks calls to anything other than the runtime host. Use `workhub.api.call(...)` to reach `/v1/*` instead.
+- **No external script CDNs** — `default-src 'self'` blocks loading scripts/styles from esm.sh, jsdelivr, unpkg, etc. Either bundle dependencies or import them via the platform-served `/sdk.js`.
+- **`localStorage` / `IndexedDB` work** — but they're partitioned per-frame because of the opaque origin. State persists across reloads of the same installation; cross-app sharing isn't possible (use the SDK's `storage.*` for shared, server-backed KV).
+- **No cookies inside the iframe** — for the same reason. Anything that needs auth goes through the SDK's `api.call(...)`, where the host parent attaches the user's session.
+
+This is a **production security boundary**. A malicious bundle uploaded by tenant A cannot read tenant B's portal data, manipulate the parent UI, or call /v1 endpoints on the user's behalf without going through the scope-enforcing SDK bridge.
+
+## Gotchas (the things that bite agents)
+
+1. **Manifest at zip root, not nested in a folder.** `unzip -l` should show `workhub.json` directly, not `dist/workhub.json` or `my-app/workhub.json`. The upload endpoint reads the manifest from the root entry.
+2. **Don't ship `node_modules` or build configs.** Bundle the compiled output only — the upload limit is 25 MB compressed.
+3. **`postMessage` requires the iframe to be embedded.** Calling SDK methods locally in a browser tab outside the portal returns `not_embedded`. There's no offline mock in v1 — develop by uploading and iterating, or stub the SDK methods locally with mocks.
+4. **Scope enforcement is exact.** Calling `storage.set` without `storage:write` rejects with `{ code: 'ERR_SCOPE_DENIED' }` — the call never leaves the iframe.
+5. **`api.call('GET /v1/...')`** verb format is `"METHOD path"` with a single space. Lowercase methods are accepted but normalised.
+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).
+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.
+
+## Error catalogue
+
+| code               | meaning                                               | fix                                       |
+| ------------------ | ----------------------------------------------------- | ----------------------------------------- |
+| `not_embedded`     | SDK called outside an iframe                          | run inside the portal                     |
+| `ERR_SCOPE_DENIED` | manifest doesn't declare the required scope           | add the scope to `workhub.json` + re-upload |
+| `rpc_timeout`      | host bridge didn't respond in 10s                     | check network / portal logs               |
+| `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 |
+
+## Starter template (copy verbatim)
+
+```
+my-app/
+├── workhub.json
+├── index.html
+└── assets/
+    └── icon.svg
+```
+
+`workhub.json`:
+```json
+{
+  "key":     "my-app",
+  "name":    "My App",
+  "version": "0.1.0",
+  "entry":   "index.html",
+  "icon":    "assets/icon.svg",
+  "scopes":  ["identity:read", "storage:read", "storage:write", "notifications:send", "events:listen"]
+}
+```
+
+`index.html`:
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>My App</title>
+    <style>
+      :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+      body { margin: 0; padding: 24px; max-width: 720px; }
+      [data-theme="dark"] body { background: #0e1116; color: #e6e6e6; }
+      button { padding: 8px 14px; border-radius: 6px; cursor: pointer; }
+    </style>
+  </head>
+  <body>
+    <h1 id="title">Loading…</h1>
+    <p><input id="note" placeholder="type something" /> <button id="save">Save</button></p>
+    <pre id="out"></pre>
+    <script type="module">
+      import { workhub } from '/sdk.js';
+      const me = await workhub.identity.current();
+      title.textContent = `Hi ${me.user?.displayName ?? 'tenant'}`;
+      const last = await workhub.storage.get('note');
+      if (last) note.value = last;
+      save.onclick = async () => {
+        await workhub.storage.set('note', note.value);
+        out.textContent = JSON.stringify(await workhub.storage.list(), null, 2);
+        await workhub.notifications.toast('Saved', { variant: 'success' });
+      };
+      workhub.events.on('theme:change', (p) => document.documentElement.dataset.theme = p.mode);
+    </script>
+  </body>
+</html>
+```
+
+Zip + upload:
+```bash
+zip -r my-app.zip workhub.json index.html assets/
+# then upload via /apps/development → Upload bundle
+```
+
+That's a complete, working WorkHub app. Modify and ship.

package/README.md

@@ -2,8 +2,25 @@
 
 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))
+> for a dense, machine-friendly reference with the full SDK surface, three
+> worked examples, the gotcha catalogue, and a copy-paste starter template.
+
 ## Install
 
+The platform serves the compiled SDK at **`/sdk.js`** on the portal origin —
+uploaded apps can import it without any build step or external CDN. This is
+the recommended path for hand-written and AI-generated bundles:
+
+```html
+<script type="module">
+  import { workhub } from '/sdk.js';
+</script>
+```
+
+For TypeScript projects with a build step:
+
 ```bash
 npm install @fepro/workhub-app-sdk
 # or
@@ -12,6 +29,11 @@ pnpm add @fepro/workhub-app-sdk
 yarn add @fepro/workhub-app-sdk
 ```
 
+> **Do not use cross-origin CDNs** (esm.sh, jsdelivr, unpkg, etc.). Uploaded
+> apps run inside a fully sandboxed iframe whose CSP is `default-src 'self'`,
+> which blocks external script loads. `/sdk.js` is the same-origin platform
+> SDK and is the only supported way to load it without bundling.
+
 ## The bundle format
 
 A WorkHub developer-app is a `.zip` archive with this layout:

package/dist/index.d.ts

@@ -93,6 +93,22 @@ export declare const workhub: {
     readonly api: {
         readonly call: <T = unknown>(verb: string, body?: unknown) => Promise<T>;
     };
+    /** Calls the developer's own workspace backend, proxied through the
+     *  WorkHub runtime so requests carry a verifiable identity token (the
+     *  backend SDK verifies it against /.well-known/jwks.json).
+     *
+     *  Only available to apps installed under a developer workspace — for
+     *  standalone-iframe apps this method throws because the runtime has
+     *  no backend deployment to forward to. */
+    readonly backend: {
+        /** Issue a request against the workspace backend.
+         *
+         *  `path` is the route path declared in the backend's defineWorkspace
+         *  routes table (e.g. `/leads` or `/leads/123/notes`). Leading slash
+         *  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>;
+    };
 };
 export default workhub;
 //# sourceMappingURL=index.d.ts.map

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;;CAIrD,CAAC;AAGX,eAAe,OAAO,CAAC"}
+{"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"}

package/dist/index.js

@@ -141,6 +141,36 @@ export const workhub = {
             return channel.call('api.call', { verb, body });
         },
     },
+    /** Calls the developer's own workspace backend, proxied through the
+     *  WorkHub runtime so requests carry a verifiable identity token (the
+     *  backend SDK verifies it against /.well-known/jwks.json).
+     *
+     *  Only available to apps installed under a developer workspace — for
+     *  standalone-iframe apps this method throws because the runtime has
+     *  no backend deployment to forward to. */
+    backend: {
+        /** Issue a request against the workspace backend.
+         *
+         *  `path` is the route path declared in the backend's defineWorkspace
+         *  routes table (e.g. `/leads` or `/leads/123/notes`). Leading slash
+         *  required. The host SDK builds the full URL `/v1/apps/runtime/<installationId>/api<path>`
+         *  and uses same-origin credentialed fetch — no extra auth wiring. */
+        async fetch(path, init) {
+            if (!path.startsWith('/')) {
+                throw new Error(`workhub.backend.fetch: path must start with "/" — got "${path}"`);
+            }
+            const identity = await channel.call('identity.current', {});
+            const installationId = identity.installation?.id;
+            if (!installationId) {
+                throw new Error('workhub.backend.fetch: no installation id on identity — is this app installed under a workspace?');
+            }
+            const url = `/v1/apps/runtime/${encodeURIComponent(installationId)}/api${path}`;
+            return fetch(url, {
+                ...init,
+                credentials: 'include',
+            });
+        },
+    },
 };
 // Default export for ergonomic single-import usage.
 export default workhub;

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fepro/workhub-app-sdk",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -17,7 +17,8 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/index.ts

@@ -198,6 +198,37 @@ export const workhub = {
       return channel.call<T>('api.call', { verb, body });
     },
   },
+
+  /** Calls the developer's own workspace backend, proxied through the
+   *  WorkHub runtime so requests carry a verifiable identity token (the
+   *  backend SDK verifies it against /.well-known/jwks.json).
+   *
+   *  Only available to apps installed under a developer workspace — for
+   *  standalone-iframe apps this method throws because the runtime has
+   *  no backend deployment to forward to. */
+  backend: {
+    /** Issue a request against the workspace backend.
+     *
+     *  `path` is the route path declared in the backend's defineWorkspace
+     *  routes table (e.g. `/leads` or `/leads/123/notes`). Leading slash
+     *  required. The host SDK builds the full URL `/v1/apps/runtime/<installationId>/api<path>`
+     *  and uses same-origin credentialed fetch — no extra auth wiring. */
+    async fetch(path: string, init?: RequestInit): Promise<Response> {
+      if (!path.startsWith('/')) {
+        throw new Error(`workhub.backend.fetch: path must start with "/" — got "${path}"`);
+      }
+      const identity = await channel.call<Identity>('identity.current', {});
+      const installationId = identity.installation?.id;
+      if (!installationId) {
+        throw new Error('workhub.backend.fetch: no installation id on identity — is this app installed under a workspace?');
+      }
+      const url = `/v1/apps/runtime/${encodeURIComponent(installationId)}/api${path}`;
+      return fetch(url, {
+        ...init,
+        credentials: 'include',
+      });
+    },
+  },
 } as const;
 
 // Default export for ergonomic single-import usage.