@colixsystems/widget-sdk 0.83.0 → 0.85.0

package/README.md

@@ -18,6 +18,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
 | **CORE** | `useTheme()` | `{ colors, elevation, spacing, radii, typography, components }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`). `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
+| **CORE** | `useWorkspaceCurrency()` | `{ currency, formatMoney }` | `ctx.workspace.currency` — no scope. The currency this workspace charges its app users in, resolved at RENDER time. Render every price as `formatMoney(minorUnits)` and never write a currency symbol or code into a widget: the owner can change it after the widget ships, and a baked label then contradicts the charge. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
@@ -48,7 +49,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 +63,14 @@ 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.85.0 (contract 1.60.0)
+
+**A widget must never name a currency — `useWorkspaceCurrency()` resolves it at render time (sc-4686).** A workspace picks the currency it charges its app users in, and the owner usually sets that *after* the app is built (the normal order is prompt first, billing later). So anything a widget wrote down — a `"kr"` in JSX, a `€` in a `manifest.translations` string, a `currency` argument on `requestPayment` — kept displaying the old currency over a charge that had correctly followed the change: one price shown, another taken. Currency is workspace configuration that changes after authoring, exactly like `theme` and `locale`, so it now joins them on the host-resolved `ctx.workspace` slice. `useWorkspaceCurrency()` returns `{ currency, formatMoney }`; `formatMoney(45000)` renders `"450,00 kr"` or `"450,00 €"` from `CONTRACT.currencyFormats` — an explicit table, not `Intl.NumberFormat`, which does not agree between the exported Expo app and react-native-web. Omit `currency` on `requestPayment` and the platform applies the workspace's own, so it can never be wrong. Enforcement tightened to match: `payment-currency` now rejects **any** currency literal (one that matches today still lies tomorrow) and so needs no per-workspace option — it fires in a bare `appstudio-widget lint`, and `lintSource`'s `paymentCurrency` option is removed; a new `no-hardcoded-currency-label` warning catches a symbol or code beside a price in a charging widget. `CONTRACT.version` → `1.60.0`. Additive for a widget that already omits `currency`.
+
+### 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

@@ -810,6 +810,22 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-4686 — the workspace's charge currency + the only sanctioned way to
+  // render money. A widget must NOT name a currency: the owner can change it
+  // after the widget was authored, so a baked symbol goes stale over a charge
+  // that followed the change.
+  {
+    name: "useWorkspaceCurrency",
+    signature: "useWorkspaceCurrency()",
+    returnShape: {
+      currency:
+        "string  // the ISO code this workspace charges its app users in, e.g. \"SEK\"",
+      formatMoney:
+        "(minorUnits) => string  // 45000 -> \"450,00 kr\"; renders identically on web and native. NEVER write a currency symbol or code yourself",
+    },
+    requiredContextSlice: ["workspace.currency"],
+    scopes: null,
+  },
   // sc-890 — send an in-app notification to one app user in the tenant.
   // IMPERATIVE: send() never fires on mount; the widget calls it from an
   // event handler. Reads ctx.notifications.send (the injected
@@ -1457,13 +1473,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   workspace: {
     description:
-      "Workspace identity + resolved theme ({ id, slug, theme, locale }).",
+      "Workspace identity + resolved theme + charge currency ({ id, slug, theme, locale, currency }).",
     required: true,
     fields: {
       id: "string",
       slug: "string",
       theme: "ThemeTokens",
       locale: "string",
+      // sc-4686 — the ISO code this workspace charges its app users in.
+      currency: "string",
     },
   },
   navigation: {
@@ -2010,6 +2028,115 @@ const TRANSLATION_API_HOSTS = [
   "lingvanex.com",
 ];
 
+// sc-4686 — the currency a price renders in when the HOST does not supply the
+// workspace's own (a host predating the workspace.currency slice, or a caller
+// that forgot to wire it). A rendering fallback so a price is never blank or
+// "undefined" — NOT a statement about which currencies the server accepts,
+// which is per-workspace and operator-configured (sc-4649).
+const CHARGE_CURRENCY = "SEK";
+
+// sc-4686 — how each accepted currency is written, so a widget never has to.
+//
+// A widget must not name a currency: it is workspace configuration the owner
+// can change AFTER the widget was authored (see `chargeCurrency` on the
+// workspace context slice), so a baked "kr" or "€" goes stale the moment they
+// switch. Widgets render money through `useWorkspaceCurrency().formatMoney`,
+// which reads this table.
+//
+// Deliberately NOT `Intl.NumberFormat`: the exported Expo app and
+// react-native-web do not agree on its output (the same reason widgets format
+// dates with `date-fns` rather than `toLocaleDateString`), and this string ends
+// up on a price the buyer compares against the amount they are charged. An
+// explicit table renders byte-identically on both hosts.
+//
+// `symbol` is written `before` or `after` the amount; `space` inserts a
+// non-breaking gap between them. `decimals` is the minor-unit exponent, so it
+// is also how many minor units make one major unit.
+const CURRENCY_FORMATS = {
+  SEK: { symbol: "kr", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  NOK: { symbol: "kr", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  DKK: { symbol: "kr.", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  ISK: { symbol: "kr", position: "after", space: true, decimals: 0, decimalSeparator: ",", groupSeparator: "." },
+  EUR: { symbol: "€", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  GBP: { symbol: "£", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  USD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  CAD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  AUD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  NZD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  CHF: { symbol: "CHF", position: "before", space: true, decimals: 2, decimalSeparator: ".", groupSeparator: "'" },
+  PLN: { symbol: "zł", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  CZK: { symbol: "Kč", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  HUF: { symbol: "Ft", position: "after", space: true, decimals: 0, decimalSeparator: ",", groupSeparator: " " },
+  RON: { symbol: "lei", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  BGN: { symbol: "лв", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  JPY: { symbol: "¥", position: "before", space: false, decimals: 0, decimalSeparator: ".", groupSeparator: "," },
+  INR: { symbol: "₹", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  ILS: { symbol: "₪", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  ZAR: { symbol: "R", position: "before", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  MXN: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  BRL: { symbol: "R$", position: "before", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  SGD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  HKD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  AED: { symbol: "AED", position: "before", space: true, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  TRY: { symbol: "₺", position: "before", space: false, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  THB: { symbol: "฿", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  KRW: { symbol: "₩", position: "before", space: false, decimals: 0, decimalSeparator: ".", groupSeparator: "," },
+  CNY: { symbol: "¥", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+};
+
+// An unlisted currency still has to render something a buyer can read, so the
+// ISO code stands in for a symbol rather than the amount appearing bare.
+const CURRENCY_FORMAT_FALLBACK = Object.freeze({
+  position: "after",
+  space: true,
+  decimals: 2,
+  decimalSeparator: ".",
+  groupSeparator: ",",
+});
+
+// sc-4686 — the ISO code a workspace charges in, normalised. An empty value
+// means a host that predates the `workspace.currency` slice; falling back to the
+// platform default keeps a price rendering rather than printing "undefined" next
+// to an amount, which is the one place a blank is unacceptable.
+function normaliseCurrencyCode(value) {
+  const code = typeof value === "string" ? value.trim().toUpperCase() : "";
+  return code || CHARGE_CURRENCY;
+}
+
+/**
+ * `formatMoneyIn("SEK", 45000)` → `"450,00 kr"`.
+ *
+ * Takes MINOR units — the same unit `requestPayment` charges in — so there is no
+ * conversion step for a widget to get wrong. Renders from `CURRENCY_FORMATS`
+ * rather than `Intl.NumberFormat`, which does not produce identical output in
+ * the exported Expo app and react-native-web; this string sits beside the amount
+ * the buyer is actually charged, so the two hosts must agree exactly.
+ *
+ * A non-finite amount renders as zero rather than "NaN": a price whose data has
+ * not loaded should read as an amount, never as a broken string in a checkout.
+ */
+function formatMoneyIn(currency, minorUnits) {
+  const code = normaliseCurrencyCode(currency);
+  const fmt = CURRENCY_FORMATS[code] || {
+    ...CURRENCY_FORMAT_FALLBACK,
+    symbol: code,
+  };
+  const amount = Number(minorUnits);
+  const safe = Number.isFinite(amount) ? Math.round(amount) : 0;
+  const negative = safe < 0;
+  const digits = String(Math.abs(safe)).padStart(fmt.decimals + 1, "0");
+  const whole = fmt.decimals > 0 ? digits.slice(0, -fmt.decimals) : digits;
+  const cents = fmt.decimals > 0 ? digits.slice(-fmt.decimals) : "";
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, fmt.groupSeparator);
+  const body = cents ? `${grouped}${fmt.decimalSeparator}${cents}` : grouped;
+  const gap = fmt.space ? " " : "";
+  const withSymbol =
+    fmt.position === "before"
+      ? `${fmt.symbol}${gap}${body}`
+      : `${body}${gap}${fmt.symbol}`;
+  return negative ? `-${withSymbol}` : withSymbol;
+}
+
 function deepFreeze(value) {
   if (value === null || typeof value !== "object") return value;
   if (Object.isFrozen(value)) return value;
@@ -2524,7 +2651,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.60.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2546,6 +2673,9 @@ const CONTRACT = deepFreeze({
   allowedBareImports: ALLOWED_BARE_IMPORTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
   payloadValueTypes: PAYLOAD_VALUE_TYPES,
+  chargeCurrency: CHARGE_CURRENCY,
+  currencyFormats: CURRENCY_FORMATS,
+  currencyFormatFallback: CURRENCY_FORMAT_FALLBACK,
   translationApiHosts: TRANSLATION_API_HOSTS,
 });
 
@@ -2721,6 +2851,8 @@ module.exports = {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  formatMoneyIn,
+  normaliseCurrencyCode,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/contract.js

@@ -810,6 +810,22 @@ const HOOKS = [
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-4686 — the workspace's charge currency + the only sanctioned way to
+  // render money. A widget must NOT name a currency: the owner can change it
+  // after the widget was authored, so a baked symbol goes stale over a charge
+  // that followed the change.
+  {
+    name: "useWorkspaceCurrency",
+    signature: "useWorkspaceCurrency()",
+    returnShape: {
+      currency:
+        "string  // the ISO code this workspace charges its app users in, e.g. \"SEK\"",
+      formatMoney:
+        "(minorUnits) => string  // 45000 -> \"450,00 kr\"; renders identically on web and native. NEVER write a currency symbol or code yourself",
+    },
+    requiredContextSlice: ["workspace.currency"],
+    scopes: null,
+  },
   // sc-890 — send an in-app notification to one app user in the tenant.
   // IMPERATIVE: send() never fires on mount; the widget calls it from an
   // event handler. Reads ctx.notifications.send (the injected
@@ -1457,13 +1473,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   workspace: {
     description:
-      "Workspace identity + resolved theme ({ id, slug, theme, locale }).",
+      "Workspace identity + resolved theme + charge currency ({ id, slug, theme, locale, currency }).",
     required: true,
     fields: {
       id: "string",
       slug: "string",
       theme: "ThemeTokens",
       locale: "string",
+      // sc-4686 — the ISO code this workspace charges its app users in.
+      currency: "string",
     },
   },
   navigation: {
@@ -2010,6 +2028,115 @@ const TRANSLATION_API_HOSTS = [
   "lingvanex.com",
 ];
 
+// sc-4686 — the currency a price renders in when the HOST does not supply the
+// workspace's own (a host predating the workspace.currency slice, or a caller
+// that forgot to wire it). A rendering fallback so a price is never blank or
+// "undefined" — NOT a statement about which currencies the server accepts,
+// which is per-workspace and operator-configured (sc-4649).
+const CHARGE_CURRENCY = "SEK";
+
+// sc-4686 — how each accepted currency is written, so a widget never has to.
+//
+// A widget must not name a currency: it is workspace configuration the owner
+// can change AFTER the widget was authored (see `chargeCurrency` on the
+// workspace context slice), so a baked "kr" or "€" goes stale the moment they
+// switch. Widgets render money through `useWorkspaceCurrency().formatMoney`,
+// which reads this table.
+//
+// Deliberately NOT `Intl.NumberFormat`: the exported Expo app and
+// react-native-web do not agree on its output (the same reason widgets format
+// dates with `date-fns` rather than `toLocaleDateString`), and this string ends
+// up on a price the buyer compares against the amount they are charged. An
+// explicit table renders byte-identically on both hosts.
+//
+// `symbol` is written `before` or `after` the amount; `space` inserts a
+// non-breaking gap between them. `decimals` is the minor-unit exponent, so it
+// is also how many minor units make one major unit.
+const CURRENCY_FORMATS = {
+  SEK: { symbol: "kr", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  NOK: { symbol: "kr", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  DKK: { symbol: "kr.", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  ISK: { symbol: "kr", position: "after", space: true, decimals: 0, decimalSeparator: ",", groupSeparator: "." },
+  EUR: { symbol: "€", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  GBP: { symbol: "£", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  USD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  CAD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  AUD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  NZD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  CHF: { symbol: "CHF", position: "before", space: true, decimals: 2, decimalSeparator: ".", groupSeparator: "'" },
+  PLN: { symbol: "zł", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  CZK: { symbol: "Kč", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  HUF: { symbol: "Ft", position: "after", space: true, decimals: 0, decimalSeparator: ",", groupSeparator: " " },
+  RON: { symbol: "lei", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  BGN: { symbol: "лв", position: "after", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  JPY: { symbol: "¥", position: "before", space: false, decimals: 0, decimalSeparator: ".", groupSeparator: "," },
+  INR: { symbol: "₹", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  ILS: { symbol: "₪", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  ZAR: { symbol: "R", position: "before", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: " " },
+  MXN: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  BRL: { symbol: "R$", position: "before", space: true, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  SGD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  HKD: { symbol: "$", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  AED: { symbol: "AED", position: "before", space: true, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  TRY: { symbol: "₺", position: "before", space: false, decimals: 2, decimalSeparator: ",", groupSeparator: "." },
+  THB: { symbol: "฿", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+  KRW: { symbol: "₩", position: "before", space: false, decimals: 0, decimalSeparator: ".", groupSeparator: "," },
+  CNY: { symbol: "¥", position: "before", space: false, decimals: 2, decimalSeparator: ".", groupSeparator: "," },
+};
+
+// An unlisted currency still has to render something a buyer can read, so the
+// ISO code stands in for a symbol rather than the amount appearing bare.
+const CURRENCY_FORMAT_FALLBACK = Object.freeze({
+  position: "after",
+  space: true,
+  decimals: 2,
+  decimalSeparator: ".",
+  groupSeparator: ",",
+});
+
+// sc-4686 — the ISO code a workspace charges in, normalised. An empty value
+// means a host that predates the `workspace.currency` slice; falling back to the
+// platform default keeps a price rendering rather than printing "undefined" next
+// to an amount, which is the one place a blank is unacceptable.
+function normaliseCurrencyCode(value) {
+  const code = typeof value === "string" ? value.trim().toUpperCase() : "";
+  return code || CHARGE_CURRENCY;
+}
+
+/**
+ * `formatMoneyIn("SEK", 45000)` → `"450,00 kr"`.
+ *
+ * Takes MINOR units — the same unit `requestPayment` charges in — so there is no
+ * conversion step for a widget to get wrong. Renders from `CURRENCY_FORMATS`
+ * rather than `Intl.NumberFormat`, which does not produce identical output in
+ * the exported Expo app and react-native-web; this string sits beside the amount
+ * the buyer is actually charged, so the two hosts must agree exactly.
+ *
+ * A non-finite amount renders as zero rather than "NaN": a price whose data has
+ * not loaded should read as an amount, never as a broken string in a checkout.
+ */
+function formatMoneyIn(currency, minorUnits) {
+  const code = normaliseCurrencyCode(currency);
+  const fmt = CURRENCY_FORMATS[code] || {
+    ...CURRENCY_FORMAT_FALLBACK,
+    symbol: code,
+  };
+  const amount = Number(minorUnits);
+  const safe = Number.isFinite(amount) ? Math.round(amount) : 0;
+  const negative = safe < 0;
+  const digits = String(Math.abs(safe)).padStart(fmt.decimals + 1, "0");
+  const whole = fmt.decimals > 0 ? digits.slice(0, -fmt.decimals) : digits;
+  const cents = fmt.decimals > 0 ? digits.slice(-fmt.decimals) : "";
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, fmt.groupSeparator);
+  const body = cents ? `${grouped}${fmt.decimalSeparator}${cents}` : grouped;
+  const gap = fmt.space ? " " : "";
+  const withSymbol =
+    fmt.position === "before"
+      ? `${fmt.symbol}${gap}${body}`
+      : `${body}${gap}${fmt.symbol}`;
+  return negative ? `-${withSymbol}` : withSymbol;
+}
+
 function deepFreeze(value) {
   if (value === null || typeof value !== "object") return value;
   if (Object.isFrozen(value)) return value;
@@ -2524,7 +2651,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.60.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2546,6 +2673,9 @@ const CONTRACT = deepFreeze({
   allowedBareImports: ALLOWED_BARE_IMPORTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
   payloadValueTypes: PAYLOAD_VALUE_TYPES,
+  chargeCurrency: CHARGE_CURRENCY,
+  currencyFormats: CURRENCY_FORMATS,
+  currencyFormatFallback: CURRENCY_FORMAT_FALLBACK,
   translationApiHosts: TRANSLATION_API_HOSTS,
 });
 
@@ -2721,6 +2851,8 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  formatMoneyIn,
+  normaliseCurrencyCode,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/hooks.js

@@ -33,10 +33,15 @@ import React, {
 // `sharedTranslationKey` builds the tenant-wide predefined key
 // (`shared.<key>`); `isSharedTranslationKey` tells the hook whether a bare key
 // is one of the predefined shared keys and so should try the shared namespace.
+// sc-4686 — `formatMoneyIn` lives beside the currency table it reads, for the
+// same single-source reason: the host, the compiler-parity tests and this hook
+// must render a price identically.
 import {
   widgetTranslationKey,
   sharedTranslationKey,
   isSharedTranslationKey,
+  formatMoneyIn,
+  normaliseCurrencyCode,
 } from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
@@ -129,6 +134,34 @@ function readInput(inputs, inputName) {
     : undefined;
 }
 
+/**
+ * sc-4686 — the workspace's charge currency, and the only sanctioned way for a
+ * widget to render money.
+ *
+ * A widget must never name a currency. The owner picks what the workspace
+ * charges its app users in and can change it long AFTER the widget was authored,
+ * so a hardcoded "kr" or "€" starts lying about a charge that correctly followed
+ * the change. Reading it from the host means every existing widget survives a
+ * switch with no regeneration — the same reason `useTheme()` and `useI18n()`
+ * resolve the other two pieces of workspace configuration at render time.
+ *
+ * `formatMoney` takes MINOR units, the same unit `requestPayment` charges in.
+ *
+ * @returns {{ currency: string, formatMoney: (minorUnits: number) => string }}
+ */
+export function useWorkspaceCurrency() {
+  const ctx = useWidgetContextOrThrow("useWorkspaceCurrency");
+  const currency = ctx.workspace && ctx.workspace.currency;
+  // React.useMemo rather than a bare import — see the import block above.
+  return React.useMemo(
+    () => ({
+      currency: normaliseCurrencyCode(currency),
+      formatMoney: (minorUnits) => formatMoneyIn(currency, minorUnits),
+    }),
+    [currency],
+  );
+}
+
 /**
  * Returns the host-provided theme tokens. The host guarantees every field
  * documented in CONTRACT.themeTokens is present (defaults merged with

package/dist/index.d.ts

@@ -846,6 +846,19 @@ export interface SendNotificationApi {
  */
 export function useSendNotification(): SendNotificationApi;
 
+export interface WorkspaceCurrency {
+  /** The ISO code this workspace charges its app users in. */
+  currency: string;
+  /** MINOR units in, a display string out: 45000 -> "450,00 kr". */
+  formatMoney: (minorUnits: number) => string;
+}
+/**
+ * sc-4686 — the workspace charge currency + the only sanctioned way to render
+ * money. Never write a currency symbol or code into a widget: the owner can
+ * change it after the widget ships.
+ */
+export function useWorkspaceCurrency(): WorkspaceCurrency;
+
 export function useTheme(): ThemeTokens;
 
 /**
@@ -1766,7 +1779,13 @@ export interface LintFinding {
   line: number;
   snippet: string;
 }
-export function lintSource(source: string): {
+export interface LintOptions {
+  manifest?: { requestedScopes?: string[]; supportedPlatforms?: string[] };
+}
+export function lintSource(
+  source: string,
+  options?: LintOptions,
+): {
   ok: boolean;
   findings: LintFinding[];
 };
@@ -1837,6 +1856,10 @@ export interface AiWidgetContract {
   readonly bundleExportContract: ReadonlyArray<ContractBundleShape>;
   readonly bannedApis: ReadonlyArray<ContractBannedApi>;
   readonly allowedBareImports: ReadonlyArray<string>;
+  /** sc-4686 — the render-time fallback currency when the host supplies none. */
+  readonly chargeCurrency: string;
+  /** sc-4686 — how each currency is written; read by `formatMoney`, never Intl. */
+  readonly currencyFormats: Readonly<Record<string, Readonly<{ symbol: string; position: "before" | "after"; space: boolean; decimals: number; decimalSeparator: string; groupSeparator: string }>>>;
 }
 
 export const CONTRACT: AiWidgetContract;

package/dist/index.js

@@ -38,6 +38,7 @@ export {
   useWidgetEvent,
   useWidgetInput,
   usePayments,
+  useWorkspaceCurrency,
   useSendNotification,
   useTheme,
   useWidgetStyle,

package/dist/index.native.js

@@ -38,6 +38,7 @@ export {
   useWidgetEvent,
   useWidgetInput,
   usePayments,
+  useWorkspaceCurrency,
   useSendNotification,
   useTheme,
   useWidgetStyle,

package/dist/linter.cjs

@@ -728,6 +728,95 @@ function _jsxOpenTagEnd(source, from) {
   return source.length;
 }
 
+// sc-4649 / sc-4686 — see linter.js for the rationale comments. The two
+// files must stay in lockstep (a 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) {
+  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;
+    // 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 hardcodes currency "${match[2].toUpperCase()}". Each ` +
+        `workspace charges in its OWN currency and can change it after this ` +
+        `widget ships, so OMIT currency — the platform applies the ` +
+        `workspace's — and show prices with useWorkspaceCurrency().formatMoney.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// sc-4686 — no-hardcoded-currency-label.
+//
+// The charge is safe once `currency` is omitted, but the DISPLAY is not: a "kr"
+// in JSX or a "€" in a translation string keeps showing the old currency after
+// the owner switches, so the widget tells the buyer one currency and charges
+// another. `formatMoney` renders the symbol from the workspace's currency.
+//
+// A `warning`, not an error: this is a text heuristic over string data, and a
+// legitimate non-price use exists (a currency-converter widget's own labels).
+// It drives an AI repair turn without hard-failing a human submission.
+//
+// Only in a widget that CHARGES — a widget with no `requestPayment` is not
+// displaying a price the platform is about to take money for. And only where the
+// symbol sits on a digit or a template hole, so prose can't trip it.
+const CURRENCY_LABEL_RES = [
+  // `${` is a template hole, `{` a JSX expression — a price is written both ways.
+  /[€£¥₹₺₪]\s*(?:\d|\$?\{)/,
+  /(?:\d|\})\s*(?:kr|kr\.|zł|Kč|Ft|lei|лв)\b/,
+  /\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b\s*(?:\d|\$\{)/,
+  /(?:\d|\})\s*\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b/,
+];
+
+function _hardcodedCurrencyLabelRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  if (!code.includes(REQUEST_PAYMENT_CALL)) return [];
+  const findings = [];
+  const lines = code.split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    // The requestPayment call's own `currency:` literal is the other rule's
+    // finding — don't report the same line twice.
+    if (CURRENCY_LITERAL_RE.test(lines[i])) continue;
+    if (!CURRENCY_LABEL_RES.some((re) => re.test(lines[i]))) continue;
+    findings.push({
+      rule: "no-hardcoded-currency-label",
+      severity: "warning",
+      label:
+        `this charging widget writes a currency next to a price. The owner can ` +
+        `change the workspace's currency after it ships, leaving the label ` +
+        `wrong over a correct charge — render money with ` +
+        `useWorkspaceCurrency().formatMoney(amountInMinorUnits) instead.`,
+      line: i + 1,
+      snippet: (sourceLines[i] || "").trim().slice(0, 200),
+    });
+    // One per line is enough; a price line often matches twice.
+  }
+  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 +940,8 @@ 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));
+  findings.push(..._hardcodedCurrencyLabelRules(source));
   findings.push(..._paymentErrorHandlingRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({

package/dist/linter.js

@@ -846,6 +846,109 @@ function _jsxOpenTagEnd(source, from) {
   return source.length;
 }
 
+// sc-4649 / sc-4686 — payment-currency.
+//
+// A widget must not name a currency AT ALL. Each workspace charges its app users
+// in one currency of its own choosing, the owner can change it long after the
+// widget was authored, and the server refuses a charge in anything else — so
+// omitting `currency` is the ONLY always-correct call: the platform applies the
+// workspace's own, and an existing widget follows a switch with no rebuild.
+//
+// That makes this rule workspace-INDEPENDENT (it needs no expected value passed
+// in, unlike its first sc-4649 form) and therefore it also fires in a bare
+// `appstudio-widget lint`, before a third-party developer ever uploads.
+//
+// `error`, not a warning like `payment-error-not-branched`: a literal here either
+// disagrees with the workspace and kills every checkout, or agrees today and
+// silently starts lying the moment the owner switches. Neither is code worth an
+// opt-out directive.
+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) {
+  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;
+    // 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 hardcodes currency "${match[2].toUpperCase()}". Each ` +
+        `workspace charges in its OWN currency and can change it after this ` +
+        `widget ships, so OMIT currency — the platform applies the ` +
+        `workspace's — and show prices with useWorkspaceCurrency().formatMoney.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// sc-4686 — no-hardcoded-currency-label.
+//
+// The charge is safe once `currency` is omitted, but the DISPLAY is not: a "kr"
+// in JSX or a "€" in a translation string keeps showing the old currency after
+// the owner switches, so the widget tells the buyer one currency and charges
+// another. `formatMoney` renders the symbol from the workspace's currency.
+//
+// A `warning`, not an error: this is a text heuristic over string data, and a
+// legitimate non-price use exists (a currency-converter widget's own labels).
+// It drives an AI repair turn without hard-failing a human submission.
+//
+// Only in a widget that CHARGES — a widget with no `requestPayment` is not
+// displaying a price the platform is about to take money for. And only where the
+// symbol sits on a digit or a template hole, so prose can't trip it.
+const CURRENCY_LABEL_RES = [
+  // `${` is a template hole, `{` a JSX expression — a price is written both ways.
+  /[€£¥₹₺₪]\s*(?:\d|\$?\{)/,
+  /(?:\d|\})\s*(?:kr|kr\.|zł|Kč|Ft|lei|лв)\b/,
+  /\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b\s*(?:\d|\$\{)/,
+  /(?:\d|\})\s*\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b/,
+];
+
+function _hardcodedCurrencyLabelRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  if (!code.includes(REQUEST_PAYMENT_CALL)) return [];
+  const findings = [];
+  const lines = code.split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    // The requestPayment call's own `currency:` literal is the other rule's
+    // finding — don't report the same line twice.
+    if (CURRENCY_LITERAL_RE.test(lines[i])) continue;
+    if (!CURRENCY_LABEL_RES.some((re) => re.test(lines[i]))) continue;
+    findings.push({
+      rule: "no-hardcoded-currency-label",
+      severity: "warning",
+      label:
+        `this charging widget writes a currency next to a price. The owner can ` +
+        `change the workspace's currency after it ships, leaving the label ` +
+        `wrong over a correct charge — render money with ` +
+        `useWorkspaceCurrency().formatMoney(amountInMinorUnits) instead.`,
+      line: i + 1,
+      snippet: (sourceLines[i] || "").trim().slice(0, 200),
+    });
+    // One per line is enough; a price line often matches twice.
+  }
+  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 +1084,8 @@ 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));
+  findings.push(..._hardcodedCurrencyLabelRules(source));
   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.85.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",