@colixsystems/widget-sdk 0.180.1 → 0.182.0

package/README.md

@@ -59,7 +59,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
-| **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
+| **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, q?, app_user_id?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| open \| all` (endpoint default `all`; `open` = `pending` or `expired`); `q` matches the invite's name or email, `app_user_id` returns the invites reserving that user id. |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
 | **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: spaceType, folderId) | `{ openPdf, opening, canOpenPdf, exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.renderPdf` + `ctx.device.pdfViewer`, `ctx.filestore.files.exportPdf` — `files.write:*`. `openPdf(html, { fileName? })` renders the HTML to a PDF server-side and OPENS it (web: PDF tab; native: print / share sheet) without saving. `exportToPdf(html, { fileName?, folderId? })` renders it and saves it as a file (`application/pdf`). Same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
@@ -74,7 +74,22 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.180.1` — 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.182.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.182.0 (contract 1.143.0)
+
+**A `datastoreTemplate` relation decides what happens when the row it points at is deleted.** A `ONE_TO_ONE` / `ONE_TO_MANY` RELATION column may declare `onDelete`. With `"SET_NULL"`, the default, the row is kept and its reference is emptied. With `"CASCADE"`, the row is deleted along with the row it points at, and anything that cascades from it is deleted in turn. A `MANY_TO_MANY` column takes no `onDelete`: deleting a row on either side only removes its links. The platform applies the rule on every delete, so a widget that deletes a parent row never has to delete or clear its children itself. Use `CASCADE` for rows that mean nothing without their parent (order lines, a post's comments). Additive: a template without it gets `SET_NULL`.
+
+### What's new in 0.181.0 (contract 1.142.0)
+
+**A `USER` column can point at someone who has been invited but has not joined yet.** Every invite now reserves the id its invitee's user account will have, so a record can be assigned to that person straight away and nothing needs rewriting when they accept.
+
+- **`useInvites()` rows carry `app_user_id`** — that reserved id. The `resend()` result carries it too.
+- **`useInvites(query)` takes two more optional keys.** `q` is a case-insensitive substring match on the invite's name or email. `app_user_id` returns only the invites reserving that id, which is how a member-admin widget resolves the person behind a `USER` value before they have joined; an id no invite reserves returns no rows.
+- **`status: 'open'`** is every invite that is neither accepted nor revoked — `pending` or `expired`. A re-invite keeps the reserved id, so `useInvites({ app_user_id, status: 'open' })` is the one invite that still reserves it.
+- **A `USER` column has a third read shape.** A user of the workspace still reads as `{ id, name, email }` and an id that names nobody as `{ id, name: null }`. An invited person who has not joined reads as `{ id, name, invited: true }` — **with no `email`**, so render `name` and treat `email` as optional. Once they accept, the same id reads as an ordinary user and `invited` is gone.
+
+Additive: no existing field changed shape, and the scope is unchanged (`users.write:*` plus the `users.write` capability for the whole invite surface).
 
 ### What's new in 0.180.1 (contract 1.141.0 — unchanged)
 
@@ -2114,9 +2129,17 @@ function PendingInvites() {
 }
 ```
 
-Rows are snake_case: `{ id, email, name, group_ids, status, expires_at, accepted_at,
-revoked_at, created_at }`. Trust the server-computed `status` rather than comparing
-`expires_at` against the device clock.
+Rows are snake_case: `{ id, app_user_id, email, name, group_ids, status, expires_at,
+accepted_at, revoked_at, created_at }`. Trust the server-computed `status` rather than
+comparing `expires_at` against the device clock.
+
+`query` also takes `q` (a case-insensitive substring match on the invite's name or
+email) and `app_user_id`. Each row's `app_user_id` is the id the invitee's user account
+will have once they accept. A `USER` column may hold that id before the person has
+joined — it then reads back as `{ id, name, invited: true }`, with no `email` — and
+`useInvites({ app_user_id: value.id, status: 'open', limit: 1 })` returns the invite
+behind it. `status: 'open'` is every invite that is neither accepted nor revoked
+(`pending` or `expired`); a re-invite keeps the id, so without it earlier invites match too.
 
 **The gate is `users.write`, not `users.read`.** A pending invite exposes the email of
 someone who is not a member yet, so the backend gates the entire invite surface —

package/dist/contract.cjs

@@ -1787,9 +1787,18 @@ const HOOKS = [
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (email, status, expires_at, …) and " +
       "status is the server-computed pending/accepted/revoked/expired " +
-      "value. query is { status?, limit?, offset? } passed verbatim; the " +
-      "endpoint defaults to status 'all', so pass { status: 'pending' } " +
-      "for the usual outstanding-invite list. The WHOLE invite surface — " +
+      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "verbatim; the endpoint defaults to status 'all', so pass " +
+      "{ status: 'pending' } for the usual outstanding-invite list; " +
+      "status 'open' is every invite neither accepted nor revoked (pending " +
+      "or expired). q is a " +
+      "case-insensitive substring match on the invite's name or email. " +
+      "Each row's app_user_id is the id the invitee's user account will " +
+      "have once they accept; a USER column may already hold it, and " +
+      "{ app_user_id, status: 'open' } returns the invite behind such an id " +
+      "(a re-invite keeps the id, so without the status earlier invites " +
+      "match too; an id no invite reserves returns no rows). The WHOLE " +
+      "invite surface — " +
       "list included — is gated on users.write:* plus the users.write " +
       "SystemAcl capability, because a pending invite exposes the email of " +
       "someone who is not a member yet; a users.read-only caller cannot see " +
@@ -1799,7 +1808,7 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
@@ -4767,7 +4776,13 @@ const CONTRACT = deepFreeze({
   // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
   //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
   //    colour that cannot be read against it by the rule its text follows.
-  version: "1.141.0",
+  // 1.142.0: additive (sc-9713) — `useInvites(query)` takes `q`,
+  //    `app_user_id` and `status: "open"`, and each invite row carries
+  //    `app_user_id`: the id the invitee's user account will have once they
+  //    accept.
+  // 1.143.0: additive (sc-9756) — a datastoreTemplate RELATION column may
+  //    declare `onDelete` ("CASCADE" | "SET_NULL") for ONE_TO_ONE/ONE_TO_MANY.
+  version: "1.143.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1787,9 +1787,18 @@ const HOOKS = [
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (email, status, expires_at, …) and " +
       "status is the server-computed pending/accepted/revoked/expired " +
-      "value. query is { status?, limit?, offset? } passed verbatim; the " +
-      "endpoint defaults to status 'all', so pass { status: 'pending' } " +
-      "for the usual outstanding-invite list. The WHOLE invite surface — " +
+      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "verbatim; the endpoint defaults to status 'all', so pass " +
+      "{ status: 'pending' } for the usual outstanding-invite list; " +
+      "status 'open' is every invite neither accepted nor revoked (pending " +
+      "or expired). q is a " +
+      "case-insensitive substring match on the invite's name or email. " +
+      "Each row's app_user_id is the id the invitee's user account will " +
+      "have once they accept; a USER column may already hold it, and " +
+      "{ app_user_id, status: 'open' } returns the invite behind such an id " +
+      "(a re-invite keeps the id, so without the status earlier invites " +
+      "match too; an id no invite reserves returns no rows). The WHOLE " +
+      "invite surface — " +
       "list included — is gated on users.write:* plus the users.write " +
       "SystemAcl capability, because a pending invite exposes the email of " +
       "someone who is not a member yet; a users.read-only caller cannot see " +
@@ -1799,7 +1808,7 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
@@ -4763,7 +4772,13 @@ const CONTRACT = deepFreeze({
   // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
   //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
   //    colour that cannot be read against it by the rule its text follows.
-  version: "1.141.0",
+  // 1.142.0: additive (sc-9713) — `useInvites(query)` takes `q`,
+  //    `app_user_id` and `status: "open"`, and each invite row carries
+  //    `app_user_id`: the id the invitee's user account will have once they
+  //    accept.
+  // 1.143.0: additive (sc-9756) — a datastoreTemplate RELATION column may
+  //    declare `onDelete` ("CASCADE" | "SET_NULL") for ONE_TO_ONE/ONE_TO_MANY.
+  version: "1.143.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -187,6 +187,12 @@ export interface WidgetDatastoreTemplateColumn {
   relationType?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY";
   /** REQ-ACL-RELINHERIT: opt this RELATION column into row-level ACL inheritance. */
   inheritAcl?: boolean;
+  /**
+   * ONE_TO_ONE / ONE_TO_MANY only: what deleting the referenced row does to
+   * this table's rows. `CASCADE` deletes them too; `SET_NULL` (the default)
+   * empties the reference. A MANY_TO_MANY link is always removed.
+   */
+  onDelete?: "CASCADE" | "SET_NULL";
   /**
    * REQ-DDL-ENCRYPT: store this column's values encrypted at rest (AES-256-GCM
    * under a per-workspace subkey). The widget still reads and writes plaintext
@@ -2185,6 +2191,12 @@ export type AppUserInviteStatus =
 
 export interface AppUserInviteRow {
   id: string;
+  /**
+   * The id the invitee's user account will have once they accept. On every
+   * `useInvites()` row and the `resend()` result; `useUsers().invite()` does
+   * not return it.
+   */
+  app_user_id?: string;
   email: string;
   /** Server-computed lifecycle value — prefer it over re-deriving expiry. */
   status: AppUserInviteStatus;
@@ -2258,8 +2270,20 @@ export function useGroups(query?: GroupsQuery): GroupsApi;
 // sc-5097 — pending AppUser invite administration.
 
 export interface InvitesQuery {
-  /** Defaults to "all" server-side; pass "pending" for outstanding invites. */
-  status?: AppUserInviteStatus | "all";
+  /**
+   * Defaults to "all" server-side; pass "pending" for outstanding invites.
+   * "open" is "pending" or "expired": neither accepted nor revoked.
+   */
+  status?: AppUserInviteStatus | "open" | "all";
+  /** Case-insensitive substring match on the invite's name or email. */
+  q?: string;
+  /**
+   * Only the invites reserving this user id (a row's `app_user_id`) — resolves
+   * the person behind an id a USER column holds before they have joined. A
+   * re-invite keeps the id, so add `status: "open"` for the one that still
+   * reserves it. An id no invite reserves returns no rows.
+   */
+  app_user_id?: string;
   limit?: number;
   offset?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.180.1",
+  "version": "0.182.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",