@colixsystems/widget-sdk 0.278.0 → 0.281.0

package/README.md

@@ -73,7 +73,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, q?, app_user_id?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| not_sent \| open \| all` (endpoint default `all`; `open` = `pending`, `not_sent` or `expired`); `q` matches the invite's name or email, `app_user_id` returns the invites reserving that user id. `resend(inviteId)` sends the invitation — the first send of a `not_sent` one included. |
 | **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`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
+| **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`) | `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. |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useRecordMute(tableId, recordId)` | `{ muted, mutedUntil, loading, error, mute, unmute, refetch }` | `ctx.notifications.mutes` — no scope. Mutes one record's notifications for the signed-in user, `mute(until)` with an ISO time, a `Date`, or `null` for until unmuted. Needs read access to the record (`RECORD_NOT_FOUND` otherwise). |
@@ -87,7 +88,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.278.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.281.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.281.0 (contract 1.230.0)
+
+**Paid page access in the store builds.** A workspace can sell a `useAccessPlans()` plan in its iOS and Android apps by naming a RevenueCat entitlement for it. In those builds `purchase(planId)` then opens the store's own in-app purchase sheet, and access arrives when RevenueCat confirms the purchase — call `refresh()` a moment later. Each plan now carries `purchase_available`; `purchaseAvailable` is `false` only when no plan can be bought here, so check the plan's own flag before showing its button. A plan or paid-app access bought on the web also grants its RevenueCat entitlement, so `usePurchases().entitlements` in the app includes it. `usePurchases()` itself stays native-only. The payments client's `purchaseAccessPlan()` may answer with `store_product_id` (`@colixsystems/payments-client` 0.4.0).
+
+### What's new in 0.280.0 (contract 1.229.0)
+
+**`useAccessPlans()` — paid access to restricted pages.** A workspace can sell plans (one-time or monthly) that add the buyer to a group the maker restricted pages to. `useAccessPlans()` returns `{ plans, loading, error, purchaseAvailable, purchase, cancel, refresh }`; each plan is `{ id, name, price_cents, currency, billing, owned, renews, access_ends_at }`. `cancel(planId)` stops a held monthly plan renewing; access continues until `access_ends_at`. `purchase(planId)` sends only the plan id: the server sets the price and the group, so a widget can never name an amount. The host opens hosted Checkout as it does for `usePayments()`, and access arrives when the payment is confirmed — call `refresh()` after the user returns. Page access is a digital good, so `purchaseAvailable` is `false` in an iOS or Android build; render a visible "not available in this app" state there. Needs the `payments.charge:appUser` scope. The injected payments client gains `listAccessPlans()`, `purchaseAccessPlan()` and `cancelAccessPlan()` (`@colixsystems/payments-client` 0.3.0).
+
+### What's new in 0.279.0 (contract 1.228.0)
+
+**`requestPayment` says what it sells.** `usePayments().requestPayment` now takes a required `kind`: `"physical"` for goods shipped or handed over, `"service"` for a real-world service such as a booking or a ticket, and `"digital"` for content or features used inside the app. The server refuses a charge without one (`CHARGE_KIND_REQUIRED`) and a kind the workspace has not been opened for (`CHARGE_KIND_NOT_ENABLED`). App stores require their own billing for digital goods, so a `"digital"` charge from an iOS or Android build is refused with `DIGITAL_SALE_NEEDS_STORE_BILLING`. All three are non-retryable `PaymentError` codes that carry a message to show. This is a breaking change for a widget that charges without `kind`, so it ships as a minor version.
 
 ### What's new in 0.278.0 (contract 1.227.0)
 

package/dist/contract.cjs

@@ -2330,13 +2330,37 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
+        "({ 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\"",
       getPayment:
         "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-15167 — paid access to restricted pages.
+  {
+    name: "useAccessPlans",
+    signature: "useAccessPlans()",
+    returnShape: {
+      plans:
+        "Array<{ id, name, price_cents, currency, billing: \"one_time\" | \"monthly\", owned, renews, access_ends_at, purchase_available }>  // owned: the user holds it; renews: a held monthly plan will charge again; access_ends_at: end of held access without a renewal (null for one-time); purchase_available: this plan can be bought here — false in an iOS/Android build for a plan the workspace does not sell in-app",
+      loading: "boolean",
+      error: "PaymentError | null",
+      purchaseAvailable:
+        "boolean  // false when no plan can be bought here (an iOS/Android build where the workspace sells no plan in-app) — render a visible not-available state, never a dead button or a blank; check each plan's purchase_available too",
+      purchase:
+        "(planId, { return_path? }?) => Promise<{ plan_id, status: \"ACTIVE\" | \"PENDING\" }>  // pass ONLY the plan id; the server sets price and group; the host opens hosted Checkout on the web and the store's in-app purchase sheet in an iOS/Android build; access arrives with the payment confirmation, so refresh() a moment later",
+      cancel:
+        "(planId) => Promise<{ plan_id, renews: false, access_ends_at }>  // stop a renewing monthly plan; access runs to access_ends_at — offer it beside every plan with renews: true",
+      refresh: "() => Promise<void>  // re-read after returning from Checkout",
+    },
+    requiredContextSlice: [
+      "payments.listAccessPlans",
+      "payments.purchaseAccessPlan",
+      "payments.cancelAccessPlan",
+    ],
+    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
@@ -3147,7 +3171,9 @@ const HOOKS = [
       "the buyer closed the sheet, so do not show it as a failure. A purchase needs a signed-in app user. NATIVE-ONLY: a " +
       "browser has no App Store or Google Play billing, so the web Player (and the Studio canvas) report supported:false " +
       "— ALWAYS render a visible 'available in the app' state there, never a blank or a dead button. The Expo export also " +
-      "reports supported:false until the workspace connects RevenueCat in Payments and rebuilds the app.",
+      "reports supported:false until the workspace connects RevenueCat in Payments and rebuilds the app. On the web, sell " +
+      "page access with useAccessPlans() instead: a web purchase of a plan (or of paid-app access) also grants its " +
+      "RevenueCat entitlement, so `entitlements` in the app includes what the user bought on the web.",
     returnShape: {
       supported: "boolean  // false on the web Player and in an app built without RevenueCat",
       loading: "boolean",
@@ -4380,9 +4406,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment> }; wire is snake_case (amount_cents, return_path). Backs usePayments(); 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 }> }; 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.",
     required: true,
-    fields: { requestPayment: "function", getPayment: "function" },
+    fields: {
+      requestPayment: "function",
+      getPayment: "function",
+      listAccessPlans: "function",
+      purchaseAccessPlan: "function",
+      cancelAccessPlan: "function",
+    },
   },
   // sc-890 — backs useSendNotification().
   notifications: {
@@ -6628,7 +6660,14 @@ const CONTRACT = deepFreeze({
   // 1.227.0: additive (sc-15163) — new native-only `usePurchases()` hook and
   //    `PurchasesError`, a `device.purchases` slice, and the vetted
   //    `react-native-purchases` import.
-  version: "1.227.0",
+  // 1.228.0: stricter (sc-15161) — `usePayments().requestPayment` requires
+  //    `kind` (physical | service | digital); three new PaymentError codes.
+  // 1.229.0: additive (sc-15167) — `useAccessPlans()`, and the payments slice
+  //    gains `listAccessPlans` / `purchaseAccessPlan` / `cancelAccessPlan`.
+  // 1.230.0: additive (sc-15164) — each access plan carries
+  //    `purchase_available`; a store build buys a plan the workspace sells
+  //    in-app through the store, and web purchases grant RevenueCat entitlements.
+  version: "1.230.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2326,13 +2326,37 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
+        "({ 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\"",
       getPayment:
         "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-15167 — paid access to restricted pages.
+  {
+    name: "useAccessPlans",
+    signature: "useAccessPlans()",
+    returnShape: {
+      plans:
+        "Array<{ id, name, price_cents, currency, billing: \"one_time\" | \"monthly\", owned, renews, access_ends_at, purchase_available }>  // owned: the user holds it; renews: a held monthly plan will charge again; access_ends_at: end of held access without a renewal (null for one-time); purchase_available: this plan can be bought here — false in an iOS/Android build for a plan the workspace does not sell in-app",
+      loading: "boolean",
+      error: "PaymentError | null",
+      purchaseAvailable:
+        "boolean  // false when no plan can be bought here (an iOS/Android build where the workspace sells no plan in-app) — render a visible not-available state, never a dead button or a blank; check each plan's purchase_available too",
+      purchase:
+        "(planId, { return_path? }?) => Promise<{ plan_id, status: \"ACTIVE\" | \"PENDING\" }>  // pass ONLY the plan id; the server sets price and group; the host opens hosted Checkout on the web and the store's in-app purchase sheet in an iOS/Android build; access arrives with the payment confirmation, so refresh() a moment later",
+      cancel:
+        "(planId) => Promise<{ plan_id, renews: false, access_ends_at }>  // stop a renewing monthly plan; access runs to access_ends_at — offer it beside every plan with renews: true",
+      refresh: "() => Promise<void>  // re-read after returning from Checkout",
+    },
+    requiredContextSlice: [
+      "payments.listAccessPlans",
+      "payments.purchaseAccessPlan",
+      "payments.cancelAccessPlan",
+    ],
+    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
@@ -3143,7 +3167,9 @@ const HOOKS = [
       "the buyer closed the sheet, so do not show it as a failure. A purchase needs a signed-in app user. NATIVE-ONLY: a " +
       "browser has no App Store or Google Play billing, so the web Player (and the Studio canvas) report supported:false " +
       "— ALWAYS render a visible 'available in the app' state there, never a blank or a dead button. The Expo export also " +
-      "reports supported:false until the workspace connects RevenueCat in Payments and rebuilds the app.",
+      "reports supported:false until the workspace connects RevenueCat in Payments and rebuilds the app. On the web, sell " +
+      "page access with useAccessPlans() instead: a web purchase of a plan (or of paid-app access) also grants its " +
+      "RevenueCat entitlement, so `entitlements` in the app includes what the user bought on the web.",
     returnShape: {
       supported: "boolean  // false on the web Player and in an app built without RevenueCat",
       loading: "boolean",
@@ -4376,9 +4402,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment> }; wire is snake_case (amount_cents, return_path). Backs usePayments(); 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 }> }; 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.",
     required: true,
-    fields: { requestPayment: "function", getPayment: "function" },
+    fields: {
+      requestPayment: "function",
+      getPayment: "function",
+      listAccessPlans: "function",
+      purchaseAccessPlan: "function",
+      cancelAccessPlan: "function",
+    },
   },
   // sc-890 — backs useSendNotification().
   notifications: {
@@ -6624,7 +6656,14 @@ const CONTRACT = deepFreeze({
   // 1.227.0: additive (sc-15163) — new native-only `usePurchases()` hook and
   //    `PurchasesError`, a `device.purchases` slice, and the vetted
   //    `react-native-purchases` import.
-  version: "1.227.0",
+  // 1.228.0: stricter (sc-15161) — `usePayments().requestPayment` requires
+  //    `kind` (physical | service | digital); three new PaymentError codes.
+  // 1.229.0: additive (sc-15167) — `useAccessPlans()`, and the payments slice
+  //    gains `listAccessPlans` / `purchaseAccessPlan` / `cancelAccessPlan`.
+  // 1.230.0: additive (sc-15164) — each access plan carries
+  //    `purchase_available`; a store build buys a plan the workspace sells
+  //    in-app through the store, and web purchases grant RevenueCat entitlements.
+  version: "1.230.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -6886,7 +6886,10 @@ const NON_RETRYABLE_PAYMENT_CODES = new Set([
   "AUTH_REQUIRED",
   "AMOUNT_TOO_LARGE",
   "BUSINESS_IDENTITY_REQUIRED",
+  "CHARGE_KIND_NOT_ENABLED",
+  "CHARGE_KIND_REQUIRED",
   "CONNECT_NOT_READY",
+  "DIGITAL_SALE_NEEDS_STORE_BILLING",
   "FORBIDDEN",
   "INVALID_AMOUNT",
   "NOT_FOUND",
@@ -6912,6 +6915,11 @@ const NON_RETRYABLE_PAYMENT_CODES = new Set([
  *   - "PAYMENTS_UNAVAILABLE"       — no installed widget / no payments host
  *   - "UNSUPPORTED_CURRENCY"       — not the platform's charge currency
  *   - "INVALID_AMOUNT" / "AMOUNT_TOO_LARGE" / "VALIDATION" — bad request
+ *   - "CHARGE_KIND_REQUIRED"       — `kind` missing or not physical / service
+ *                                    / digital
+ *   - "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
  *   - "CONNECT_NOT_READY" / "PAYMENTS_DISABLED" — provider not ready
  *   - "DECLINED"                   — the charge was declined
  *   - "INTERNAL"                   — anything else
@@ -6972,8 +6980,13 @@ function toPaymentError(err) {
  * `{ requestPayment, getPayment }`. The wire is snake_case (REQ-GEN-09) —
  * pass and read snake_case keys VERBATIM.
  *
- *   requestPayment({ amount_cents, currency?, description, return_path? })
- *     → Promise<{ id, status, ... }>. When a hosted-checkout provider
+ *   requestPayment({ amount_cents, currency?, description, kind, return_path? })
+ *     → Promise<{ id, status, ... }>. `kind` is REQUIRED and says what is
+ *       sold: "physical" (goods shipped or handed over), "service" (a
+ *       real-world service: a booking, a ticket, a delivery) or "digital"
+ *       (content or features used inside the app). A digital charge is refused
+ *       in an iOS / Android build with DIGITAL_SALE_NEEDS_STORE_BILLING — show
+ *       the error's message as a visible state, never a blank render. When a hosted-checkout provider
  *       (Mollie) is active the HOST opens Checkout for you — a same-tab
  *       redirect on web, the in-app browser on native — so you do NOT open
  *       anything yourself (no `Linking.openURL`, no `checkout_url` to
@@ -7055,6 +7068,129 @@ export function usePayments() {
   return { requestPayment, getPayment };
 }
 
+/**
+ * Paid access to restricted pages (sc-15167). A workspace sells plans; buying
+ * one adds the signed-in app user to a group the maker restricted pages to, so
+ * those pages open for them. Returns
+ * `{ plans, loading, error, purchaseAvailable, purchase, cancel, refresh }`:
+ *
+ *   plans → [{ id, name, price_cents, currency, billing, owned, renews,
+ *     access_ends_at, purchase_available }] — `billing` is "one_time" or
+ *     "monthly"; `owned` is true once the user holds the plan; `renews` while
+ *     a held monthly plan will charge again; `access_ends_at` is when held
+ *     access ends without a renewal (null for one-time access);
+ *     `purchase_available` is whether this plan can be bought here.
+ *     Render the price with `useWorkspaceCurrency().formatMoney(price_cents)`.
+ *   purchaseAvailable → false where no plan can be bought here: page access is
+ *     a digital good, and an iOS / Android build sells only the plans the
+ *     workspace sells in-app (through store billing). Render a visible "not
+ *     available in this app" state for a plan whose `purchase_available` is
+ *     false — never a dead button and never a blank render.
+ *   purchase(planId, { return_path? }?) → Promise<{ plan_id, status }>. Pass
+ *     ONLY the plan id: the server sets the price and the group, so a widget can
+ *     never name an amount. The HOST takes the payment: hosted Checkout on the
+ *     web, the store's in-app purchase sheet in an iOS / Android build. `status`
+ *     is "ACTIVE" when access was granted at once (the mock provider) and
+ *     "PENDING" while payment is confirmed; access arrives with the
+ *     confirmation, never from the client.
+ *   cancel(planId) → Promise<{ plan_id, renews: false, access_ends_at }> —
+ *     stop a held monthly plan renewing (`renews` true). Access continues
+ *     until `access_ends_at`; offer it beside every renewing plan.
+ *   refresh() → re-read the plans. Call it when the user returns from Checkout
+ *     (`useRouteParams().payment === "success"`) and poll a few times, since the
+ *     confirmation may land a moment after the redirect.
+ *
+ * `error` and `purchase` rejections are a `PaymentError` — show its `message`
+ * when `retryable` is false. Requires the `payments.charge:appUser` scope.
+ */
+export function useAccessPlans() {
+  const ctx = useWidgetContextOrThrow("useAccessPlans");
+  const paymentsRef = useRef(ctx.payments);
+  paymentsRef.current = ctx.payments;
+  const supported = Boolean(
+    ctx.payments && typeof ctx.payments.listAccessPlans === "function",
+  );
+  const [state, setState] = useState(() => ({
+    plans: [],
+    loading: supported,
+    error: supported
+      ? null
+      : new PaymentError(
+          "PAYMENTS_UNAVAILABLE",
+          "Plans are only available for an installed widget running in the app.",
+        ),
+    purchaseAvailable: false,
+  }));
+
+  const refresh = useCallback(async () => {
+    const payments = paymentsRef.current;
+    if (!payments || typeof payments.listAccessPlans !== "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),
+      });
+    } catch (err) {
+      setState((prev) => ({ ...prev, loading: false, error: toPaymentError(err) }));
+    }
+  }, []);
+
+  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 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.",
+        );
+      }
+      let res;
+      try {
+        res = await payments.cancelAccessPlan(planId);
+      } catch (err) {
+        throw toPaymentError(err);
+      }
+      await refresh();
+      return res;
+    },
+    [refresh],
+  );
+
+  return { ...state, purchase, cancel, refresh };
+}
+
 /* ============================================================================
  * NOTIFICATIONS CLIENT — ctx.notifications (@colixsystems/notifications-client)
  *

package/dist/index.d.ts

@@ -697,6 +697,14 @@ export interface AssetsClient {
 export interface PaymentsClient {
   requestPayment(body: PaymentRequest): Promise<PaymentResult>;
   getPayment(paymentId: string): Promise<PaymentResult>;
+  listAccessPlans(): Promise<{
+    data: AccessPlan[];
+    meta: { total: number; limit: number; offset: number; purchase_available: boolean };
+  }>;
+  purchaseAccessPlan(body: { plan_id: string; return_path?: string }): Promise<AccessPlanPurchase>;
+  cancelAccessPlan(
+    planId: string,
+  ): Promise<{ plan_id: string; renews: false; access_ends_at: string | null }>;
 }
 
 /**
@@ -1465,6 +1473,14 @@ export interface PaymentRequest {
   amount_cents: number;
   currency?: string;
   description: string;
+  /**
+   * What the charge sells. Required. "physical": goods shipped or handed over;
+   * "service": a real-world service such as a booking or a ticket; "digital":
+   * content or features used inside the app. App stores require their own
+   * billing for digital goods, so a "digital" charge from an iOS or Android
+   * build is refused with DIGITAL_SALE_NEEDS_STORE_BILLING.
+   */
+  kind: "physical" | "service" | "digital";
   /**
    * Site-relative path to return to after Checkout (e.g. "/cart"). Defaults
    * to the current page, so the user lands back where they started.
@@ -1478,6 +1494,7 @@ export interface PaymentResult {
   amount_cents?: number;
   currency?: string;
   description?: string;
+  kind?: "physical" | "service" | "digital" | null;
 }
 
 export interface PaymentsApi {
@@ -1496,6 +1513,53 @@ export interface PaymentsApi {
  */
 export function usePayments(): PaymentsApi;
 
+/** A plan selling access to restricted pages, as the app user sees it. */
+export interface AccessPlan {
+  id: string;
+  name: string;
+  /** In the currency's minor unit. */
+  price_cents: number;
+  currency: string;
+  billing: "one_time" | "monthly";
+  /** True once the signed-in user holds the plan. */
+  owned: boolean;
+  /** A held monthly plan that will charge again; false once cancelled. */
+  renews: boolean;
+  /** ISO time held access ends without a renewal; null for one-time access. */
+  access_ends_at: string | null;
+  /** Whether this plan can be bought here (false in a store build that does not sell it in-app). */
+  purchase_available: boolean;
+}
+
+export interface AccessPlanPurchase {
+  plan_id: string;
+  /** ACTIVE: granted at once. PENDING: waiting for the payment to confirm. */
+  status: "ACTIVE" | "PENDING";
+}
+
+export interface AccessPlansApi {
+  plans: AccessPlan[];
+  loading: boolean;
+  error: PaymentError | null;
+  /**
+   * False where no plan can be bought here (an iOS / Android build sells only
+   * the plans the workspace sells in-app): render a visible not-available state.
+   */
+  purchaseAvailable: boolean;
+  /** Pass only the plan id; the server sets price and group. */
+  purchase(planId: string, opts?: { return_path?: string }): Promise<AccessPlanPurchase>;
+  /** Stop a held monthly plan renewing; access runs to `access_ends_at`. */
+  cancel(planId: string): Promise<{ plan_id: string; renews: false; access_ends_at: string | null }>;
+  refresh(): Promise<void>;
+}
+
+/**
+ * Paid access to restricted pages: list the workspace's plans and buy one.
+ * Buying adds the user to the group the maker restricted pages to, once the
+ * payment is confirmed. Requires the `payments.charge:appUser` scope.
+ */
+export function useAccessPlans(): AccessPlansApi;
+
 /**
  * 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
@@ -1514,6 +1578,9 @@ export class PaymentError extends Error {
     | "AMOUNT_TOO_LARGE"
     | "VALIDATION"
     | "CONNECT_NOT_READY"
+    | "CHARGE_KIND_REQUIRED"
+    | "CHARGE_KIND_NOT_ENABLED"
+    | "DIGITAL_SALE_NEEDS_STORE_BILLING"
     | "PAYMENTS_DISABLED"
     | "DECLINED"
     | "FORBIDDEN"

package/dist/index.js

@@ -67,6 +67,7 @@ export {
   useWidgetEvent,
   useWidgetInput,
   usePayments,
+  useAccessPlans,
   useWorkspaceCurrency,
   useSendNotification,
   useRecordMute,

package/dist/index.native.js

@@ -67,6 +67,7 @@ export {
   useWidgetEvent,
   useWidgetInput,
   usePayments,
+  useAccessPlans,
   useWorkspaceCurrency,
   useSendNotification,
   useRecordMute,

package/package.json

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

@@ -2326,13 +2326,37 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError { code, message, retryable } — render the message when retryable is false, never \"try again\"",
+        "({ 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\"",
       getPayment:
         "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
   },
+  // sc-15167 — paid access to restricted pages.
+  {
+    name: "useAccessPlans",
+    signature: "useAccessPlans()",
+    returnShape: {
+      plans:
+        "Array<{ id, name, price_cents, currency, billing: \"one_time\" | \"monthly\", owned, renews, access_ends_at, purchase_available }>  // owned: the user holds it; renews: a held monthly plan will charge again; access_ends_at: end of held access without a renewal (null for one-time); purchase_available: this plan can be bought here — false in an iOS/Android build for a plan the workspace does not sell in-app",
+      loading: "boolean",
+      error: "PaymentError | null",
+      purchaseAvailable:
+        "boolean  // false when no plan can be bought here (an iOS/Android build where the workspace sells no plan in-app) — render a visible not-available state, never a dead button or a blank; check each plan's purchase_available too",
+      purchase:
+        "(planId, { return_path? }?) => Promise<{ plan_id, status: \"ACTIVE\" | \"PENDING\" }>  // pass ONLY the plan id; the server sets price and group; the host opens hosted Checkout on the web and the store's in-app purchase sheet in an iOS/Android build; access arrives with the payment confirmation, so refresh() a moment later",
+      cancel:
+        "(planId) => Promise<{ plan_id, renews: false, access_ends_at }>  // stop a renewing monthly plan; access runs to access_ends_at — offer it beside every plan with renews: true",
+      refresh: "() => Promise<void>  // re-read after returning from Checkout",
+    },
+    requiredContextSlice: [
+      "payments.listAccessPlans",
+      "payments.purchaseAccessPlan",
+      "payments.cancelAccessPlan",
+    ],
+    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
@@ -3143,7 +3167,9 @@ const HOOKS = [
       "the buyer closed the sheet, so do not show it as a failure. A purchase needs a signed-in app user. NATIVE-ONLY: a " +
       "browser has no App Store or Google Play billing, so the web Player (and the Studio canvas) report supported:false " +
       "— ALWAYS render a visible 'available in the app' state there, never a blank or a dead button. The Expo export also " +
-      "reports supported:false until the workspace connects RevenueCat in Payments and rebuilds the app.",
+      "reports supported:false until the workspace connects RevenueCat in Payments and rebuilds the app. On the web, sell " +
+      "page access with useAccessPlans() instead: a web purchase of a plan (or of paid-app access) also grants its " +
+      "RevenueCat entitlement, so `entitlements` in the app includes what the user bought on the web.",
     returnShape: {
       supported: "boolean  // false on the web Player and in an app built without RevenueCat",
       loading: "boolean",
@@ -4376,9 +4402,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment> }; wire is snake_case (amount_cents, return_path). Backs usePayments(); 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 }> }; 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.",
     required: true,
-    fields: { requestPayment: "function", getPayment: "function" },
+    fields: {
+      requestPayment: "function",
+      getPayment: "function",
+      listAccessPlans: "function",
+      purchaseAccessPlan: "function",
+      cancelAccessPlan: "function",
+    },
   },
   // sc-890 — backs useSendNotification().
   notifications: {
@@ -6624,7 +6656,14 @@ const CONTRACT = deepFreeze({
   // 1.227.0: additive (sc-15163) — new native-only `usePurchases()` hook and
   //    `PurchasesError`, a `device.purchases` slice, and the vetted
   //    `react-native-purchases` import.
-  version: "1.227.0",
+  // 1.228.0: stricter (sc-15161) — `usePayments().requestPayment` requires
+  //    `kind` (physical | service | digital); three new PaymentError codes.
+  // 1.229.0: additive (sc-15167) — `useAccessPlans()`, and the payments slice
+  //    gains `listAccessPlans` / `purchaseAccessPlan` / `cancelAccessPlan`.
+  // 1.230.0: additive (sc-15164) — each access plan carries
+  //    `purchase_available`; a store build buys a plan the workspace sells
+  //    in-app through the store, and web purchases grant RevenueCat entitlements.
+  version: "1.230.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,