@colixsystems/widget-sdk 0.94.0 → 0.96.0

package/README.md

@@ -47,7 +47,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type? })` | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **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:*` (edits also `users.write:*`; `remove()` also `users.delete:*`) |
+| **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useInvites(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** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
@@ -66,6 +66,36 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.91.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.96.0 (contract 1.68.0)
+
+**A manifest action can declare `manual`, and every action script gains a `request` global (sc-5366).** The backend Action model grew three ways of *reaching* a script to sit beside the ones that *fire* it: `manual` (nothing starts it — the workspace runs it on demand), `app` (a published app's button `onPress`) and `http_post` (an inbound webhook at `POST /api/v1/action-hooks/:actionId`, authenticated with one of the workspace's integration API keys). The same change retired the separate `appInvokable` boolean, so one column now answers "what starts this action?".
+
+Only `manual` joins `CONTRACT.actionTriggerTypes`, and that is deliberate. `app` and `http_post` expose a script to a caller **outside** the Studio, which is the installing workspace's decision about running someone else's code — not the author's. A manifest that declares either is rejected by `validateManifest`, the CLI linter and the backend alike; the operator grants them in the Actions admin page after install, on top of whatever triggers your manifest declared. Nothing about an already-published manifest changes.
+
+`CONTRACT.actionScriptGlobals` gains **`request`**: `{ body }` — the JSON an inbound webhook caller sent — on an `http_post` run, and `null` on every other trigger. Request *headers* are never passed through, because they carry the caller's API key. `triggerType` now also reports `"http_post"` alongside `"manual"` and `"app"`, so one script can tell a webhook apart from its nightly schedule:
+
+```js
+if (triggerType === "http_post") {
+  const order = request?.body;
+  if (!order?.id) return; // never trust the caller's shape
+  await datastore.records("Orders").create({ externalId: order.id });
+}
+```
+
+`CONTRACT.version` → `1.68.0`. Additive for every existing manifest.
+
+### What's new in 0.95.0 (contract 1.67.0)
+
+**An admin can mail a locked-out member a password-reset link — `useUsers().sendPasswordReset(userId)` (sc-5335).** An app user who forgot their password could only recover it themselves, from the app's own login screen. The admin they actually ask — the one already able to invite, deactivate and remove them — had no way to help, and the workaround in the field was to remove and re-invite the account, which discards its group memberships and history.
+
+`sendPasswordReset(userId)` mails the **same** self-serve link `POST /auth/app/forgot-password` sends, to that user's **own registered address**, and resolves `{ sent, email_masked }`. It deliberately returns neither the token nor the link, so it is not an account-takeover primitive: an admin can start the recovery, only the user can finish it. `email_masked` (`ad**********@example.com`) is there because a widget caller reads the roster through the privacy-reduced directory projection, which omits email — the confirmation says where the mail went without becoming a new way to read addresses.
+
+- **Scope**: `users.write:*`, alongside `invite` / `deactivate` / `reactivate` — the same grant, since mailing someone a link they must act on is strictly less powerful than deactivating them. The `scope-required-for-user-mutation` linter rule covers the new method, so calling it without the scope fails the lint.
+- **Refusals are typed, not silent.** Rejects with a `DirectoryError` coded `USER_INACTIVE` (deactivated — reactivate first) or `NO_PASSWORD_CREDENTIAL` (an INTEGRATION service account authenticates by API key and holds no password). Branch on `code` and render `err.message`; don't offer the action on those rows at all.
+- Issuing a link supersedes any outstanding one for that user, and the send is rate-limited per acting admin.
+- The built-in **User Management** widget gains the row action and a new `onPasswordResetSent` event.
+- **`CONTRACT.version` → `1.67.0`** (additive: one hook method). No existing signature changed, and both hosts get it from the same injected `@colixsystems/directory-client`.
+
 ### What's new in 0.93.0 (contract 1.66.0)
 
 **BREAKING: a widget no longer declares server-side actions.** `manifest.actions` is removed from the contract and **refused** by `validateManifest` — an author who declares it now fails the publish with a message naming the replacement, rather than shipping a widget that quietly carries no automation.

package/dist/contract.cjs

@@ -957,7 +957,8 @@ const HOOKS = [
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
-  // deactivate / reactivate) additionally need `users.write:*`, and the
+  // deactivate / reactivate / sendPasswordReset) additionally need
+  // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
   // call accepts `{ email, name, groupIds? }` and returns the resulting
   // AppUserInvite row (the email is sent by the host). Mutating users from
@@ -969,15 +970,22 @@ const HOOKS = [
     signature: "useUsers(query?)",
     description:
       "AppUser administration via the injected directory-client at " +
-      "ctx.directory.users.{list,get,invite,deactivate,reactivate}. Returns " +
-      "{ users, loading, error, refetch, invite, deactivate, reactivate, remove }. " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset}. " +
+      "Returns { users, loading, error, refetch, invite, deactivate, " +
+      "reactivate, remove, sendPasswordReset }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
-      "scope; edit-style mutations (invite/deactivate/reactivate) need " +
-      "users.write:*, and the destructive remove() additionally needs " +
-      "users.delete:* (SC-902). The `invite` call accepts " +
+      "scope; edit-style mutations (invite/deactivate/reactivate/" +
+      "sendPasswordReset) need users.write:*, and the destructive remove() " +
+      "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
       "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
-      "(the email is sent by the host).",
+      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
+      "standard self-serve reset link to that user's own registered address " +
+      "and resolves { sent, email_masked } — never the token or the link, so " +
+      "it cannot be used to sign in as them. It rejects with a DirectoryError " +
+      "coded USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL (an " +
+      "INTEGRATION service account); surface those as an explanation rather " +
+      "than a generic failure.",
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
@@ -988,6 +996,8 @@ const HOOKS = [
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
+      sendPasswordReset:
+        "(userId) => Promise<{ sent, email_masked }>  // rejects with DirectoryError",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
@@ -1449,14 +1459,23 @@ const PLATFORMS = ["web", "native"];
 
 // REQ-WIDGET-ACTION — server-side actions a widget may declare in its
 // manifest. Each runs in the shared isolated-vm action runner (see backend
-// action-runner.service.js) on a cron schedule or in response to a record
-// CRUD event — NEVER in the rendered app, so they never affect Player ↔
-// export parity. The trigger vocabulary mirrors the backend Action model.
+// action-runner.service.js) on a cron schedule, in response to a record CRUD
+// event, or on demand — NEVER in the rendered app, so they never affect
+// Player ↔ export parity.
+//
+// This is what a MANIFEST may declare. The backend Action model additionally
+// accepts 'app' and 'http_post' (sc-5366), which expose a script to a
+// published app's buttons or to a public webhook — those are the installing
+// workspace's decision about running someone else's code, so an operator
+// grants them and a manifest may not ask for them. `validateManifest` and the
+// backend's `_validateWidgetDeclared` both reject them, so the linter and the
+// server agree about what a manifest declared.
 const ACTION_TRIGGER_TYPES = [
   "schedule",
   "record_created",
   "record_updated",
   "record_deleted",
+  "manual",
 ];
 // Globals the action script runs against (the runner's surface) — distinct
 // from the React/SDK widget surface, so the component import/banned-API
@@ -1469,6 +1488,9 @@ const ACTION_SCRIPT_GLOBALS = [
   "notifications",
   "console",
   "record",
+  // sc-5366 — `{ body }` on a run fired by the inbound `http_post` trigger,
+  // null on every other trigger.
+  "request",
   "tenantId",
   "triggerType",
   "triggerTableId",
@@ -2922,7 +2944,19 @@ const CONTRACT = deepFreeze({
   // REFUSED by the validator (sc-4879). Server-side automation ships as its own
   // marketplace deliverable (`@colixsystems/action-sdk`), which a workspace
   // installs and configures separately. A widget renders; it does not automate.
-  version: "1.66.0",
+  // 1.67.0: additive (sc-5335) — `useUsers()` gains
+  //    `sendPasswordReset(userId)`, which mails the standard self-serve
+  //    password-reset link to that user's own registered address so an
+  //    app-admin can unblock a locked-out member from inside the app. It
+  //    resolves `{ sent, email_masked }` and never returns the token or the
+  //    link, so it is not an account-takeover primitive; it gates on the same
+  //    `users.write:*` scope as invite / deactivate.
+  // 1.68.0: additive (sc-5366) — a manifest action may declare the `manual`
+  //    trigger (nothing fires it; the workspace runs it on demand), and every
+  //    action script now sees a `request` global — `{ body }` on a run fired
+  //    by the workspace-granted `http_post` webhook trigger, null otherwise.
+  //    `app` and `http_post` stay operator-granted and are NOT declarable.
+  version: "1.68.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -957,7 +957,8 @@ const HOOKS = [
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
-  // deactivate / reactivate) additionally need `users.write:*`, and the
+  // deactivate / reactivate / sendPasswordReset) additionally need
+  // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
   // call accepts `{ email, name, groupIds? }` and returns the resulting
   // AppUserInvite row (the email is sent by the host). Mutating users from
@@ -969,15 +970,22 @@ const HOOKS = [
     signature: "useUsers(query?)",
     description:
       "AppUser administration via the injected directory-client at " +
-      "ctx.directory.users.{list,get,invite,deactivate,reactivate}. Returns " +
-      "{ users, loading, error, refetch, invite, deactivate, reactivate, remove }. " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset}. " +
+      "Returns { users, loading, error, refetch, invite, deactivate, " +
+      "reactivate, remove, sendPasswordReset }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
-      "scope; edit-style mutations (invite/deactivate/reactivate) need " +
-      "users.write:*, and the destructive remove() additionally needs " +
-      "users.delete:* (SC-902). The `invite` call accepts " +
+      "scope; edit-style mutations (invite/deactivate/reactivate/" +
+      "sendPasswordReset) need users.write:*, and the destructive remove() " +
+      "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
       "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
-      "(the email is sent by the host).",
+      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
+      "standard self-serve reset link to that user's own registered address " +
+      "and resolves { sent, email_masked } — never the token or the link, so " +
+      "it cannot be used to sign in as them. It rejects with a DirectoryError " +
+      "coded USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL (an " +
+      "INTEGRATION service account); surface those as an explanation rather " +
+      "than a generic failure.",
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
@@ -988,6 +996,8 @@ const HOOKS = [
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
+      sendPasswordReset:
+        "(userId) => Promise<{ sent, email_masked }>  // rejects with DirectoryError",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
@@ -1449,14 +1459,23 @@ const PLATFORMS = ["web", "native"];
 
 // REQ-WIDGET-ACTION — server-side actions a widget may declare in its
 // manifest. Each runs in the shared isolated-vm action runner (see backend
-// action-runner.service.js) on a cron schedule or in response to a record
-// CRUD event — NEVER in the rendered app, so they never affect Player ↔
-// export parity. The trigger vocabulary mirrors the backend Action model.
+// action-runner.service.js) on a cron schedule, in response to a record CRUD
+// event, or on demand — NEVER in the rendered app, so they never affect
+// Player ↔ export parity.
+//
+// This is what a MANIFEST may declare. The backend Action model additionally
+// accepts 'app' and 'http_post' (sc-5366), which expose a script to a
+// published app's buttons or to a public webhook — those are the installing
+// workspace's decision about running someone else's code, so an operator
+// grants them and a manifest may not ask for them. `validateManifest` and the
+// backend's `_validateWidgetDeclared` both reject them, so the linter and the
+// server agree about what a manifest declared.
 const ACTION_TRIGGER_TYPES = [
   "schedule",
   "record_created",
   "record_updated",
   "record_deleted",
+  "manual",
 ];
 // Globals the action script runs against (the runner's surface) — distinct
 // from the React/SDK widget surface, so the component import/banned-API
@@ -1469,6 +1488,9 @@ const ACTION_SCRIPT_GLOBALS = [
   "notifications",
   "console",
   "record",
+  // sc-5366 — `{ body }` on a run fired by the inbound `http_post` trigger,
+  // null on every other trigger.
+  "request",
   "tenantId",
   "triggerType",
   "triggerTableId",
@@ -2922,7 +2944,19 @@ const CONTRACT = deepFreeze({
   // REFUSED by the validator (sc-4879). Server-side automation ships as its own
   // marketplace deliverable (`@colixsystems/action-sdk`), which a workspace
   // installs and configures separately. A widget renders; it does not automate.
-  version: "1.66.0",
+  // 1.67.0: additive (sc-5335) — `useUsers()` gains
+  //    `sendPasswordReset(userId)`, which mails the standard self-serve
+  //    password-reset link to that user's own registered address so an
+  //    app-admin can unblock a locked-out member from inside the app. It
+  //    resolves `{ sent, email_masked }` and never returns the token or the
+  //    link, so it is not an account-takeover primitive; it gates on the same
+  //    `users.write:*` scope as invite / deactivate.
+  // 1.68.0: additive (sc-5366) — a manifest action may declare the `manual`
+  //    trigger (nothing fires it; the workspace runs it on demand), and every
+  //    action script now sees a `request` global — `{ body }` on a run fired
+  //    by the workspace-granted `http_post` webhook trigger, null otherwise.
+  //    `app` and `http_post` stay operator-granted and are NOT declarable.
+  version: "1.68.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3363,8 +3363,37 @@ export function useUsers(query) {
       throw toDirectoryError(err);
     }
   }, []);
+  // sc-5335: mail the self-serve reset link to a user who has locked
+  // themselves out. Resolves `{ sent, email_masked }`; the host never returns
+  // the token, so this cannot be used to sign in as that user. Rejects with a
+  // DirectoryError carrying `code` USER_INACTIVE or NO_PASSWORD_CREDENTIAL
+  // when the target cannot receive one.
+  const sendPasswordReset = useCallback(async (userId) => {
+    if (typeof usersRef.current.sendPasswordReset !== "function") {
+      throw toDirectoryError(
+        new Error(
+          "useUsers: this host's directory client predates sendPasswordReset",
+        ),
+      );
+    }
+    try {
+      return await usersRef.current.sendPasswordReset(userId);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
 
-  return { users, loading, error, refetch, invite, deactivate, reactivate, remove };
+  return {
+    users,
+    loading,
+    error,
+    refetch,
+    invite,
+    deactivate,
+    reactivate,
+    remove,
+    sendPasswordReset,
+  };
 }
 
 /**

package/dist/index.d.ts

@@ -229,17 +229,25 @@ export interface WidgetManifestAction {
    * that actually fired.
    */
   triggerTypes: Array<
-    "schedule" | "record_created" | "record_updated" | "record_deleted"
+    | "schedule"
+    | "record_created"
+    | "record_updated"
+    | "record_deleted"
+    // sc-5366 — nothing fires it; the workspace runs it on demand. The
+    // `"app"` and `"http_post"` triggers are operator-granted, not declarable.
+    | "manual"
   >;
   /** Required iff `triggerTypes` contains `"schedule"`. node-cron syntax. */
   scheduleCron?: string;
   /** 100–300000. Defaults to 30000 on materialise. */
   timeoutMs?: number;
   /**
-   * Runs against `datastore`, `fetch`, `console`, `record`, `tenantId`,
-   * `triggerType`, `triggerTableId` — NOT the React/SDK surface. ≤ 200 KiB.
-   * `triggerType` is the trigger that fired THIS run — one of the declared
-   * `triggerTypes`, or `"manual"` / `"app"` for an operator or button run.
+   * Runs against `datastore`, `fetch`, `console`, `record`, `request`,
+   * `tenantId`, `triggerType`, `triggerTableId` — NOT the React/SDK surface.
+   * ≤ 200 KiB. `triggerType` is the trigger that fired THIS run — one of the
+   * declared `triggerTypes`, or `"manual"` / `"app"` / `"http_post"` for an
+   * operator, button or webhook run. `request` is `{ body }` on a webhook run
+   * and `null` otherwise (sc-5366).
    */
   scriptSource: string;
 }

package/dist/linter.cjs

@@ -428,7 +428,14 @@ function _translationApiRules(source) {
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation. See
 // linter.js for the rationale comment. The two files must stay in
 // lockstep (the contract test asserts behaviour-equivalence).
-const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate"];
+const USER_MUTATION_METHODS = [
+  "invite",
+  "deactivate",
+  "reactivate",
+  // sc-5335 — mailing a reset link is edit-style, so it rides `users.write`
+  // alongside deactivate rather than the destructive `users.delete`.
+  "sendPasswordReset",
+];
 // SC-902 — destructive user removal is gated on the dedicated
 // `users.delete` capability, NOT `users.write`. A widget that calls
 // useUsers().remove() must declare `users.delete:*` so the static contract

package/dist/linter.js

@@ -485,7 +485,8 @@ function _translationApiRules(source) {
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation.
 //
 // A widget that calls `useUsers().invite()` / `.deactivate()` /
-// `.reactivate()` / `.remove()` MUST declare `users.write:*` in its
+// `.reactivate()` / `.sendPasswordReset()` / `.remove()` MUST declare
+// `users.write:*` in its
 // manifest's `requestedScopes`; similarly `useGroups()` mutation methods
 // require `groups.write:*`. The rule is enforced statically so a manifest
 // that drifts from the source (e.g. an author forgot to add the scope
@@ -498,7 +499,14 @@ function _translationApiRules(source) {
 // AST-free; an author whose code happened to spell `.invite(` for an
 // unrelated reason can opt out with a `// @appstudio-skip-scope-check`
 // trailing comment on the offending line.
-const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate"];
+const USER_MUTATION_METHODS = [
+  "invite",
+  "deactivate",
+  "reactivate",
+  // sc-5335 — mailing a reset link is edit-style, so it rides `users.write`
+  // alongside deactivate rather than the destructive `users.delete`.
+  "sendPasswordReset",
+];
 // SC-902 — destructive user removal is gated on the dedicated
 // `users.delete` capability, NOT `users.write`. A widget that calls
 // useUsers().remove() must declare `users.delete:*` so the static contract

package/package.json

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