@colixsystems/widget-sdk 0.286.0 → 0.288.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.286.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.288.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.288.0 (contract 1.236.0)
+
+**A payment can pay for an order, and only the payment marks it paid.** Until now a shop widget charged the buyer and then wrote "Paid" to the order itself, so a buyer who could edit their own order could mark it paid without paying. `usePayments().requestPayment` now takes an optional `order: { table_id, record_id }`: a row the buyer may edit, in a table whose payment-status column the workspace has set (a STRING or BOOL column, one per table). The server checks it before the charge starts and refuses a missing or unreachable order (`ORDER_NOT_FOUND`), a table with no payment-status column (`ORDER_NOT_PAYABLE`) and an order that is already paid (`ORDER_ALREADY_PAID`); all three are non-retryable. Only one checkout per order can be open at a time: a second one while the first is still open is refused with `ORDER_PAYMENT_IN_PROGRESS`, which is retryable and clears when that checkout ends. When the payment settles, the server writes the column (`"PAID"`, or `true` on a BOOL; `"REFUNDED"` / `false` after a full refund); a failed or cancelled payment leaves it alone. Nothing else can write that column: every client value for it is ignored on create and update, so drop any code that sets "paid" yourself. The payment returned by `requestPayment` and `getPayment` carries `order` too, so a buyer coming back from Checkout lands on the right order. A `datastoreTemplate` column may declare `paymentStatus: true` to ship the column with the widget. Additive: a charge without `order` behaves as before.
+
+### 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)
 

package/dist/contract.cjs

@@ -2376,9 +2376,9 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, kind, return_path? }) => Promise<{ id, status }>  // kind is REQUIRED: \"physical\" | \"service\" | \"digital\" — what is sold; a digital charge is refused in an iOS/Android build (DIGITAL_SALE_NEEDS_STORE_BILLING); host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
+        "({ amount_cents, currency?, description, kind, return_path?, order? }) => Promise<{ id, status, order }>  // kind is REQUIRED: \"physical\" | \"service\" | \"digital\" — what is sold; a digital charge is refused in an iOS/Android build (DIGITAL_SALE_NEEDS_STORE_BILLING); order: { table_id, record_id } — the order row this pays for, in a table with a payment-status column; the SERVER marks it paid when the payment settles, so never write \"paid\" yourself (refused: ORDER_NOT_FOUND, ORDER_NOT_PAYABLE, ORDER_ALREADY_PAID; ORDER_PAYMENT_IN_PROGRESS is retryable while another checkout for the order is open); host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
       getPayment:
-        "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
+        "(paymentId) => Promise<{ id, status, amount_cents, currency, description, order }>  // order: { table_id, record_id } | null — read it after returning from Checkout",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
@@ -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
@@ -4154,7 +4170,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). `paymentStatus: true` makes a STRING or BOOL column the table's payment status (at most one per table; not required, encrypted, immutable or defaulting to paid): a settled `requestPayment({ order: { table_id, record_id } })` for one of its rows writes it (`PAID`, or `true` on a BOOL; `REFUNDED` / `false` after a full refund), and every client value for it is ignored, so a buyer cannot mark their own order paid. A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -4455,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, order). 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",
@@ -4463,6 +4479,8 @@ const WIDGET_CONTEXT_SHAPE = {
       listAccessPlans: "function",
       purchaseAccessPlan: "function",
       cancelAccessPlan: "function",
+      getAppSubscription: "function",
+      cancelAppSubscription: "function",
     },
   },
   // sc-890 — backs useSendNotification().
@@ -6724,7 +6742,14 @@ const CONTRACT = deepFreeze({
   //    `deleteWhenLastMemberLeaves: true`.
   // 1.234.0: additive (sc-15609) — ACTION_SCRIPT_GLOBALS gains `previous` and
   //    `changedFields`; no widget hook, primitive or manifest field changed.
-  version: "1.234.0",
+  // 1.235.0: additive (sc-15342) — `useAppSubscription()`, and the payments
+  //    slice gains `getAppSubscription` / `cancelAppSubscription`: a paid
+  //    app's subscriber cancels their own subscription.
+  // 1.236.0: additive (sc-15358) — `requestPayment` takes an optional
+  //    `order: { table_id, record_id }` the server marks paid on settlement,
+  //    a template column may declare `paymentStatus: true`, and four new
+  //    PaymentError codes.
+  version: "1.236.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2372,9 +2372,9 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, kind, return_path? }) => Promise<{ id, status }>  // kind is REQUIRED: \"physical\" | \"service\" | \"digital\" — what is sold; a digital charge is refused in an iOS/Android build (DIGITAL_SALE_NEEDS_STORE_BILLING); host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
+        "({ amount_cents, currency?, description, kind, return_path?, order? }) => Promise<{ id, status, order }>  // kind is REQUIRED: \"physical\" | \"service\" | \"digital\" — what is sold; a digital charge is refused in an iOS/Android build (DIGITAL_SALE_NEEDS_STORE_BILLING); order: { table_id, record_id } — the order row this pays for, in a table with a payment-status column; the SERVER marks it paid when the payment settles, so never write \"paid\" yourself (refused: ORDER_NOT_FOUND, ORDER_NOT_PAYABLE, ORDER_ALREADY_PAID; ORDER_PAYMENT_IN_PROGRESS is retryable while another checkout for the order is open); host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
       getPayment:
-        "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
+        "(paymentId) => Promise<{ id, status, amount_cents, currency, description, order }>  // order: { table_id, record_id } | null — read it after returning from Checkout",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
@@ -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
@@ -4150,7 +4166,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). `paymentStatus: true` makes a STRING or BOOL column the table's payment status (at most one per table; not required, encrypted, immutable or defaulting to paid): a settled `requestPayment({ order: { table_id, record_id } })` for one of its rows writes it (`PAID`, or `true` on a BOOL; `REFUNDED` / `false` after a full refund), and every client value for it is ignored, so a buyer cannot mark their own order paid. A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -4451,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, order). 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",
@@ -4459,6 +4475,8 @@ const WIDGET_CONTEXT_SHAPE = {
       listAccessPlans: "function",
       purchaseAccessPlan: "function",
       cancelAccessPlan: "function",
+      getAppSubscription: "function",
+      cancelAppSubscription: "function",
     },
   },
   // sc-890 — backs useSendNotification().
@@ -6720,7 +6738,14 @@ const CONTRACT = deepFreeze({
   //    `deleteWhenLastMemberLeaves: true`.
   // 1.234.0: additive (sc-15609) — ACTION_SCRIPT_GLOBALS gains `previous` and
   //    `changedFields`; no widget hook, primitive or manifest field changed.
-  version: "1.234.0",
+  // 1.235.0: additive (sc-15342) — `useAppSubscription()`, and the payments
+  //    slice gains `getAppSubscription` / `cancelAppSubscription`: a paid
+  //    app's subscriber cancels their own subscription.
+  // 1.236.0: additive (sc-15358) — `requestPayment` takes an optional
+  //    `order: { table_id, record_id }` the server marks paid on settlement,
+  //    a template column may declare `paymentStatus: true`, and four new
+  //    PaymentError codes.
+  version: "1.236.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -6893,6 +6893,9 @@ const NON_RETRYABLE_PAYMENT_CODES = new Set([
   "FORBIDDEN",
   "INVALID_AMOUNT",
   "NOT_FOUND",
+  "ORDER_ALREADY_PAID",
+  "ORDER_NOT_FOUND",
+  "ORDER_NOT_PAYABLE",
   "PAYMENTS_DISABLED",
   "PAYMENTS_SCOPE_NOT_GRANTED",
   "PAYMENTS_UNAVAILABLE",
@@ -6920,6 +6923,10 @@ const NON_RETRYABLE_PAYMENT_CODES = new Set([
  *   - "CHARGE_KIND_NOT_ENABLED"    — this workspace cannot sell that kind yet
  *   - "DIGITAL_SALE_NEEDS_STORE_BILLING" — a digital sale from an iOS / Android
  *                                    build: store policy requires store billing
+ *   - "ORDER_NOT_FOUND" / "ORDER_NOT_PAYABLE" / "ORDER_ALREADY_PAID" — the
+ *                                    `order` is not one this user can pay for
+ *   - "ORDER_PAYMENT_IN_PROGRESS"  — another checkout for the order is open
+ *                                    (retryable: it clears when that one ends)
  *   - "CONNECT_NOT_READY" / "PAYMENTS_DISABLED" — provider not ready
  *   - "DECLINED"                   — the charge was declined
  *   - "INTERNAL"                   — anything else
@@ -7104,91 +7111,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>;
 }
 
 /**
@@ -1536,6 +1538,20 @@ export interface PaymentRequest {
    * to the current page, so the user lands back where they started.
    */
   return_path?: string;
+  /**
+   * The order this charge pays for: a row the user may edit, in a table with
+   * a payment-status column. When the payment settles the server sets that
+   * column, so never write "paid" yourself; the platform ignores it anyway.
+   * Refused with ORDER_NOT_FOUND, ORDER_NOT_PAYABLE or ORDER_ALREADY_PAID, and
+   * with the retryable ORDER_PAYMENT_IN_PROGRESS while another checkout is open.
+   */
+  order?: PaymentOrder;
+}
+
+/** A row of a table with a payment-status column, by the ids a widget holds. */
+export interface PaymentOrder {
+  table_id: string;
+  record_id: string;
 }
 
 export interface PaymentResult {
@@ -1545,6 +1561,8 @@ export interface PaymentResult {
   currency?: string;
   description?: string;
   kind?: "physical" | "service" | "digital" | null;
+  /** The order the charge pays for, or null. Read it after returning from Checkout. */
+  order?: PaymentOrder | null;
 }
 
 export interface PaymentsApi {
@@ -1610,6 +1628,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
@@ -1631,6 +1674,10 @@ export class PaymentError extends Error {
     | "CHARGE_KIND_REQUIRED"
     | "CHARGE_KIND_NOT_ENABLED"
     | "DIGITAL_SALE_NEEDS_STORE_BILLING"
+    | "ORDER_NOT_FOUND"
+    | "ORDER_NOT_PAYABLE"
+    | "ORDER_ALREADY_PAID"
+    | "ORDER_PAYMENT_IN_PROGRESS"
     | "PAYMENTS_DISABLED"
     | "DECLINED"
     | "FORBIDDEN"

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/package.json

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

@@ -2372,9 +2372,9 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, kind, return_path? }) => Promise<{ id, status }>  // kind is REQUIRED: \"physical\" | \"service\" | \"digital\" — what is sold; a digital charge is refused in an iOS/Android build (DIGITAL_SALE_NEEDS_STORE_BILLING); host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
+        "({ amount_cents, currency?, description, kind, return_path?, order? }) => Promise<{ id, status, order }>  // kind is REQUIRED: \"physical\" | \"service\" | \"digital\" — what is sold; a digital charge is refused in an iOS/Android build (DIGITAL_SALE_NEEDS_STORE_BILLING); order: { table_id, record_id } — the order row this pays for, in a table with a payment-status column; the SERVER marks it paid when the payment settles, so never write \"paid\" yourself (refused: ORDER_NOT_FOUND, ORDER_NOT_PAYABLE, ORDER_ALREADY_PAID; ORDER_PAYMENT_IN_PROGRESS is retryable while another checkout for the order is open); host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
       getPayment:
-        "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
+        "(paymentId) => Promise<{ id, status, amount_cents, currency, description, order }>  // order: { table_id, record_id } | null — read it after returning from Checkout",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
@@ -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
@@ -4150,7 +4166,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). `paymentStatus: true` makes a STRING or BOOL column the table's payment status (at most one per table; not required, encrypted, immutable or defaulting to paid): a settled `requestPayment({ order: { table_id, record_id } })` for one of its rows writes it (`PAID`, or `true` on a BOOL; `REFUNDED` / `false` after a full refund), and every client value for it is ignored, so a buyer cannot mark their own order paid. A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -4451,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, order). 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",
@@ -4459,6 +4475,8 @@ const WIDGET_CONTEXT_SHAPE = {
       listAccessPlans: "function",
       purchaseAccessPlan: "function",
       cancelAccessPlan: "function",
+      getAppSubscription: "function",
+      cancelAppSubscription: "function",
     },
   },
   // sc-890 — backs useSendNotification().
@@ -6720,7 +6738,14 @@ const CONTRACT = deepFreeze({
   //    `deleteWhenLastMemberLeaves: true`.
   // 1.234.0: additive (sc-15609) — ACTION_SCRIPT_GLOBALS gains `previous` and
   //    `changedFields`; no widget hook, primitive or manifest field changed.
-  version: "1.234.0",
+  // 1.235.0: additive (sc-15342) — `useAppSubscription()`, and the payments
+  //    slice gains `getAppSubscription` / `cancelAppSubscription`: a paid
+  //    app's subscriber cancels their own subscription.
+  // 1.236.0: additive (sc-15358) — `requestPayment` takes an optional
+  //    `order: { table_id, record_id }` the server marks paid on settlement,
+  //    a template column may declare `paymentStatus: true`, and four new
+  //    PaymentError codes.
+  version: "1.236.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,