@colixsystems/widget-sdk 0.285.0 → 0.287.0

package/README.md

@@ -10,7 +10,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | `ctx.directory` | `@colixsystems/directory-client` | `me()`, `users.{list,get,invite,deactivate,reactivate}`, `groups.{list,create,remove,addMember,removeMember,listMine}`, `invites.{list,revoke,resend}` |
 | `ctx.assets` | `@colixsystems/assets-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useAsset()` (single asset by id) and `useAssetsByTag()` (every asset carrying a tag) resolve |
 | `ctx.widget.assets` | — (built by the host) | the files the widget package bundles: a map of file name → absolute URL, `{}` when it bundles nothing — what `useBundledAsset()` resolves |
-| `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` |
+| `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)`, the access plans and the app subscription |
 
 **Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
 
@@ -75,6 +75,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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 })` (optional: spaceType, folderId) | `{ openPdf, opening, canOpenPdf, exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.renderPdf` + `ctx.device.pdfViewer`, `ctx.filestore.files.exportPdf` — `files.write:*`. `openPdf(html, { fileName? })` renders the HTML to a PDF server-side and OPENS it (web: PDF tab; native: print / share sheet) without saving. `exportToPdf(html, { fileName?, folderId? })` renders it and saves it as a file (`application/pdf`). Same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `useAccessPlans()` | `{ plans, loading, error, purchaseAvailable, purchase, cancel, refresh }` | `ctx.payments.{listAccessPlans,purchaseAccessPlan,cancelAccessPlan}` — `payments.charge:appUser`. Plans selling access to restricted pages; `purchase(planId)` names only the plan, the server sets price and group. `purchaseAvailable` is `false` in an iOS / Android build (digital goods need store billing): show a visible not-available state. |
+| **PAYMENTS** (`ctx.payments`) | `useAppSubscription()` | `{ subscription, loading, error, cancel, refresh }` | `ctx.payments.{getAppSubscription,cancelAppSubscription}` — `payments.charge:appUser`. The signed-in user's subscription to a paid app (`{ active, renews, access_ends_at }`); `cancel()` stops it renewing, and access runs to `access_ends_at`. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. `requestPayment` requires `kind` (`"physical"` \| `"service"` \| `"digital"`): what is sold. A `"digital"` charge is refused in an iOS or Android build (`DIGITAL_SALE_NEEDS_STORE_BILLING`). 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`. |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useRecordMutes(tableId)` | `{ isMuted, loading, error, refetch }` | `ctx.notifications.mutes` — no scope. Which records of one table the signed-in user has muted, in one request for a whole list; `isMuted(recordId)` turns false when a timed mute lapses, and a `useRecordMute` write shows at once. |
@@ -89,7 +90,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.285.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**.
+`v0.287.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.287.0 (contract 1.235.0)
+
+**`useAppSubscription()` — a paid app's subscriber cancels their own subscription.** When a workspace charges its app users a monthly price for the whole app, `useAppSubscription()` returns `{ subscription, loading, error, cancel, refresh }`, where `subscription` is `{ active, renews, access_ends_at }`: `active` says the signed-in user holds paid access now, `renews` that a subscription will charge again, and `access_ends_at` when access ends without a renewal (null while it has no end). Offer a "Cancel subscription" control whenever `renews` is true: `cancel()` stops the renewal, access continues until `access_ends_at`, and nothing is refunded. Access bought in the App Store or Google Play is cancelled in the store and reads `renews: false`. Needs the `payments.charge:appUser` scope. The injected payments client gains `getAppSubscription()` and `cancelAppSubscription()` (`@colixsystems/payments-client` 0.5.0).
+
+### What's new in 0.286.0 (contract 1.234.0)
+
+**Action scripts only: `previous` and `changedFields`.** `CONTRACT.actionScriptGlobals` lists the two new runner globals a `record_updated` Action script reads: the row before the edit and the columns whose value changed. Nothing changes for widget authors.
 
 ### What's new in 0.285.0 (contract 1.233.0)
 

package/dist/contract.cjs

@@ -2407,6 +2407,22 @@ const HOOKS = [
     ],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-15342 — a paid app's subscriber cancels their own subscription.
+  {
+    name: "useAppSubscription",
+    signature: "useAppSubscription()",
+    returnShape: {
+      subscription:
+        "{ active, renews, access_ends_at } | null  // the signed-in user's subscription to the app itself (a paid app): active = they hold paid access now; renews = a subscription will charge again (false once cancelled, or when bought in the App Store / Google Play); access_ends_at = when access ends without a renewal (null while it has no end, or when not held)",
+      loading: "boolean",
+      error: "PaymentError | null",
+      cancel:
+        "() => Promise<{ active, renews: false, access_ends_at }>  // stop it renewing; access runs to access_ends_at, nothing is refunded — offer it whenever renews is true",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: ["payments.getAppSubscription", "payments.cancelAppSubscription"],
+    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
@@ -3945,6 +3961,9 @@ const ACTION_SCRIPT_GLOBALS = [
   "directory",
   "console",
   "record",
+  // sc-15609 — on record_updated, the row before the edit and what changed.
+  "previous",
+  "changedFields",
   // sc-5366 — `{ body }` on a run fired by the inbound `http_post` trigger,
   // null on every other trigger.
   "request",
@@ -4452,7 +4471,7 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment>, listAccessPlans() -> Promise<{ data, meta }>, purchaseAccessPlan({ plan_id, return_path? }) -> Promise<{ plan_id, status }>, cancelAccessPlan(planId) -> Promise<{ plan_id, renews, access_ends_at }> }; wire is snake_case (amount_cents, return_path). Backs usePayments() and useAccessPlans(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
+      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment>, listAccessPlans() -> Promise<{ data, meta }>, purchaseAccessPlan({ plan_id, return_path? }) -> Promise<{ plan_id, status }>, cancelAccessPlan(planId) -> Promise<{ plan_id, renews, access_ends_at }>, getAppSubscription() -> Promise<{ active, renews, access_ends_at }>, cancelAppSubscription() -> Promise<{ active, renews, access_ends_at }> }; wire is snake_case (amount_cents, return_path). Backs usePayments(), useAccessPlans() and useAppSubscription(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
     required: true,
     fields: {
       requestPayment: "function",
@@ -4460,6 +4479,8 @@ const WIDGET_CONTEXT_SHAPE = {
       listAccessPlans: "function",
       purchaseAccessPlan: "function",
       cancelAccessPlan: "function",
+      getAppSubscription: "function",
+      cancelAppSubscription: "function",
     },
   },
   // sc-890 — backs useSendNotification().
@@ -6719,7 +6740,12 @@ const CONTRACT = deepFreeze({
   //    "Rows per page" property.
   // 1.233.0: additive (sc-8115) — a `datastoreTemplate` table may declare
   //    `deleteWhenLastMemberLeaves: true`.
-  version: "1.233.0",
+  // 1.234.0: additive (sc-15609) — ACTION_SCRIPT_GLOBALS gains `previous` and
+  //    `changedFields`; no widget hook, primitive or manifest field changed.
+  // 1.235.0: additive (sc-15342) — `useAppSubscription()`, and the payments
+  //    slice gains `getAppSubscription` / `cancelAppSubscription`: a paid
+  //    app's subscriber cancels their own subscription.
+  version: "1.235.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2403,6 +2403,22 @@ const HOOKS = [
     ],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-15342 — a paid app's subscriber cancels their own subscription.
+  {
+    name: "useAppSubscription",
+    signature: "useAppSubscription()",
+    returnShape: {
+      subscription:
+        "{ active, renews, access_ends_at } | null  // the signed-in user's subscription to the app itself (a paid app): active = they hold paid access now; renews = a subscription will charge again (false once cancelled, or when bought in the App Store / Google Play); access_ends_at = when access ends without a renewal (null while it has no end, or when not held)",
+      loading: "boolean",
+      error: "PaymentError | null",
+      cancel:
+        "() => Promise<{ active, renews: false, access_ends_at }>  // stop it renewing; access runs to access_ends_at, nothing is refunded — offer it whenever renews is true",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: ["payments.getAppSubscription", "payments.cancelAppSubscription"],
+    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
@@ -3941,6 +3957,9 @@ const ACTION_SCRIPT_GLOBALS = [
   "directory",
   "console",
   "record",
+  // sc-15609 — on record_updated, the row before the edit and what changed.
+  "previous",
+  "changedFields",
   // sc-5366 — `{ body }` on a run fired by the inbound `http_post` trigger,
   // null on every other trigger.
   "request",
@@ -4448,7 +4467,7 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment>, listAccessPlans() -> Promise<{ data, meta }>, purchaseAccessPlan({ plan_id, return_path? }) -> Promise<{ plan_id, status }>, cancelAccessPlan(planId) -> Promise<{ plan_id, renews, access_ends_at }> }; wire is snake_case (amount_cents, return_path). Backs usePayments() and useAccessPlans(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
+      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment>, listAccessPlans() -> Promise<{ data, meta }>, purchaseAccessPlan({ plan_id, return_path? }) -> Promise<{ plan_id, status }>, cancelAccessPlan(planId) -> Promise<{ plan_id, renews, access_ends_at }>, getAppSubscription() -> Promise<{ active, renews, access_ends_at }>, cancelAppSubscription() -> Promise<{ active, renews, access_ends_at }> }; wire is snake_case (amount_cents, return_path). Backs usePayments(), useAccessPlans() and useAppSubscription(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
     required: true,
     fields: {
       requestPayment: "function",
@@ -4456,6 +4475,8 @@ const WIDGET_CONTEXT_SHAPE = {
       listAccessPlans: "function",
       purchaseAccessPlan: "function",
       cancelAccessPlan: "function",
+      getAppSubscription: "function",
+      cancelAppSubscription: "function",
     },
   },
   // sc-890 — backs useSendNotification().
@@ -6715,7 +6736,12 @@ const CONTRACT = deepFreeze({
   //    "Rows per page" property.
   // 1.233.0: additive (sc-8115) — a `datastoreTemplate` table may declare
   //    `deleteWhenLastMemberLeaves: true`.
-  version: "1.233.0",
+  // 1.234.0: additive (sc-15609) — ACTION_SCRIPT_GLOBALS gains `previous` and
+  //    `changedFields`; no widget hook, primitive or manifest field changed.
+  // 1.235.0: additive (sc-15342) — `useAppSubscription()`, and the payments
+  //    slice gains `getAppSubscription` / `cancelAppSubscription`: a paid
+  //    app's subscriber cancels their own subscription.
+  version: "1.235.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -7104,91 +7104,131 @@ export function usePayments() {
  * when `retryable` is false. Requires the `payments.charge:appUser` scope.
  */
 export function useAccessPlans() {
-  const ctx = useWidgetContextOrThrow("useAccessPlans");
+  const { state, refresh, call } = usePaymentsResource(
+    "useAccessPlans",
+    "listAccessPlans",
+    "Plans are only available for an installed widget running in the app.",
+    _accessPlansState,
+  );
+
+  const purchase = useCallback(
+    async (planId, opts) => {
+      const res = await call("purchaseAccessPlan", {
+        plan_id: planId,
+        return_path: opts && opts.return_path,
+      });
+      if (res && res.status === "ACTIVE") await refresh();
+      return res;
+    },
+    [call, refresh],
+  );
+
+  const cancel = useCallback(
+    async (planId) => {
+      const res = await call("cancelAccessPlan", planId);
+      await refresh();
+      return res;
+    },
+    [call, refresh],
+  );
+
+  return { ...state, purchase, cancel, refresh };
+}
+
+function _accessPlansState(res) {
+  return {
+    plans: Array.isArray(res && res.data) ? res.data : [],
+    purchaseAvailable: Boolean(res && res.meta && res.meta.purchase_available),
+  };
+}
+
+/**
+ * sc-15342 — the signed-in app user's own subscription to the app itself (a
+ * paid app), and the control to stop it renewing.
+ *
+ *   subscription → { active, renews, access_ends_at }. `active`: they hold paid
+ *     access to the app now; `renews`: a subscription will charge again;
+ *     `access_ends_at`: when access ends without a renewal (null while it has
+ *     no end, or when not held).
+ *   cancel() → Promise<{ active, renews: false, access_ends_at }> — stop the
+ *     subscription renewing. Access continues until `access_ends_at`, then
+ *     ends; nothing is refunded. Offer it whenever `renews` is true. Access
+ *     bought in the App Store or Google Play is cancelled in the store, so it
+ *     reads `renews: false` here.
+ *   refresh() → re-read the subscription.
+ *
+ * `error` and `cancel` rejections are a `PaymentError` — show its `message`
+ * when `retryable` is false. Requires the `payments.charge:appUser` scope.
+ */
+export function useAppSubscription() {
+  const { state, setState, refresh, call } = usePaymentsResource(
+    "useAppSubscription",
+    "getAppSubscription",
+    "The subscription is only available for an installed widget running in the app.",
+    _appSubscriptionState,
+  );
+
+  const cancel = useCallback(async () => {
+    const res = await call("cancelAppSubscription");
+    setState({ ..._appSubscriptionState(res), loading: false, error: null });
+    return res;
+  }, [call, setState]);
+
+  return { ...state, cancel, refresh };
+}
+
+function _appSubscriptionState(subscription) {
+  return { subscription };
+}
+
+/**
+ * The payments read hooks' shared core: `readMethod` loads the state on mount
+ * and on `refresh()`, `toState` maps its result, and `call(method, ...args)`
+ * invokes a payments method with its rejection as a `PaymentError`.
+ */
+function usePaymentsResource(hookName, readMethod, unavailableMessage, toState) {
+  const ctx = useWidgetContextOrThrow(hookName);
   const paymentsRef = useRef(ctx.payments);
   paymentsRef.current = ctx.payments;
-  const supported = Boolean(
-    ctx.payments && typeof ctx.payments.listAccessPlans === "function",
-  );
+  const supported = Boolean(ctx.payments && typeof ctx.payments[readMethod] === "function");
   const [state, setState] = useState(() => ({
-    plans: [],
+    ...toState(null),
     loading: supported,
-    error: supported
-      ? null
-      : new PaymentError(
-          "PAYMENTS_UNAVAILABLE",
-          "Plans are only available for an installed widget running in the app.",
-        ),
-    purchaseAvailable: false,
+    error: supported ? null : new PaymentError("PAYMENTS_UNAVAILABLE", unavailableMessage),
   }));
 
   const refresh = useCallback(async () => {
     const payments = paymentsRef.current;
-    if (!payments || typeof payments.listAccessPlans !== "function") return;
+    if (!payments || typeof payments[readMethod] !== "function") return;
     setState((prev) => ({ ...prev, loading: true }));
     try {
-      const res = await payments.listAccessPlans();
-      setState({
-        plans: Array.isArray(res && res.data) ? res.data : [],
-        loading: false,
-        error: null,
-        purchaseAvailable: Boolean(res && res.meta && res.meta.purchase_available),
-      });
+      const res = await payments[readMethod]();
+      setState({ ...toState(res), loading: false, error: null });
     } catch (err) {
       setState((prev) => ({ ...prev, loading: false, error: toPaymentError(err) }));
     }
-  }, []);
+  }, [readMethod, toState]);
 
   useEffect(() => {
     if (supported) refresh();
   }, [supported, refresh]);
 
-  const purchase = useCallback(
-    async (planId, opts) => {
-      const payments = paymentsRef.current;
-      if (!payments || typeof payments.purchaseAccessPlan !== "function") {
-        throw new PaymentError(
-          "PAYMENTS_UNAVAILABLE",
-          "Plans are only available for an installed widget running in the app.",
-        );
-      }
-      let res;
-      try {
-        res = await payments.purchaseAccessPlan({
-          plan_id: planId,
-          return_path: opts && opts.return_path,
-        });
-      } catch (err) {
-        throw toPaymentError(err);
-      }
-      if (res && res.status === "ACTIVE") await refresh();
-      return res;
-    },
-    [refresh],
-  );
-
-  const cancel = useCallback(
-    async (planId) => {
+  const call = useCallback(
+    async (method, ...args) => {
       const payments = paymentsRef.current;
-      if (!payments || typeof payments.cancelAccessPlan !== "function") {
-        throw new PaymentError(
-          "PAYMENTS_UNAVAILABLE",
-          "Plans are only available for an installed widget running in the app.",
-        );
+      if (!payments || typeof payments[method] !== "function") {
+        throw new PaymentError("PAYMENTS_UNAVAILABLE", unavailableMessage);
       }
-      let res;
       try {
-        res = await payments.cancelAccessPlan(planId);
+        return await payments[method](...args);
       } catch (err) {
         throw toPaymentError(err);
       }
-      await refresh();
-      return res;
     },
-    [refresh],
+    [unavailableMessage],
   );
 
-  return { ...state, purchase, cancel, refresh };
+  return { state, setState, refresh, call };
 }
 
 /* ============================================================================

package/dist/index.d.ts

@@ -713,6 +713,8 @@ export interface PaymentsClient {
   cancelAccessPlan(
     planId: string,
   ): Promise<{ plan_id: string; renews: false; access_ends_at: string | null }>;
+  getAppSubscription(): Promise<AppSubscription>;
+  cancelAppSubscription(): Promise<AppSubscription>;
 }
 
 /**
@@ -1610,6 +1612,31 @@ export interface AccessPlansApi {
  */
 export function useAccessPlans(): AccessPlansApi;
 
+/** The signed-in app user's own subscription to the app itself (a paid app). */
+export interface AppSubscription {
+  /** They hold paid access to the app now. */
+  active: boolean;
+  /** A subscription will charge again; false once cancelled, or bought in a store. */
+  renews: boolean;
+  /** ISO time access ends without a renewal; null while it has no end, or when not held. */
+  access_ends_at: string | null;
+}
+
+export interface AppSubscriptionApi {
+  subscription: AppSubscription | null;
+  loading: boolean;
+  error: PaymentError | null;
+  /** Stop it renewing; access runs to `access_ends_at`, nothing is refunded. */
+  cancel(): Promise<AppSubscription>;
+  refresh(): Promise<void>;
+}
+
+/**
+ * The signed-in app user's subscription to a paid app, and the control to
+ * cancel it themselves. Requires the `payments.charge:appUser` scope.
+ */
+export function useAppSubscription(): AppSubscriptionApi;
+
 /**
  * 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

package/dist/index.js

@@ -68,6 +68,7 @@ export {
   useWidgetInput,
   usePayments,
   useAccessPlans,
+  useAppSubscription,
   useWorkspaceCurrency,
   useSendNotification,
   useRecordMute,

package/dist/index.native.js

@@ -68,6 +68,7 @@ export {
   useWidgetInput,
   usePayments,
   useAccessPlans,
+  useAppSubscription,
   useWorkspaceCurrency,
   useSendNotification,
   useRecordMute,

package/dist/navigation.cjs

@@ -3,6 +3,7 @@
 "use strict";
 
 const { CONTRACT, isHexColor, contrastRatio, mixHex, readableTextColor } = require("./contract.cjs");
+const { isPlainObject } = require("./plain-object.cjs");
 
 // REQ-NAV-STRUCTURE — the host side of an app's navigation SHAPE and the
 // tokens its footer strip is painted with.
@@ -27,10 +28,6 @@ const { CONTRACT, isHexColor, contrastRatio, mixHex, readableTextColor } = requi
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
 
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 /**
  * Resolve a `theme_config.navigation` block to the shape both hosts read.
  *

package/dist/navigation.js

@@ -17,15 +17,12 @@
 // diverge.
 
 import { CONTRACT, isHexColor, contrastRatio, mixHex, readableTextColor } from "./contract.js";
+import { isPlainObject } from "./plain-object.js";
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
 
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 /**
  * Resolve a `theme_config.navigation` block to the shape both hosts read.
  *

package/dist/plain-object.cjs

@@ -0,0 +1,11 @@
+// GENERATED from plain-object.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change plain-object.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
+
+/** Any non-null, non-array object — a Date, Map or class instance passes. */
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+module.exports = {
+  isPlainObject,
+};

package/dist/plain-object.js

@@ -0,0 +1,4 @@
+/** Any non-null, non-array object — a Date, Map or class instance passes. */
+export function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/property-schema.js

@@ -3,6 +3,7 @@
 
 import { CORNER_RADIUS_KEYS } from "./corner-radius.js";
 import { SPACING_KEYS } from "./spacing.js";
+import { isPlainObject } from "./plain-object.js";
 
 const VALID_TYPES = new Set([
   "string", "number", "boolean",
@@ -85,10 +86,6 @@ const VALID_TYPES = new Set([
 /** The propertySchema field types, for documentation generated from this list. */
 export const PROPERTY_TYPES = Object.freeze([...VALID_TYPES]);
 
-function isPlainObject(v) {
-  return v !== null && typeof v === "object" && !Array.isArray(v);
-}
-
 function validateDef(def, path, errors) {
   if (!isPlainObject(def)) {
     errors.push(`${path}: must be an object`);

package/dist/signing-state.js

@@ -2,6 +2,8 @@
 // a sign order's state, what a refusal says, and how an overview is indexed.
 // Kept apart from hooks.js so it runs under plain `node --test`.
 
+import { isPlainObject } from "./plain-object.js";
+
 /** The server reads at most this many file ids per overview call. */
 export const OVERVIEW_IDS_PER_CALL = 200;
 
@@ -83,12 +85,11 @@ export function readRefusalDetail(err) {
 }
 
 const nonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
-const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 
 /** One prepare entry as the filestore client takes it, or null when it is neither form. */
 function signerForPrepare(signer) {
   if (nonEmptyString(signer)) return signer;
-  if (!isObject(signer)) return null;
+  if (!isPlainObject(signer)) return null;
   const keys = Object.keys(signer).sort().join(",");
   if (keys === "app_user_id" && nonEmptyString(signer.app_user_id)) return signer.app_user_id;
   if (keys === "email,name" && nonEmptyString(signer.name) && nonEmptyString(signer.email)) {
@@ -111,7 +112,7 @@ export function signerListForPrepare(signers) {
 
 /** The body of a new link: a corrected `email` when one is given, otherwise nothing. */
 export function resendLinkOptions(options) {
-  const email = isObject(options) && typeof options.email === "string" ? options.email.trim() : "";
+  const email = isPlainObject(options) && typeof options.email === "string" ? options.email.trim() : "";
   return email ? { email } : {};
 }
 

package/dist/theme-appearance.cjs

@@ -3,6 +3,7 @@
 "use strict";
 
 const { isHexColor, APPEARANCE_PREFERENCES } = require("./contract.cjs");
+const { isPlainObject } = require("./plain-object.cjs");
 
 // APPEARANCE_PREFERENCES: what an app opens on and a user may choose.
 
@@ -21,10 +22,6 @@ const APPEARANCE_THEME_KEYS = ["dark", "appearance"];
 /** The two palettes an app can render. */
 const APPEARANCE_MODES = Object.freeze(["light", "dark"]);
 
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 // A gradient is one colour value: its angle and type travel with its stops.
 function isGradient(value) {
   return isPlainObject(value) && isHexColor(value.from) && isHexColor(value.to);

package/dist/theme-appearance.js

@@ -1,5 +1,6 @@
 // APPEARANCE_PREFERENCES: what an app opens on and a user may choose.
 import { isHexColor, APPEARANCE_PREFERENCES } from "./contract.js";
+import { isPlainObject } from "./plain-object.js";
 
 export { APPEARANCE_PREFERENCES };
 
@@ -17,10 +18,6 @@ const APPEARANCE_THEME_KEYS = ["dark", "appearance"];
 /** The two palettes an app can render. */
 export const APPEARANCE_MODES = Object.freeze(["light", "dark"]);
 
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 // A gradient is one colour value: its angle and type travel with its stops.
 function isGradient(value) {
   return isPlainObject(value) && isHexColor(value.from) && isHexColor(value.to);

package/dist/theme-components.cjs

@@ -3,6 +3,7 @@
 "use strict";
 
 const { CONTRACT, normaliseComponentGradient } = require("./contract.cjs");
+const { isPlainObject } = require("./plain-object.cjs");
 
 // REQ-THEME-15 (sc-1497) — the host side of per-component style tokens.
 //
@@ -26,10 +27,6 @@ const { CONTRACT, normaliseComponentGradient } = require("./contract.cjs");
 // must never drop a colour the runner already accepted.
 const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
 
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 function coerceToken(def, value) {
   if (def.type === "color") {
     if (typeof value !== "string") return undefined;

package/dist/theme-components.js

@@ -16,15 +16,12 @@
 // literal, so what a planner may emit and what a host applies cannot diverge.
 
 import { CONTRACT, normaliseComponentGradient } from "./contract.js";
+import { isPlainObject } from "./plain-object.js";
 
 // 3-, 6- and 8-digit hex, matching what the build runner persists — the host
 // must never drop a colour the runner already accepted.
 const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
 
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 function coerceToken(def, value) {
   if (def.type === "color") {
     if (typeof value !== "string") return undefined;

package/dist/theme-token-refs.js

@@ -23,6 +23,7 @@ import {
   withHexAlpha,
   THEME_TOKEN_REF_PREFIX,
 } from "./contract.js";
+import { isPlainObject } from "./plain-object.js";
 
 // A value is a binding, not a colour, when it carries this prefix. No CSS
 // colour can begin with it, so a stored literal can never be misread as one.
@@ -67,10 +68,6 @@ export function resolveThemeTokenRef(value, theme) {
   return ref.alpha === null ? resolved : withHexAlpha(resolved, ref.alpha);
 }
 
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 // The same guard the neighbouring style validators apply: these props are
 // author-stored JSON, and assigning such a key while rebuilding an object would
 // silently reseat its prototype instead of carrying the value.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.285.0",
+  "version": "0.287.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -2403,6 +2403,22 @@ const HOOKS = [
     ],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-15342 — a paid app's subscriber cancels their own subscription.
+  {
+    name: "useAppSubscription",
+    signature: "useAppSubscription()",
+    returnShape: {
+      subscription:
+        "{ active, renews, access_ends_at } | null  // the signed-in user's subscription to the app itself (a paid app): active = they hold paid access now; renews = a subscription will charge again (false once cancelled, or when bought in the App Store / Google Play); access_ends_at = when access ends without a renewal (null while it has no end, or when not held)",
+      loading: "boolean",
+      error: "PaymentError | null",
+      cancel:
+        "() => Promise<{ active, renews: false, access_ends_at }>  // stop it renewing; access runs to access_ends_at, nothing is refunded — offer it whenever renews is true",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: ["payments.getAppSubscription", "payments.cancelAppSubscription"],
+    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
@@ -3941,6 +3957,9 @@ const ACTION_SCRIPT_GLOBALS = [
   "directory",
   "console",
   "record",
+  // sc-15609 — on record_updated, the row before the edit and what changed.
+  "previous",
+  "changedFields",
   // sc-5366 — `{ body }` on a run fired by the inbound `http_post` trigger,
   // null on every other trigger.
   "request",
@@ -4448,7 +4467,7 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment>, listAccessPlans() -> Promise<{ data, meta }>, purchaseAccessPlan({ plan_id, return_path? }) -> Promise<{ plan_id, status }>, cancelAccessPlan(planId) -> Promise<{ plan_id, renews, access_ends_at }> }; wire is snake_case (amount_cents, return_path). Backs usePayments() and useAccessPlans(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
+      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment>, listAccessPlans() -> Promise<{ data, meta }>, purchaseAccessPlan({ plan_id, return_path? }) -> Promise<{ plan_id, status }>, cancelAccessPlan(planId) -> Promise<{ plan_id, renews, access_ends_at }>, getAppSubscription() -> Promise<{ active, renews, access_ends_at }>, cancelAppSubscription() -> Promise<{ active, renews, access_ends_at }> }; wire is snake_case (amount_cents, return_path). Backs usePayments(), useAccessPlans() and useAppSubscription(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
     required: true,
     fields: {
       requestPayment: "function",
@@ -4456,6 +4475,8 @@ const WIDGET_CONTEXT_SHAPE = {
       listAccessPlans: "function",
       purchaseAccessPlan: "function",
       cancelAccessPlan: "function",
+      getAppSubscription: "function",
+      cancelAppSubscription: "function",
     },
   },
   // sc-890 — backs useSendNotification().
@@ -6715,7 +6736,12 @@ const CONTRACT = deepFreeze({
   //    "Rows per page" property.
   // 1.233.0: additive (sc-8115) — a `datastoreTemplate` table may declare
   //    `deleteWhenLastMemberLeaves: true`.
-  version: "1.233.0",
+  // 1.234.0: additive (sc-15609) — ACTION_SCRIPT_GLOBALS gains `previous` and
+  //    `changedFields`; no widget hook, primitive or manifest field changed.
+  // 1.235.0: additive (sc-15342) — `useAppSubscription()`, and the payments
+  //    slice gains `getAppSubscription` / `cancelAppSubscription`: a paid
+  //    app's subscriber cancels their own subscription.
+  version: "1.235.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,