@colixsystems/widget-sdk 0.33.0 → 0.34.0

package/README.md

@@ -11,7 +11,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | `ctx.files` | `@colixsystems/files-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useFile()` resolves |
 | `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` |
 
-**Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no client-side case transform anywhere** — the only transform left in the system is the backend's wire ↔ Prisma middleware. Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
+**Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
 
 **Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (18 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
 
@@ -36,6 +36,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (mutations also `users.write:*`) |
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
+| **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser` |
 
 All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
@@ -46,7 +47,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.33.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.34.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.34.0
+
+**`useBankIdLink()` — link / unlink BankID from a widget (REQ-BANKID-AUTH).** A new DIRECTORY hook reading the new `ctx.directory.bankid` namespace on `@colixsystems/directory-client` **0.2.0** (`status` / `startLink` / `collect` / `cancel` / `unlink`). It lets a signed-in app-user attach a BankID identity to their account (or remove it) via an animated-QR poll — `startLink()` opens the order, `refresh()` polls it (drive on a ~2s interval while `status === "pending"`; render `qr` with the `Image` primitive), `unlink()` removes it. `available` is `false` when BankID can't be used in the app (provider disabled or no platform cert) — hide the affordance then. Self-service + JWT-gated, so **no `requestedScopes` entry is required**. Backs the built-in **User** widget's "Link BankID" section. `CONTRACT.version` → `1.24.0`. Additive — no existing export or type changed.
 
 ### What's new in 0.33.0
 

package/dist/contract.cjs

@@ -377,6 +377,42 @@ const HOOKS = [
     requiredContextSlice: ["directory.groups"],
     scopes: ["groups.read:*"],
   },
+  // REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in
+  // app-user. Self-service + JWT-gated (no widget scope). Mirror of contract.js.
+  {
+    name: "useBankIdLink",
+    signature: "useBankIdLink()",
+    description:
+      "Link / unlink a BankID identity to the signed-in app-user via the " +
+      "injected directory-client at ctx.directory.bankid.{status,startLink," +
+      "collect,cancel,unlink}. Returns { linked, available, status, qr, message, " +
+      "loading, statusLoading, error, startLink, refresh, cancel, unlink, " +
+      "refetchStatus }. On mount it reads the link status; `available` is false " +
+      "when BankID can't be used here (provider disabled or no platform cert) — " +
+      "hide the Link affordance then. The link flow is an animated-QR poll like " +
+      "useFileSignature: startLink() opens an order (status 'pending' + qr — a " +
+      "PNG data-URL, render with the Image primitive); refresh() polls (drive on " +
+      "a ~2s interval while pending; sets linked=true on complete); cancel() " +
+      "aborts; unlink() removes the link (rejects DirectoryError LAST_AUTH_METHOD " +
+      "when BankID is the only sign-in method). No requestedScopes entry needed.",
+    returnShape: {
+      linked: "boolean | null  // null until the status loads",
+      available: "boolean  // false → hide the Link affordance",
+      status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR",
+      message: "string | null",
+      loading: "boolean",
+      statusLoading: "boolean",
+      error: "DirectoryError | null",
+      startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
+      refresh: "() => Promise<void>",
+      cancel: "() => Promise<void>",
+      unlink: "() => Promise<{ linked: boolean }>  // rejects with DirectoryError",
+      refetchStatus: "() => Promise<{ linked, available }>",
+    },
+    requiredContextSlice: ["directory.bankid"],
+    scopes: null,
+  },
   // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
   // management for a single record. Mirror of contract.js.
   {
@@ -809,10 +845,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "Injected @colixsystems/directory-client instance. " +
       "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
-      "invites: { list(), revoke(id), resend(id) } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
+      "invites: { list(), revoke(id), resend(id) }, " +
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
     required: true,
-    fields: { users: "object", groups: "object" },
+    fields: { users: "object", groups: "object", bankid: "object" },
   },
   files: {
     description:
@@ -1349,7 +1386,15 @@ const CONTRACT = deepFreeze({
   //    form-root tableId switches) and `ui.defaultFactory: "tabId"`
   //    (per-instance dynamic default). No existing field, hook, primitive,
   //    or token changed shape — minor bump on the pre-1.0 channel.
-  version: "1.23.0",
+  //
+  // 1.24.0: additive (REQ-BANKID-AUTH) — new `useBankIdLink()` hook reading the
+  //    new `ctx.directory.bankid` namespace (status/startLink/collect/cancel/
+  //    unlink) on the @colixsystems/directory-client (0.2.0). Lets the built-in
+  //    User widget link / unlink a BankID identity to the signed-in app-user
+  //    (animated-QR poll). Self-service + JWT-gated — no requestedScopes entry.
+  //    No existing hook, primitive, or field changed shape — minor bump on the
+  //    pre-1.0 channel.
+  version: "1.24.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -377,6 +377,42 @@ const HOOKS = [
     requiredContextSlice: ["directory.groups"],
     scopes: ["groups.read:*"],
   },
+  // REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in
+  // app-user. Self-service + JWT-gated (no widget scope). Mirror of contract.cjs.
+  {
+    name: "useBankIdLink",
+    signature: "useBankIdLink()",
+    description:
+      "Link / unlink a BankID identity to the signed-in app-user via the " +
+      "injected directory-client at ctx.directory.bankid.{status,startLink," +
+      "collect,cancel,unlink}. Returns { linked, available, status, qr, message, " +
+      "loading, statusLoading, error, startLink, refresh, cancel, unlink, " +
+      "refetchStatus }. On mount it reads the link status; `available` is false " +
+      "when BankID can't be used here (provider disabled or no platform cert) — " +
+      "hide the Link affordance then. The link flow is an animated-QR poll like " +
+      "useFileSignature: startLink() opens an order (status 'pending' + qr — a " +
+      "PNG data-URL, render with the Image primitive); refresh() polls (drive on " +
+      "a ~2s interval while pending; sets linked=true on complete); cancel() " +
+      "aborts; unlink() removes the link (rejects DirectoryError LAST_AUTH_METHOD " +
+      "when BankID is the only sign-in method). No requestedScopes entry needed.",
+    returnShape: {
+      linked: "boolean | null  // null until the status loads",
+      available: "boolean  // false → hide the Link affordance",
+      status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR",
+      message: "string | null",
+      loading: "boolean",
+      statusLoading: "boolean",
+      error: "DirectoryError | null",
+      startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
+      refresh: "() => Promise<void>",
+      cancel: "() => Promise<void>",
+      unlink: "() => Promise<{ linked: boolean }>  // rejects with DirectoryError",
+      refetchStatus: "() => Promise<{ linked, available }>",
+    },
+    requiredContextSlice: ["directory.bankid"],
+    scopes: null,
+  },
   // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
   // management for a single record. Mirror of contract.js.
   {
@@ -809,10 +845,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "Injected @colixsystems/directory-client instance. " +
       "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
-      "invites: { list(), revoke(id), resend(id) } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
+      "invites: { list(), revoke(id), resend(id) }, " +
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
     required: true,
-    fields: { users: "object", groups: "object" },
+    fields: { users: "object", groups: "object", bankid: "object" },
   },
   files: {
     description:
@@ -1349,7 +1386,15 @@ const CONTRACT = deepFreeze({
   //    form-root tableId switches) and `ui.defaultFactory: "tabId"`
   //    (per-instance dynamic default). No existing field, hook, primitive,
   //    or token changed shape — minor bump on the pre-1.0 channel.
-  version: "1.23.0",
+  //
+  // 1.24.0: additive (REQ-BANKID-AUTH) — new `useBankIdLink()` hook reading the
+  //    new `ctx.directory.bankid` namespace (status/startLink/collect/cancel/
+  //    unlink) on the @colixsystems/directory-client (0.2.0). Lets the built-in
+  //    User widget link / unlink a BankID identity to the signed-in app-user
+  //    (animated-QR poll). Self-service + JWT-gated — no requestedScopes entry.
+  //    No existing hook, primitive, or field changed shape — minor bump on the
+  //    pre-1.0 channel.
+  version: "1.24.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -1850,6 +1850,170 @@ export function useGroups(query) {
   return { groups, loading, error, refetch, create, remove, addMember, removeMember };
 }
 
+/**
+ * REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in app-user,
+ * and read whether BankID is available + already linked. Returns
+ * `{ linked, available, status, qr, message, loading, statusLoading, error,
+ * startLink, refresh, cancel, unlink, refetchStatus }`.
+ *
+ * Reads the injected `@colixsystems/directory-client` at `ctx.directory.bankid`
+ * (a self-service, JWT-gated surface — no widget scope needed). On mount it
+ * fetches the link status; `available` is false when BankID can't be used in
+ * this app (provider disabled or no platform cert), so a widget should hide the
+ * Link affordance entirely when `!available`.
+ *
+ * The link flow is an animated-QR poll, mirroring `useFileSignature`:
+ *   - `startLink()` opens an order → sets `status: "pending"` + `qr` (a PNG
+ *     data-URL; render it with the `Image` primitive).
+ *   - `refresh()` polls the order — refreshing the QR frame while pending and,
+ *     on completion, setting `linked: true` + `status: "complete"`. The widget
+ *     drives the cadence (e.g. a 2s interval while `status === "pending"`).
+ *   - `cancel()` aborts the in-flight order.
+ *   - `unlink()` removes the link (rejects with a DirectoryError carrying
+ *     `code: "LAST_AUTH_METHOD"` / status 409 when BankID is the user's only
+ *     sign-in method).
+ *
+ * No `requestedScopes` entry is required — the endpoints are gated by the
+ * app-user session the host already holds.
+ */
+export function useBankIdLink() {
+  const ctx = useWidgetContextOrThrow("useBankIdLink");
+  if (
+    !ctx.directory ||
+    !ctx.directory.bankid ||
+    typeof ctx.directory.bankid.status !== "function"
+  ) {
+    throw new Error(
+      "useBankIdLink: host did not inject a directory client (ctx.directory.bankid)",
+    );
+  }
+  // `ctx` is a fresh identity each host render — hold the namespace in a ref so
+  // the callbacks stay stable.
+  const apiRef = useRef(ctx.directory.bankid);
+  apiRef.current = ctx.directory.bankid;
+
+  const [linked, setLinked] = useState(null); // null until the status loads
+  const [available, setAvailable] = useState(false);
+  const [statusLoading, setStatusLoading] = useState(true);
+  const [status, setStatus] = useState(null); // null | pending | complete | failed | cancelled
+  const [qr, setQr] = useState(null);
+  const [message, setMessage] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const orderRef = useRef(null);
+
+  const refetchStatus = useCallback(async () => {
+    setStatusLoading(true);
+    try {
+      const res = await apiRef.current.status();
+      setLinked(Boolean(res && res.linked));
+      setAvailable(Boolean(res && res.available));
+      setStatusLoading(false);
+      return res;
+    } catch (err) {
+      setError(toDirectoryError(err));
+      setStatusLoading(false);
+      return null;
+    }
+  }, []);
+
+  useEffect(() => {
+    refetchStatus();
+  }, [refetchStatus]);
+
+  const startLink = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await apiRef.current.startLink();
+      orderRef.current = res && res.order_ref ? res.order_ref : null;
+      setStatus(res && res.status ? res.status : "pending");
+      setQr(res && res.qr ? res.qr : null);
+      setMessage(null);
+      setLoading(false);
+      return res;
+    } catch (err) {
+      const e = toDirectoryError(err);
+      setError(e);
+      setStatus("failed");
+      setMessage(e.message);
+      setLoading(false);
+      throw e;
+    }
+  }, []);
+
+  const refresh = useCallback(async () => {
+    const id = orderRef.current;
+    if (!id) return null;
+    try {
+      const res = await apiRef.current.collect(id);
+      if (res) {
+        if (res.status != null) setStatus(res.status);
+        if (res.qr !== undefined) setQr(res.qr || null);
+        if (res.message !== undefined) setMessage(res.message || null);
+        if (res.status === "complete") setLinked(true);
+      }
+      return res;
+    } catch (err) {
+      // A terminal client error (e.g. 409 BANKID_ALREADY_LINKED) carries a
+      // helpful message — surface it as a failed order rather than throwing
+      // into the widget's poll interval.
+      const e = toDirectoryError(err);
+      setError(e);
+      setStatus("failed");
+      setMessage(e.message);
+      return null;
+    }
+  }, []);
+
+  const cancel = useCallback(async () => {
+    const id = orderRef.current;
+    orderRef.current = null;
+    setStatus(null);
+    setQr(null);
+    setMessage(null);
+    if (id) {
+      try {
+        await apiRef.current.cancel(id);
+      } catch {
+        // best-effort — the order may have already expired.
+      }
+    }
+  }, []);
+
+  const unlink = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await apiRef.current.unlink();
+      setLinked(Boolean(res && res.linked));
+      setLoading(false);
+      return res;
+    } catch (err) {
+      const e = toDirectoryError(err);
+      setError(e);
+      setLoading(false);
+      throw e;
+    }
+  }, []);
+
+  return {
+    linked,
+    available,
+    status,
+    qr,
+    message,
+    loading,
+    statusLoading,
+    error,
+    startLink,
+    refresh,
+    cancel,
+    unlink,
+    refetchStatus,
+  };
+}
+
 /* ============================================================================
  * PAYMENTS CLIENT — ctx.payments (@colixsystems/payments-client)
  *

package/dist/index.d.ts

@@ -354,6 +354,24 @@ export interface DirectoryClient {
     revoke(inviteId: string): Promise<void>;
     resend(inviteId: string): Promise<unknown>;
   };
+  /** REQ-BANKID-AUTH — backs `useBankIdLink`. */
+  bankid: {
+    status(): Promise<{ linked: boolean; available: boolean }>;
+    startLink(): Promise<{
+      order_ref: string;
+      auto_start_token: string | null;
+      qr: string | null;
+      status: "pending";
+    }>;
+    collect(orderRef: string): Promise<{
+      status: "pending" | "complete" | "failed" | "cancelled";
+      qr?: string | null;
+      message?: string;
+      linked?: boolean;
+    }>;
+    cancel(orderRef: string): Promise<{ status: "cancelled" }>;
+    unlink(): Promise<{ linked: boolean }>;
+  };
 }
 
 /**
@@ -924,6 +942,45 @@ export interface GroupsApi {
  */
 export function useGroups(query?: GroupsQuery): GroupsApi;
 
+// ----------------------------------------------------- useBankIdLink
+//
+// REQ-BANKID-AUTH — link / unlink a BankID identity to the signed-in app-user.
+// Reads the injected directory-client at `ctx.directory.bankid`. Self-service,
+// JWT-gated — no requestedScopes entry needed.
+
+export interface BankIdLinkApi {
+  /** Whether the user currently has BankID linked (null until the status loads). */
+  linked: boolean | null;
+  /** Whether BankID linking can be used in this app (provider enabled + platform cert). */
+  available: boolean;
+  /** The active link order's state, or null when no order is in flight. */
+  status: "pending" | "complete" | "failed" | "cancelled" | null;
+  /** PNG data-URL of the animated BankID QR while pending (render with the Image primitive). */
+  qr: string | null;
+  message: string | null;
+  loading: boolean;
+  statusLoading: boolean;
+  error: DirectoryError | null;
+  /** Open a link order → sets status "pending" + qr. */
+  startLink(): Promise<unknown>;
+  /** Poll the open order; on completion sets linked=true. Drive on an interval while pending. */
+  refresh(): Promise<unknown>;
+  /** Abort the in-flight order. */
+  cancel(): Promise<void>;
+  /** Remove the link (rejects with DirectoryError code LAST_AUTH_METHOD when it is the only method). */
+  unlink(): Promise<{ linked: boolean }>;
+  /** Re-read { linked, available }. */
+  refetchStatus(): Promise<unknown>;
+}
+
+/**
+ * Link / unlink a BankID identity to the signed-in app-user and read the
+ * current link + availability state. Reads `ctx.directory.bankid`. No
+ * requestedScopes entry is required — the endpoints are gated by the app-user
+ * session the host holds. Hide the Link affordance when `available` is false.
+ */
+export function useBankIdLink(): BankIdLinkApi;
+
 // ----------------------------------------------------- useRecordPermissions
 //
 // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission

package/dist/index.js

@@ -23,6 +23,7 @@ export {
   useDirectory,
   useUsers,
   useGroups,
+  useBankIdLink,
   useRecordPermissions,
   useDatastoreSubscription,
   useWidgetEvent,

package/dist/index.native.js

@@ -23,6 +23,7 @@ export {
   useDirectory,
   useUsers,
   useGroups,
+  useBankIdLink,
   useRecordPermissions,
   useDatastoreSubscription,
   useWidgetEvent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",