@colixsystems/widget-sdk 0.61.0 → 0.62.0

package/README.md

@@ -53,7 +53,15 @@ 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.62.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.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 +402,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"],
@@ -1119,7 +1119,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" },
   },

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"],
@@ -1119,7 +1119,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" },
   },

package/dist/hooks.js

@@ -2813,20 +2813,26 @@ 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`.
+ * `{ 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> — poll the terminal status.
  *
- * 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.
+ * Because the web redirect reloads the app on return, confirm completion
+ * from server-authoritative state (the Mollie webhook flips the charge /
+ * your datastore record) — re-read your bound record on mount, or poll
+ * `getPayment(id)` after the mock/native flow resolves. 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.
  */
 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.62.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",