@colixsystems/widget-sdk 0.83.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`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. |
+| **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,10 @@ 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.

package/dist/contract.cjs

@@ -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.58.0",
+  version: "1.59.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -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.58.0",
+  version: "1.59.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -1766,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,49 @@ 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
@@ -851,6 +894,9 @@ function lintSource(source, options) {
   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) => ({

package/dist/linter.js

@@ -846,6 +846,65 @@ 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
@@ -981,6 +1040,9 @@ export function lintSource(source, options) {
   // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.83.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",