@colixsystems/widget-sdk 0.61.0 → 0.63.0

package/README.md

@@ -53,7 +53,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.60.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.63.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.63.0
+
+**New optional manifest field `rendersOwnChrome` (sc-3331).** A boolean (default `false`) that declares whether your widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. Set it `true` when your widget draws its own title (from a `title`/`subtitle` prop with a real default, so the author can still retitle it in the Properties Panel), and the AppStudio app-builder will place the widget as the WHOLE section: it will NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Leave it `false`/omitted for a content-only widget whose heading the page supplies. `CONTRACT.version` → `1.42.0`. Additive — existing manifests omit it and read `false`, so no widget needs changing.
+
+### What's new in 0.62.0
+
+**`usePayments()` — the host owns the hosted-checkout redirect, and the documented contract is corrected to snake_case (sc-3290).** Two things that had drifted are now aligned with the runtime:
+
+- **The host opens Checkout; the widget never does.** When a hosted-checkout provider (Mollie) is active, `requestPayment(...)` now makes the host open Checkout itself — a **same-tab** redirect on web, the **in-app browser** on native (the identical model the paid-signup flow uses). The result no longer carries a `checkout_url`, and widgets must **not** call `Linking.openURL(...)` for payments: `react-native-web`'s `Linking.openURL` opens a `_blank`, `noopener` tab, which left the app user stranded on an orphan tab after paying. `return_path` now defaults to the current page, so the web return lands the user back where they started. Confirm completion from server-authoritative state (the Mollie webhook flips your datastore record) or by polling `getPayment(id)`.
+- **`PaymentRequest` / `PaymentResult` types are snake_case.** The TypeScript types and the `CONTRACT` return-shape strings described `amountCents` / `checkoutUrl` (plus a `metadata` field the client never forwarded), but the wire — and the runtime client — have always been snake_case. They now read `amount_cents`, `currency?`, `description`, `return_path?` in, `{ id, status, amount_cents, ... }` out. A TS widget that passed `amountCents` was silently sending `undefined`; update to `amount_cents`.
+- No `CONTRACT.version` change — the `ctx.payments` context shape (`{ requestPayment, getPayment }`) is unchanged; only its documented request/return shape and the host-owned redirect behaviour changed.
 
 ### What's new in 0.60.0
 
@@ -394,6 +406,8 @@ The "split-implementation + vetted package list" pivot.
 
 ### What's new in 0.9.0
 
+> **Superseded in 0.62.0** — the wire was always snake_case (`amount_cents`, `return_path`), never the camelCase shown below, and the HOST now opens hosted Checkout itself (the widget does not). See the 0.62.0 entry for the current contract.
+
 - **`usePayments()` — incoming app-user payments.** Returns `{ requestPayment, getPayment }`. `requestPayment({ amountCents, currency?, description, metadata?, returnPath? })` triggers a one-time charge from the signed-in app user and resolves to `{ id, status, checkoutUrl? }`: when `checkoutUrl` is present the widget opens it (web: navigate; native: `expo-web-browser`) — the user pays in the provider's **hosted checkout**; when absent (the platform's built-in **mock** provider, the default until a real provider is configured) the charge auto-confirms (`status: "PAID"`). `getPayment(id)` polls the terminal status. Backed by a new `WidgetContext.payments` slice and gated by the new `payments.charge:appUser` scope. **No card data ever touches the widget** — never collect card fields yourself. The charge settles to the workspace owner; the amount is bounded by a platform per-charge cap. Rejections are a structured `PaymentError` (also a new named export) with a stable `.code`.
 - **`CONTRACT.version` → `1.2.0`** (additive: one new hook, one new context slice, one new scope, one new error class). No existing export changed signature.
 

package/dist/contract.cjs

@@ -469,9 +469,9 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amountCents, currency?, description, metadata? }) => Promise<{ id, status, checkoutUrl? }>  // rejects with PaymentError",
+        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError",
       getPayment:
-        "(paymentId) => Promise<{ id, status, amountCents, currency, description }>",
+        "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
@@ -971,6 +971,13 @@ const MANIFEST_SCHEMA = {
       "never auto-applies style — the widget owns placement.",
     default: {},
   },
+  rendersOwnChrome: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -1119,7 +1126,7 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (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> }; 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.",
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
@@ -1908,7 +1915,11 @@ const CONTRACT = deepFreeze({
   //    no in-code `|| "fallback"`. Backed by a host-only subpath export
   //    (`@colixsystems/widget-sdk/host` -> resolveProps); the author-facing entry
   //    is unchanged. No existing behaviour changes — minor bump.
-  version: "1.41.0",
+  // 1.42.0 (sc-3331) — new OPTIONAL manifest field `rendersOwnChrome` (boolean,
+  //    default false): declares that the widget renders its own section header,
+  //    so the app-builder places it as a whole section without stacking a
+  //    heading above it. Additive — existing manifests omit it and read false.
+  version: "1.42.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -469,9 +469,9 @@ const HOOKS = [
     signature: "usePayments()",
     returnShape: {
       requestPayment:
-        "({ amountCents, currency?, description, metadata? }) => Promise<{ id, status, checkoutUrl? }>  // rejects with PaymentError",
+        "({ amount_cents, currency?, description, return_path? }) => Promise<{ id, status }>  // host opens hosted Checkout; rejects with PaymentError",
       getPayment:
-        "(paymentId) => Promise<{ id, status, amountCents, currency, description }>",
+        "(paymentId) => Promise<{ id, status, amount_cents, currency, description }>",
     },
     requiredContextSlice: ["payments.requestPayment"],
     scopes: ["payments.charge:appUser"],
@@ -971,6 +971,13 @@ const MANIFEST_SCHEMA = {
       "never auto-applies style — the widget owns placement.",
     default: {},
   },
+  rendersOwnChrome: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -1119,7 +1126,7 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (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> }; 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.",
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
@@ -1908,7 +1915,11 @@ const CONTRACT = deepFreeze({
   //    no in-code `|| "fallback"`. Backed by a host-only subpath export
   //    (`@colixsystems/widget-sdk/host` -> resolveProps); the author-facing entry
   //    is unchanged. No existing behaviour changes — minor bump.
-  version: "1.41.0",
+  // 1.42.0 (sc-3331) — new OPTIONAL manifest field `rendersOwnChrome` (boolean,
+  //    default false): declares that the widget renders its own section header,
+  //    so the app-builder places it as a whole section without stacking a
+  //    heading above it. Additive — existing manifests omit it and read false.
+  version: "1.42.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2813,20 +2813,47 @@ function toPaymentError(err) {
 
 /**
  * Incoming app-user payments (REQ-BILL-07-WIDGETPAY). Returns
- * `{ requestPayment, getPayment }`.
- *
- *   requestPayment({ amountCents, currency?, description, metadata? })
- *     → Promise<{ id, status, checkoutUrl?, ... }>. The host either
- *       auto-confirms (mock provider, `status: "PAID"`, no redirect) or
- *       returns a hosted-checkout `checkoutUrl` the widget should open
- *       (Mollie provider, `status: "PENDING"`). Rejects with a
- *       `PaymentError`.
- *   getPayment(paymentId) → Promise<payment> — poll the terminal status.
+ * `{ 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
+ *       (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
+ *       handle). The mock provider auto-confirms (`status: "PAID"`, no
+ *       redirect). Rejects with a `PaymentError`.
+ *   getPayment(paymentId) → Promise<payment> — read the current status
+ *       (`PENDING` | `PAID` | `FAILED`), scoped server-side to the caller.
+ *
+ * THE PAYER IS ALWAYS A SIGNED-IN APP USER — charging requires it, and a paid
+ * widget lives on a page behind login. So read the buyer's identity from
+ * `useUser()` (`{ id, email, displayName }`) and connect the record you write
+ * to `user.id`. Do NOT re-collect the name / email `useUser()` already gives
+ * you as required inputs; pre-filling an editable field from it, or asking for
+ * genuinely new details (phone, address, notes), is fine.
+ *
+ * CONFIRM FROM SERVER STATE, NOT MEMORY — and handle success, failure, AND
+ * cancel. On web `requestPayment` triggers a full-page redirect, so the app
+ * reloads on return and any in-memory "done" flag is gone. One pattern works on
+ * both platforms:
+ *   1. On mount, read `useRouteParams()`. After the web redirect it carries
+ *      `payment` (`"success"` | `"cancel"`) and, on success, `payment_id`.
+ *      `"cancel"` → the user backed out: show a "payment cancelled" state, do
+ *      NOT treat it as paid. `"success"` + `payment_id` → poll `getPayment(id)`
+ *      until it leaves `PENDING`, then branch: `PAID` → confirm / write the
+ *      record; `FAILED` → show a failure state.
+ *   2. Also poll the `id` that `requestPayment` RESOLVES with — the mock
+ *      provider and the native in-app-browser flow return here without a reload,
+ *      so route params are absent and this branch reconciles instead.
+ * Poll a bounded number of times (e.g. every ~1.5s for up to ~30s) because the
+ * Mollie webhook may land a moment after the redirect; if it is still `PENDING`
+ * when you give up, show a "still processing" state rather than "paid".
  *
  * Requires the `payments.charge:appUser` scope in the manifest's
- * `requestedScopes`. The charge settles to the workspace owner; the app
- * user confirms the amount in hosted Checkout. No card data touches the
- * widget — never collect card fields yourself.
+ * `requestedScopes`. The charge settles to the workspace owner; the app user
+ * confirms the amount in hosted Checkout. No card data touches the widget —
+ * never collect card fields yourself.
  */
 export function usePayments() {
   const ctx = useWidgetContextOrThrow("usePayments");

package/dist/index.d.ts

@@ -614,32 +614,27 @@ export function useDirectory(query?: DirectoryQuery): DirectoryResult;
 export function useWidgetEvent(name: string): (payload?: unknown) => void;
 
 /**
- * Arguments for `usePayments().requestPayment(...)`. `amountCents` is the
- * charge in the currency's minor unit; the app user confirms it in hosted
- * Checkout. `metadata` is an optional flat map carried through for the
- * widget's own reconciliation (never used to derive the amount).
+ * Arguments for `usePayments().requestPayment(...)`. snake_case VERBATIM —
+ * this is the wire contract (REQ-GEN-09). `amount_cents` is the charge in the
+ * currency's minor unit; the app user confirms it in hosted Checkout.
  */
 export interface PaymentRequest {
-  amountCents: number;
+  amount_cents: number;
   currency?: string;
   description: string;
-  metadata?: Record<string, string>;
-  /** Site-relative path to return to after Checkout (e.g. "/cart"). */
-  returnPath?: string;
+  /**
+   * Site-relative path to return to after Checkout (e.g. "/cart"). Defaults
+   * to the current page, so the user lands back where they started.
+   */
+  return_path?: string;
 }
 
 export interface PaymentResult {
   id: string;
   status: "PENDING" | "PAID" | "FAILED" | "REFUNDED" | "CANCELLED";
-  amountCents?: number;
+  amount_cents?: number;
   currency?: string;
   description?: string;
-  /**
-   * Present (Mollie provider) when the app user must complete a hosted
-   * checkout: the widget should open this URL. Absent under the mock
-   * provider, where the charge auto-confirms (`status: "PAID"`).
-   */
-  checkoutUrl?: string | null;
 }
 
 export interface PaymentsApi {
@@ -649,8 +644,12 @@ export interface PaymentsApi {
 
 /**
  * Incoming app-user payments (REQ-BILL-07-WIDGETPAY). Requires the
- * `payments.charge:appUser` scope in the widget manifest. The charge
- * settles to the workspace owner; no card data touches the widget.
+ * `payments.charge:appUser` scope in the widget manifest. When a hosted-
+ * checkout provider is active the HOST opens Checkout for you (a same-tab
+ * redirect on web, the in-app browser on native) — you never open a URL and
+ * never collect card data. Confirm completion from server state (the webhook
+ * flips your record) or poll `getPayment(id)`. The charge settles to the
+ * workspace owner.
  */
 export function usePayments(): PaymentsApi;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",