@colixsystems/widget-sdk 0.81.0 → 0.83.0

package/README.md

@@ -48,7 +48,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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) |
 | **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId? })` | `{ exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.exportPdf` — `files.write:*`. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF server-side 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` |
+| **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. |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. |
 | **IDENTIFICATION** (`ctx.identification`) | `useIdentification({ provider?, purpose?, pollIntervalMs? })` | `{ available, status, qr, autoStartToken, message, identity, identificationId, start, refresh, cancel, reset, … }` | `ctx.identification.*` — no scope (the visitor is deliberately NOT signed in). Gate the UI on `available`; `start()` opens the order and the hook polls to completion. `identity` carries `personal_number_masked` + a stable `subject_hash` — never a raw personal number. |
 
@@ -62,6 +62,22 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.77.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.83.0 (contract 1.58.0)
+
+**`PaymentError` tells you WHY a charge was refused, and whether retrying could ever help (sc-4650).** `usePayments()` mapped its rejections by reading `err.response`, but `@colixsystems/payments-client` throws typed errors carrying `.code` / `.status` / `.details` (the parsed error envelope) and no `.response` at all — so every server refusal arrived as `code: "INTERNAL"` and the real reason was buried on `err.cause`. A widget could not tell a workspace that has not declared its business identity yet (`BUSINESS_IDENTITY_REQUIRED`, which no retry clears) from a declined card.
+
+- **Both error shapes are read, and the envelope wins.** The mapper takes the server's own `code` (`BUSINESS_IDENTITY_REQUIRED`, `UNSUPPORTED_CURRENCY`, `PAYMENTS_SCOPE_NOT_GRANTED`, …) over the client's status-derived class code, and keeps the server's user-safe `message`. The host's local `.response` rejections (no install bound → `PAYMENTS_UNAVAILABLE`) still map exactly as before.
+- **New `retryable` flag.** `false` for any refusal only the workspace owner, the manifest, or the amount can lift; `true` for a decline, a provider blip, or an unknown failure. Branch on it: render `err.message` and drop the retry control when it is `false`, and keep "try again" for the retryable case only.
+- **New lint warning `payment-error-not-branched`.** A widget that calls `requestPayment()` but never reads `retryable` (or branches on an explicit `err.code`) is flagged — non-blocking, so it never fails a publish.
+
+### What's new in 0.82.0 (contract 1.57.0)
+
+**Server-action scripts can notify a record's permission subjects (REQ-ACTION-NOTIFY-SUBJECTS, sc-4586).** `await notifications.notifyRecordSubjects(tableId, recordId, { title, body, link, emit_email, emit_push, exclude_user_id })` resolves to `{ recipients }` and notifies every app user whose per-record grant lets them **read** that record. This addresses the one audience the other two primitives cannot name: when membership *is* the ACL, there is no recipient column to read. The Chat widget is the case in point — a channel's participants ARE that channel record's grants, so neither a `recipient_expr` (which resolves only a fixed id or a single user/group reference column) nor a `notifyUser` loop over a column that does not exist can reach them. Subject kinds follow REQ-ACL-09: a `user` grant notifies its user, a `group` grant expands through its memberships, and the two synthetic kinds (`authenticated`, `everyone`) are skipped because they address the whole workspace rather than a membership. Recipients are **deduplicated**, so someone reachable through both a direct grant and a granted group is notified once, and `exclude_user_id` drops one — pass the author so nobody is notified of their own write. Dispatch goes through the same `notifyUser` path as before, so the always-written inbox row, the preference-gated email + push mirrors, the link sanitiser and the title/body caps are inherited unchanged, and written rows count toward the same per-run cap of 500. The tenant is bound host-side and the table/record pair is verified against it, so a foreign or missing id resolves to `{ recipients: 0 }` rather than distinguishing "absent" from "not yours". **The script never receives the member list — only the count.** `CONTRACT.version` → `1.57.0`. Additive; no widget hook, primitive, manifest field, or token changed shape.
+
+### 0.82.0 also carries (contract 1.56.0)
+
+**Server-action scripts gain a `notifications` global (REQ-ACTION-NOTIFY, sc-4514).** A `scriptSource` action can now send a real notification to a recipient it resolves at run time: `await notifications.notifyUser(userId, { title, body, link, emit_email, emit_push })` and `await notifications.notifyGroup(groupId, opts)`. Options are **snake_case**, matching every other shape a script sees. `notifyUser` resolves to the created notification row (or `null` when the recipient was skipped); `notifyGroup` resolves to `{ recipients }`. This is a directness change rather than a new capability: an action could already notify indirectly by writing into a table carrying an enabled `NotificationRule`, but that costs a throwaway table, a per-table rule, a recipient expressible only as a fixed id or one reference column — and it fails silently, since with no rule attached the row just lands and the run still reports success. `POST /notifications/send` is no alternative (it needs an app-user JWT an action cannot hold). The direct call removes the intermediary and makes a non-delivery throw. Both methods delegate to the platform's one notification dispatch path, so the inbox row is always written, the email + push mirrors respect the recipient's channel preferences, and the push ping never carries the title or body. The tenant is bound host-side: a recipient in another workspace, a soft-deleted group, or a deactivated user is a silent skip, never a cross-tenant write. A blank `title`, a non-string `body`, or exceeding the per-run cap of 500 written notifications throws a catchable Error. New entry in `CONTRACT.actionScriptGlobals`; `CONTRACT.version` → `1.56.0`. Additive — no widget hook, primitive, manifest field, or token changed shape.
+
 ### What's new in 0.78.0
 
 **New `useIdentification()` hook — identify a visitor who is NOT signed in (REQ-IDENT, sc-4313).** A new IDENTIFICATION hook reading a newly-injected `ctx.identification` slice (the new `@colixsystems/identification-client`, constructed by both the web Player and the native Expo export). Returns `{ available, availabilityLoading, status, qr, autoStartToken, message, identity, identificationId, loading, error, start, refresh, cancel, reset }`.
@@ -620,7 +636,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.

package/dist/contract.cjs

@@ -803,7 +803,7 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError",
+        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
       getPayment:
         "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
     },
@@ -1269,6 +1269,7 @@ const ACTION_SCRIPT_GLOBALS = [
   "secrets",
   "fetch",
   "connectors",
+  "notifications",
   "console",
   "record",
   "tenantId",
@@ -2506,7 +2507,24 @@ const CONTRACT = deepFreeze({
   //    already measured its own box with onLayout; this promotes that one
   //    pattern to the SDK so custom and marketplace widgets get it too,
   //    instead of each rolling its own.
-  version: "1.55.0",
+  // 1.55.0: additive (sc-4505) — `useWidgetInput(inputName)` + the
+  //    `PAYLOAD_VALUE_TYPES` a widget event payload field may declare, so
+  //    widgets on one page relate through declared inputs.
+  // 1.56.0: additive (sc-4514) — `notifications` joins
+  //    `actionScriptGlobals`. `notifications.notifyUser(id, opts)` /
+  //    `notifyGroup(id, opts)` delegate to the one notification dispatch path.
+  //    Directness, not a new capability: an action could already notify by
+  //    writing into a table carrying a NotificationRule, but that needs a
+  //    throwaway table plus a per-table rule and fails SILENTLY when no rule
+  //    is attached — the row lands and the run still reports success.
+  // 1.57.0: additive (sc-4586) — `notifications.notifyRecordSubjects(tableId,
+  //    recordId, opts)`, resolving to { recipients }. Notifies whoever a
+  //    record's per-record grants let read it, which is the only way to address
+  //    membership-by-ACL: a Chat channel's participants ARE its grants, so no
+  //    `recipient_expr` shape and no recipient column can name them. The member
+  //    list stays host-side — a script receives a count, never the ids — and
+  //    `exclude_user_id` keeps an author off their own message.
+  version: "1.58.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -803,7 +803,7 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError",
+        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
       getPayment:
         "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
     },
@@ -1269,6 +1269,7 @@ const ACTION_SCRIPT_GLOBALS = [
   "secrets",
   "fetch",
   "connectors",
+  "notifications",
   "console",
   "record",
   "tenantId",
@@ -2506,7 +2507,24 @@ const CONTRACT = deepFreeze({
   //    already measured its own box with onLayout; this promotes that one
   //    pattern to the SDK so custom and marketplace widgets get it too,
   //    instead of each rolling its own.
-  version: "1.55.0",
+  // 1.55.0: additive (sc-4505) — `useWidgetInput(inputName)` + the
+  //    `PAYLOAD_VALUE_TYPES` a widget event payload field may declare, so
+  //    widgets on one page relate through declared inputs.
+  // 1.56.0: additive (sc-4514) — `notifications` joins
+  //    `actionScriptGlobals`. `notifications.notifyUser(id, opts)` /
+  //    `notifyGroup(id, opts)` delegate to the one notification dispatch path.
+  //    Directness, not a new capability: an action could already notify by
+  //    writing into a table carrying a NotificationRule, but that needs a
+  //    throwaway table plus a per-table rule and fails SILENTLY when no rule
+  //    is attached — the row lands and the run still reports success.
+  // 1.57.0: additive (sc-4586) — `notifications.notifyRecordSubjects(tableId,
+  //    recordId, opts)`, resolving to { recipients }. Notifies whoever a
+  //    record's per-record grants let read it, which is the only way to address
+  //    membership-by-ACL: a Chat channel's participants ARE its grants, so no
+  //    `recipient_expr` shape and no recipient column can name them. The member
+  //    list stays host-side — a script receives a count, never the ids — and
+  //    `exclude_user_id` keeps an author off their own message.
+  version: "1.58.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3462,39 +3462,83 @@ export function useIdentification(options) {
  * requestPayment, getPayment. Covers: usePayments.
  * ==========================================================================*/
 
+// sc-4650 — the refusals that retrying the SAME charge can never clear: the
+// workspace, the widget manifest, or the amount has to change first. Everything
+// else (a decline, a provider blip, an unknown failure) is worth another
+// attempt. A widget reads this through `PaymentError.retryable`.
+const NON_RETRYABLE_PAYMENT_CODES = new Set([
+  "AUTH_REQUIRED",
+  "AMOUNT_TOO_LARGE",
+  "BUSINESS_IDENTITY_REQUIRED",
+  "CONNECT_NOT_READY",
+  "FORBIDDEN",
+  "INVALID_AMOUNT",
+  "NOT_FOUND",
+  "PAYMENTS_DISABLED",
+  "PAYMENTS_SCOPE_NOT_GRANTED",
+  "PAYMENTS_UNAVAILABLE",
+  "UNSUPPORTED_CURRENCY",
+  "VALIDATION",
+]);
+
 /**
  * Structured error thrown by `usePayments` callbacks. Carries a stable
- * `code` so widgets can branch without parsing message strings.
- *
- * `code` is one of:
- *   - "AUTH_REQUIRED"             — no signed-in app user
- *   - "PAYMENTS_SCOPE_NOT_GRANTED"— widget lacks payments.charge:appUser
+ * `code` so widgets can branch without parsing message strings, and
+ * `retryable` so they can tell "try again" from "this cannot work yet".
+ *
+ * `code` is the server's own code when it sent one, else a status-derived
+ * fallback:
+ *   - "AUTH_REQUIRED"              — no signed-in app user
+ *   - "BUSINESS_IDENTITY_REQUIRED" — the workspace has not declared its
+ *                                    business identity, so it may not collect
+ *                                    money yet
+ *   - "PAYMENTS_SCOPE_NOT_GRANTED" — widget lacks payments.charge:appUser
+ *   - "PAYMENTS_UNAVAILABLE"       — no installed widget / no payments host
+ *   - "UNSUPPORTED_CURRENCY"       — not the platform's charge currency
  *   - "INVALID_AMOUNT" / "AMOUNT_TOO_LARGE" / "VALIDATION" — bad request
  *   - "CONNECT_NOT_READY" / "PAYMENTS_DISABLED" — provider not ready
- *   - "DECLINED"                  — the charge was declined
- *   - "INTERNAL"                  — anything else
+ *   - "DECLINED"                   — the charge was declined
+ *   - "INTERNAL"                   — anything else
+ *
+ * `message` is the server's own user-safe sentence when it sent one — show it
+ * for a non-retryable refusal rather than a generic "payment failed", which
+ * tells the payer nothing about a block only the workspace owner can lift.
  */
 export class PaymentError extends Error {
   constructor(code, message, opts) {
     super(message);
     this.name = "PaymentError";
     this.code = code;
+    this.retryable = !NON_RETRYABLE_PAYMENT_CODES.has(code);
     if (opts && opts.cause) this.cause = opts.cause;
   }
 }
 
+// sc-4650 — the payments client throws typed `PaymentsError` subclasses that
+// carry `.code` / `.status` / `.details` (the parsed error envelope) and NO
+// `.response`, while the host's local rejections carry `.response` instead.
+// Reading only `.response` collapsed every server refusal to "INTERNAL" and
+// buried the real code, so a widget could not tell a business-identity block
+// from a declined card. Read BOTH shapes, and prefer the envelope's `code`
+// (the precise reason) over the client's status-derived class code.
 function toPaymentError(err) {
   if (err instanceof PaymentError) return err;
+  const response = (err && err.response) || null;
+  const body = (response && response.data) || (err && err.details) || null;
   const status =
-    err && err.response && typeof err.response.status === "number"
-      ? err.response.status
-      : null;
-  const bodyCode =
-    err && err.response && err.response.data && err.response.data.code;
-  const bodyMessage =
-    err && err.response && err.response.data && err.response.data.error;
+    response && typeof response.status === "number"
+      ? response.status
+      : err && typeof err.status === "number" && err.status
+        ? err.status
+        : null;
+  const bodyCode = body && body.code;
+  const clientCode = err && err.code;
+  // `message` is the canonical envelope's field (REQ-GEN-05); `error` is the
+  // ad-hoc envelope a few older surfaces still emit.
+  const bodyMessage = body && (body.message || body.error);
   let code = "INTERNAL";
   if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
+  else if (typeof clientCode === "string" && clientCode) code = clientCode;
   else if (status === 401) code = "AUTH_REQUIRED";
   else if (status === 402) code = "DECLINED";
   else if (status === 403) code = "FORBIDDEN";

package/dist/index.d.ts

@@ -766,6 +766,40 @@ export interface PaymentsApi {
  */
 export function usePayments(): PaymentsApi;
 
+/**
+ * Rejection thrown by both `usePayments()` callbacks. `code` is the server's
+ * own reason when it sent one; `message` is its user-safe sentence. Branch on
+ * `retryable`: false means the same charge can never succeed until the
+ * workspace, the manifest, or the amount changes — show the reason, not a
+ * "try again" that loops the payer forever.
+ */
+export class PaymentError extends Error {
+  code:
+    | "AUTH_REQUIRED"
+    | "BUSINESS_IDENTITY_REQUIRED"
+    | "PAYMENTS_SCOPE_NOT_GRANTED"
+    | "PAYMENTS_UNAVAILABLE"
+    | "UNSUPPORTED_CURRENCY"
+    | "INVALID_AMOUNT"
+    | "AMOUNT_TOO_LARGE"
+    | "VALIDATION"
+    | "CONNECT_NOT_READY"
+    | "PAYMENTS_DISABLED"
+    | "DECLINED"
+    | "FORBIDDEN"
+    | "NOT_FOUND"
+    | "RATE_LIMITED"
+    | "INTERNAL"
+    | string;
+  /** False when retrying the same charge can never succeed. */
+  retryable: boolean;
+  constructor(
+    code: string,
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * Arguments for `useSendNotification().send(...)`. snake_case VERBATIM — this
  * is the wire contract (REQ-GEN-09). `recipient_user_id`, `title`, and `body`

package/dist/linter.cjs

@@ -728,6 +728,34 @@ function _jsxOpenTagEnd(source, from) {
   return source.length;
 }
 
+// sc-4650 — soft warning: a widget that charges must tell a failure worth
+// retrying from a refusal only the workspace owner can lift. Collapsing every
+// rejection into one "please try again" is what sent payers round an
+// unbreakable loop on BUSINESS_IDENTITY_REQUIRED. `PaymentError.retryable` (or
+// an explicit `err.code === "…"` branch) is the signal; strings and comments
+// are blanked so prose about retrying never satisfies the check.
+function _paymentErrorHandlingRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\brequestPayment\s*\(/.exec(code);
+  if (!call) return [];
+  if (/\bretryable\b/.test(code)) return [];
+  if (/\bcode\s*===/.test(code)) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "payment-error-not-branched",
+      severity: "warning",
+      label:
+        `charges with requestPayment() but never reads ` +
+        `PaymentError.retryable — a refusal like BUSINESS_IDENTITY_REQUIRED ` +
+        `can never succeed on retry, so render err.message instead of a ` +
+        `generic "try again".`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   const code = _stripNonCode(source, { keepStrings: true });
@@ -822,6 +850,8 @@ function lintSource(source, options) {
   findings.push(..._lucideIconRules(source));
   findings.push(..._reactInScopeRules(source));
   findings.push(..._imagePercentHeightRules(source));
+  // sc-4650 — soft warning: every payment refusal reported as "try again".
+  findings.push(..._paymentErrorHandlingRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -846,6 +846,34 @@ function _jsxOpenTagEnd(source, from) {
   return source.length;
 }
 
+// sc-4650 — soft warning: a widget that charges must tell a failure worth
+// retrying from a refusal only the workspace owner can lift. Collapsing every
+// rejection into one "please try again" is what sent payers round an
+// unbreakable loop on BUSINESS_IDENTITY_REQUIRED. `PaymentError.retryable` (or
+// an explicit `err.code === "…"` branch) is the signal; strings and comments
+// are blanked so prose about retrying never satisfies the check.
+function _paymentErrorHandlingRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\brequestPayment\s*\(/.exec(code);
+  if (!call) return [];
+  if (/\bretryable\b/.test(code)) return [];
+  if (/\bcode\s*===/.test(code)) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "payment-error-not-branched",
+      severity: "warning",
+      label:
+        `charges with requestPayment() but never reads ` +
+        `PaymentError.retryable — a refusal like BUSINESS_IDENTITY_REQUIRED ` +
+        `can never succeed on retry, so render err.message instead of a ` +
+        `generic "try again".`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   // Comments are blanked (string contents kept) so a commented-out example —
@@ -952,6 +980,8 @@ export function lintSource(source, options) {
   findings.push(..._reactInScopeRules(source));
   // sc-3493 — soft warning: percentage height on an <Image> collapses to 0.
   findings.push(..._imagePercentHeightRules(source));
+  // sc-4650 — soft warning: every payment refusal reported as "try again".
+  findings.push(..._paymentErrorHandlingRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.81.0",
+  "version": "0.83.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
   },
   "engines": {
     "node": ">=18"