@fepro/workhub-app-sdk 0.2.0 → 0.4.1

package/src/index.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
@@ -40,17 +43,90 @@ export interface StorageEntry {
   updatedAt: string;
 }
 
-export type WorkhubEventName =
+/** 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[];
+}
+
+// ─── Events ──────────────────────────────────────────────────────────────────
+
+/** Built-in portal-emitted events. */
+export type WorkhubHostEventName =
   | 'theme:change'
   | 'route:change'
-  | 'tenant:switch';
+  | '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 };
+}
 
-export interface WorkhubEventPayload {
-  'theme:change':  { mode: 'light' | 'dark' };
-  'route:change':  { path: string };
-  'tenant:switch': { tenantId: string };
+/** 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 {
+  // Intentionally empty — augmented per-app.
+  [key: `app:${string}`]: unknown;
 }
 
+export type WorkhubEventName = WorkhubHostEventName | `app:${string}`;
+export type WorkhubEventPayload = WorkhubHostEventPayload & WorkhubAppEventPayload;
+
 // ─── postMessage envelope ────────────────────────────────────────────────────
 
 interface RpcRequest {
@@ -78,12 +154,33 @@ type IncomingMessage = RpcResponse | RpcEvent;
 
 const RPC_TIMEOUT_MS = 10_000;
 
+/** 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 class WorkhubError extends Error {
+  public readonly code: string;
+  public readonly status: number | undefined;
+  public readonly requestId: string | undefined;
+  public readonly details: Record<string, unknown> | undefined;
+
+  constructor(
+    code: string,
+    message: string,
+    extras?: { status?: number; requestId?: string; details?: Record<string, unknown> },
+  ) {
+    super(message);
+    this.name = 'WorkhubError';
+    this.code = code;
+    this.status = extras?.status;
+    this.requestId = extras?.requestId;
+    this.details = extras?.details;
+  }
+}
+
 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 {
@@ -101,22 +198,59 @@ class HostChannel {
         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' }));
+        if (data.ok) {
+          pending.resolve(data.result);
+        } else {
+          pending.reject(
+            new WorkhubError(
+              data.error?.code ?? 'rpc_failed',
+              data.error?.message ?? 'rpc failed',
+            ),
+          );
+        }
       } else if (data.__workhub === 'rpc-event') {
+        // Auto-navigate on host-driven route changes (deep-link, refresh
+        // restore, browser back/forward). Apps route via the URL hash, so
+        // setting location.hash drives their router with no app code change.
+        // Guarded to the differing case so it can't loop with the route
+        // reporter below.
+        if (data.name === 'route:change') {
+          const p = (data.payload as { path?: string } | undefined)?.path;
+          if (typeof p === 'string') {
+            const target = p === '' ? '/' : (p.startsWith('/') ? p : `/${p}`);
+            if (window.location.hash.replace(/^#/, '') !== target) {
+              window.location.hash = target;
+            }
+          }
+        }
         const set = this.listeners.get(data.name);
         if (!set) return;
         for (const cb of set) {
-          try { cb(data.payload); } catch { /* swallow listener errors */ }
+          try { cb(data.payload); } catch { /* swallow listener errors so one bad subscriber can't break the others */ }
         }
       }
     });
+
+    // Mirror the app's route OUT to the host so it can reflect it in the browser
+    // URL — making full-page ("popped-out") apps deep-linkable and refresh-safe.
+    // Apps route via the URL hash; we report location.hash on every change + once
+    // now. The host decides whether to act on it (the full-page surface updates
+    // the address bar; the embedded portal view ignores it).
+    const reportRoute = (): void => {
+      if (window.parent === window) return;
+      const path = window.location.hash.replace(/^#/, '') || '/';
+      window.parent.postMessage({ __workhub: 'route-report', path }, '*');
+    };
+    window.addEventListener('hashchange', reportRoute);
+    reportRoute();
   }
 
   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'));
+      return Promise.reject(
+        new WorkhubError('not_embedded', 'workhub SDK only works inside the portal iframe'),
+      );
     }
     const id = String(this.nextId++);
     const msg: RpcRequest = { __workhub: 'rpc-request', id, verb, payload };
@@ -124,7 +258,7 @@ class HostChannel {
     return new Promise<T>((resolve, reject) => {
       const timeout = setTimeout(() => {
         this.pending.delete(id);
-        reject(Object.assign(new Error(`rpc_timeout: ${verb}`), { code: 'timeout' }));
+        reject(new WorkhubError('timeout', `rpc_timeout: ${verb}`));
       }, RPC_TIMEOUT_MS);
       this.pending.set(id, {
         resolve: (v) => { clearTimeout(timeout); resolve(v as T); },
@@ -143,19 +277,174 @@ class HostChannel {
       this.listeners.set(name, set);
     }
     set.add(cb);
-    return () => set!.delete(cb);
+    // Tell the host bridge this iframe wants to receive `name`. The host
+    // tracks subscriptions per-iframe so it only forwards events the app
+    // is actually listening for, and so it knows which apps need server
+    // pushes for `app:*` events (the tenant-event bridge).
+    void this.call<void>('events.subscribe', { name }).catch(() => undefined);
+    const setRef = set;
+    return () => {
+      setRef.delete(cb);
+      if (setRef.size === 0) {
+        this.listeners.delete(name);
+        void this.call<void>('events.unsubscribe', { name }).catch(() => undefined);
+      }
+    };
   }
 }
 
 const channel = new HostChannel();
 
+/** Tag set on the backend's error JSON payloads — the frontend looks for
+ *  this so it can rethrow as `WorkhubError` instead of treating a 4xx body
+ *  as a successful response. Must match `ERROR_ENVELOPE_TAG` in the
+ *  backend SDK. */
+const ERROR_ENVELOPE_TAG = '__workhub_error';
+
+interface BackendErrorEnvelope {
+  __workhub_error: true;
+  code: string;
+  message: string;
+  requestId: string;
+  details?: Record<string, unknown>;
+}
+
+function isBackendErrorEnvelope(value: unknown): value is BackendErrorEnvelope {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && (value as Record<string, unknown>)[ERROR_ENVELOPE_TAG] === true
+  );
+}
+
 // ─── Surface ────────────────────────────────────────────────────────────────
 
+// Per-session identity cache. Identity is immutable for the lifetime of an
+// iframe (the bundle token is minted once at boot; user / tenant / installation
+// cannot change without a reload), so the first successful response is the
+// only one we'll ever need. Resolves BMS ERP request #31 — the second
+// identity.current() call within a session was racing the host RPC bridge
+// and surfacing `rpc_timeout: identity.current` even when the first call had
+// just succeeded.
+let identityCache: Identity | null = null;
+let identityPending: Promise<Identity> | null = null;
+
 export const workhub = {
   /** Identity — read-only user / tenant / installation context. */
   identity: {
     current(): Promise<Identity> {
-      return channel.call<Identity>('identity.current', {});
+      // Fast path — cached value from an earlier successful resolution.
+      if (identityCache) return Promise.resolve(identityCache);
+      // In-flight de-duplication — concurrent callers during cold start
+      // share a single RPC instead of issuing one each. Without this,
+      // `Promise.all([identity.current(), identity.current()])` would
+      // re-race the host bridge.
+      if (identityPending) return identityPending;
+      identityPending = channel.call<Identity>('identity.current', {})
+        .then((value) => {
+          identityCache = value;
+          identityPending = null;
+          return value;
+        })
+        .catch((err) => {
+          // On failure clear the pending lock so a retry actually retries
+          // (callers usually catch + retry on UI events).
+          identityPending = null;
+          throw err;
+        });
+      return identityPending;
+    },
+  },
+
+  /** 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. */
+  auth: {
+    logout(): void {
+      void channel.call('auth.logout', {}).catch(() => { /* host is navigating away */ });
+    },
+  },
+
+  /** 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. */
+  locale: {
+    current(): Promise<LocaleInfo> {
+      return channel.call<LocaleInfo>('locale.current', {});
+    },
+  },
+
+  /** 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). */
+  org: {
+    /** List accessible units + the active one. */
+    units(): Promise<OrgContext> {
+      return channel.call<OrgContext>('org.units', {});
+    },
+    /** Ask the portal to switch the active unit. The portal validates access,
+     *  re-issues the identity token, and emits `org-unit:switch`. */
+    switch(unitId: string): Promise<void> {
+      return channel.call<void>('org.switch', { unitId });
+    },
+  },
+
+  /** 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. */
+  theme: {
+    current(): Promise<ThemeTokens> {
+      return channel.call<ThemeTokens>('theme.current', {});
+    },
+  },
+
+  /** 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). */
+  files: {
+    /** Get a presigned PUT URL + the stable key to persist. Upload the file
+     *  yourself with a plain `fetch(url, { method: 'PUT', body: file })`. */
+    presignUpload(
+      opts: { filename: string; contentType?: string; keyHint?: string },
+    ): Promise<{ url: string; key: string; headers?: Record<string, string> }> {
+      return channel.call('files.presignUpload', opts);
+    },
+    /** Convenience: presign + PUT in one call. Returns the stable key. */
+    async upload(file: Blob, opts?: { filename?: string; keyHint?: string }): Promise<{ key: string }> {
+      const filename = opts?.filename ?? (file as File).name ?? 'upload.bin';
+      const contentType = file.type || 'application/octet-stream';
+      const presign = await workhub.files.presignUpload({
+        filename,
+        contentType,
+        ...(opts?.keyHint ? { keyHint: opts.keyHint } : {}),
+      });
+      const put = await fetch(presign.url, {
+        method: 'PUT',
+        headers: { 'content-type': contentType, ...(presign.headers ?? {}) },
+        body: file,
+      });
+      if (!put.ok) {
+        throw new WorkhubError('upload_failed', `upload PUT failed: ${put.status} ${put.statusText}`, { status: put.status });
+      }
+      return { key: presign.key };
+    },
+    /** Presigned, time-limited GET URL for a stored key. */
+    getUrl(key: string, opts?: { expiresInSeconds?: number }): Promise<{ url: string }> {
+      return channel.call('files.getUrl', { key, expiresInSeconds: opts?.expiresInSeconds });
+    },
+    delete(key: string): Promise<void> {
+      return channel.call<void>('files.delete', { key });
+    },
+    list(prefix?: string): Promise<Array<{ key: string; size: number; lastModified: string | null }>> {
+      return channel.call('files.list', { prefix });
     },
   },
 
@@ -184,8 +473,17 @@ export const workhub = {
     },
   },
 
-  /** 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. */
   events: {
     on: channel.on.bind(channel),
   },
@@ -215,12 +513,18 @@ export const workhub = {
      *  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}"`);
+        throw new WorkhubError(
+          'bad_request',
+          `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?');
+        throw new WorkhubError(
+          'not_installed',
+          '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, {
@@ -228,8 +532,62 @@ export const workhub = {
         credentials: 'include',
       });
     },
+
+    /** 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. */
+    async call<T = unknown>(
+      path: string,
+      opts: {
+        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        body?: unknown;
+        headers?: Record<string, string>;
+        idempotencyKey?: string;
+      } = {},
+    ): Promise<T> {
+      const init: RequestInit = {
+        method: opts.method ?? (opts.body !== undefined ? 'POST' : 'GET'),
+        headers: {
+          accept: 'application/json',
+          ...(opts.body !== undefined ? { 'content-type': 'application/json' } : {}),
+          ...(opts.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {}),
+          ...(opts.headers ?? {}),
+        },
+        ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+      };
+      const res = await workhub.backend.fetch(path, init);
+      const text = await res.text();
+      const parsed = text.length > 0 ? safeParseJson(text) : null;
+      if (!res.ok) {
+        if (isBackendErrorEnvelope(parsed)) {
+          throw new WorkhubError(parsed.code, parsed.message, {
+            status: res.status,
+            requestId: parsed.requestId,
+            ...(parsed.details ? { details: parsed.details } : {}),
+          });
+        }
+        const requestId = res.headers.get('x-request-id');
+        throw new WorkhubError(
+          'http_error',
+          `backend ${res.status} ${res.statusText}`,
+          {
+            status: res.status,
+            ...(requestId ? { requestId } : {}),
+            details: { body: typeof parsed === 'string' ? parsed : (parsed as Record<string, unknown> | null) ?? undefined },
+          },
+        );
+      }
+      return parsed as T;
+    },
   },
 } as const;
 
+function safeParseJson(text: string): unknown {
+  try { return JSON.parse(text); } catch { return text; }
+}
+
 // Default export for ergonomic single-import usage.
 export default workhub;