@fepro/workhub-app-sdk 0.1.0 → 0.1.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fepro/workhub-app-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",