@colixsystems/widget-sdk 0.82.0 → 0.84.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. 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). |
 | **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,18 @@ 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.84.0 (contract 1.59.0)
+
+**A charge is denominated in the WORKSPACE's currency, and a widget that hardcodes a different one no longer publishes (sc-4649).** Every workspace picks the currency it charges its app users in, and `POST /payments/widget-charge` refuses any other code with `UNSUPPORTED_CURRENCY` — but nothing told a widget author which one that was. A widget priced in EUR for a workspace selling in SEK compiled, rendered, and looked finished, then failed every single checkout; the buyer read that as a generic "payment failed" and retried forever. Two changes: `currency` on `requestPayment` is best **omitted** (the platform applies the workspace's own, so it can never be wrong), and a literal that disagrees is now a publish-blocking `payment-currency` finding. Because the expected code is **per-workspace**, the SDK cannot know it: the rule fires only when the caller supplies `lintSource(source, { paymentCurrency })`, which the platform's publish gate does and a local `appstudio-widget lint` does not — it stays silent rather than guessing and flagging correct code. The rule is scoped to the argument of a `requestPayment(...)` call, so a `currency` field elsewhere (a datastore column, an `Intl.NumberFormat` option) is untouched. `CONTRACT.version` → `1.59.0`. Additive; a widget that omits `currency` or already matches its workspace is unaffected.
+
+### 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.
@@ -628,7 +640,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 }>",
     },
@@ -2524,7 +2524,7 @@ const CONTRACT = deepFreeze({
   //    `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.57.0",
+  version: "1.59.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 }>",
     },
@@ -2524,7 +2524,7 @@ const CONTRACT = deepFreeze({
   //    `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.57.0",
+  version: "1.59.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`
@@ -1732,7 +1766,19 @@ export interface LintFinding {
   line: number;
   snippet: string;
 }
-export function lintSource(source: string): {
+export interface LintOptions {
+  manifest?: { requestedScopes?: string[]; supportedPlatforms?: string[] };
+  /**
+   * sc-4649 — the currency the target workspace charges its app users in. A
+   * per-workspace value the SDK cannot know, so the `payment-currency` rule
+   * stays silent unless the caller (the backend publish gate) supplies it.
+   */
+  paymentCurrency?: string;
+}
+export function lintSource(
+  source: string,
+  options?: LintOptions,
+): {
   ok: boolean;
   findings: LintFinding[];
 };

package/dist/linter.cjs

@@ -728,6 +728,77 @@ function _jsxOpenTagEnd(source, from) {
   return source.length;
 }
 
+// sc-4649 — see linter.js for the rationale comment. The two files must stay
+// in lockstep (the contract test asserts behaviour-equivalence).
+const REQUEST_PAYMENT_CALL = "requestPayment(";
+// A generous window: the options object is usually inline, occasionally spread
+// over a few lines. Bounded so an unbalanced source can't scan to EOF.
+const REQUEST_PAYMENT_WINDOW = 400;
+const CURRENCY_LITERAL_RE = /currency\s*:\s*(['"`])\s*([A-Za-z]{2,8})\s*\1/;
+
+function _paymentCurrencyRules(source, paymentCurrency) {
+  const expected = String(paymentCurrency || "").trim().toUpperCase();
+  if (!expected) return [];
+  const findings = [];
+  // Comments blanked, strings kept: the currency code IS a string literal.
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  let from = 0;
+  for (;;) {
+    const at = code.indexOf(REQUEST_PAYMENT_CALL, from);
+    if (at === -1) break;
+    from = at + REQUEST_PAYMENT_CALL.length;
+    const match = CURRENCY_LITERAL_RE.exec(
+      code.slice(at, at + REQUEST_PAYMENT_WINDOW),
+    );
+    if (!match) continue;
+    const found = match[2].toUpperCase();
+    if (found === expected) continue;
+    // Line of the currency literal itself, not of the call.
+    const line = code.slice(0, at + match.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "payment-currency",
+      severity: "error",
+      label:
+        `requestPayment charges in "${found}" but this workspace sells in ` +
+        `${expected}, and the server refuses any other currency, so the ` +
+        `checkout can never complete. Omit currency (the platform applies ` +
+        `${expected}) or pass exactly "${expected}".`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// 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 +893,11 @@ 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(
+    ..._paymentCurrencyRules(source, options && options.paymentCurrency),
+  );
+  findings.push(..._paymentErrorHandlingRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -846,6 +846,93 @@ function _jsxOpenTagEnd(source, from) {
   return source.length;
 }
 
+// sc-4649 — payment-currency.
+//
+// Each workspace charges its app users in ONE currency of its own choosing
+// (`Tenant.app_user_price_currency`), and the server refuses a charge in any
+// other with `UNSUPPORTED_CURRENCY`. A widget that hardcodes a different code
+// compiles, renders, and looks finished, but every checkout it runs dies on a
+// 400 — so this is an `error`, not a warning like `payment-error-not-branched`:
+// a literal mismatch is unambiguous and there is no correct code for an opt-out
+// directive to rescue.
+//
+// The expected currency is a PER-WORKSPACE value the SDK cannot know, so this
+// rule only fires when the caller supplies `options.paymentCurrency` — the
+// backend publish gate does, a bare `appstudio-widget lint` does not. There is
+// deliberately no default: guessing one would flag a correct widget.
+//
+// Scoped to the argument of a `requestPayment(...)` call. A `currency` field
+// elsewhere (a datastore column, an `Intl.NumberFormat` option) is the widget's
+// own display concern and is not judged here.
+const REQUEST_PAYMENT_CALL = "requestPayment(";
+// A generous window: the options object is usually inline, occasionally spread
+// over a few lines. Bounded so an unbalanced source can't scan to EOF.
+const REQUEST_PAYMENT_WINDOW = 400;
+const CURRENCY_LITERAL_RE = /currency\s*:\s*(['"`])\s*([A-Za-z]{2,8})\s*\1/;
+
+function _paymentCurrencyRules(source, paymentCurrency) {
+  const expected = String(paymentCurrency || "").trim().toUpperCase();
+  if (!expected) return [];
+  const findings = [];
+  // Comments blanked, strings kept: the currency code IS a string literal.
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  let from = 0;
+  for (;;) {
+    const at = code.indexOf(REQUEST_PAYMENT_CALL, from);
+    if (at === -1) break;
+    from = at + REQUEST_PAYMENT_CALL.length;
+    const match = CURRENCY_LITERAL_RE.exec(
+      code.slice(at, at + REQUEST_PAYMENT_WINDOW),
+    );
+    if (!match) continue;
+    const found = match[2].toUpperCase();
+    if (found === expected) continue;
+    // Line of the currency literal itself, not of the call.
+    const line = code.slice(0, at + match.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "payment-currency",
+      severity: "error",
+      label:
+        `requestPayment charges in "${found}" but this workspace sells in ` +
+        `${expected}, and the server refuses any other currency, so the ` +
+        `checkout can never complete. Omit currency (the platform applies ` +
+        `${expected}) or pass exactly "${expected}".`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// 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 +1039,11 @@ 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(
+    ..._paymentCurrencyRules(source, options && options.paymentCurrency),
+  );
+  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.82.0",
+  "version": "0.84.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"