@colixsystems/widget-sdk 0.60.0 → 0.62.0

package/README.md

@@ -21,6 +21,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
+| **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
@@ -52,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
 
@@ -384,6 +393,7 @@ The "split-implementation + vetted package list" pivot.
 ### What's new in 0.11.0
 
 - **`useNavigation()` is wired.** Returns the host-provided navigation surface `{ goTo, goBack, push, replace, back, currentRoute }` for internal page-to-page navigation. Missing methods degrade to no-ops on the Studio canvas preview. Additive.
+- **`useRouteParams()` reads the nav params.** Returns `currentRoute.params` — the bag a `goTo(pageId, params)` carried to this page. The flat accessor for master→detail: navigate with `goTo(detailPageId, { recordId: row.id })`, then read `const { recordId } = useRouteParams()`. It is an OBJECT — read a param off it, never call it. Empty object when the page was opened without params. Additive (v0.61.0).
 - **`Linking` primitive re-exported.** `Linking.openURL(url)` opens an external URL with the OS handler — web (`react-native-web`) maps to `window.open` / `location.href`; native hands off to the system. Use this for external URLs; use `useNavigation().goTo(pageId)` for internal pages.
 
 ### What's new in 0.10.0
@@ -392,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.
 
@@ -454,7 +466,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.

package/dist/contract.cjs

@@ -150,6 +150,16 @@ const HOOKS = [
     requiredContextSlice: ["navigation"],
     scopes: null,
   },
+  {
+    name: "useRouteParams",
+    signature: "useRouteParams()",
+    returnShape: {
+      "<paramKey>":
+        "a navigation param value the previous page passed via goTo(pageId, params) — usually a string id, e.g. recordId on a detail page",
+    },
+    requiredContextSlice: ["navigation"],
+    scopes: null,
+  },
   {
     name: "useDatastoreRecord",
     signature: "useDatastoreRecord(tableId, recordId)",
@@ -459,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"],
@@ -1109,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

@@ -150,6 +150,16 @@ const HOOKS = [
     requiredContextSlice: ["navigation"],
     scopes: null,
   },
+  {
+    name: "useRouteParams",
+    signature: "useRouteParams()",
+    returnShape: {
+      "<paramKey>":
+        "a navigation param value the previous page passed via goTo(pageId, params) — usually a string id, e.g. recordId on a detail page",
+    },
+    requiredContextSlice: ["navigation"],
+    scopes: null,
+  },
   {
     name: "useDatastoreRecord",
     signature: "useDatastoreRecord(tableId, recordId)",
@@ -459,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"],
@@ -1109,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

@@ -249,6 +249,27 @@ export function useNavigation() {
   return ctx.navigation;
 }
 
+const EMPTY_PARAMS = Object.freeze({});
+
+/**
+ * Returns the current route's navigation params — the bag a `goTo(pageId, params)`
+ * carried to this page (a query string on web, react-navigation route params on
+ * native). This is the flat accessor for the master→detail pattern: a list widget
+ * navigates with `goTo(detailPageId, { recordId: row.id })`, and the detail widget
+ * reads `const { recordId } = useRouteParams()`. Returns an empty object on a page
+ * opened without params (the Studio canvas, a direct deep link), so reads are
+ * always safe. Equivalent to `useNavigation().currentRoute.params`, but without the
+ * deep chain — read a param off it, never call it.
+ */
+export function useRouteParams() {
+  const ctx = useWidgetContextOrThrow("useRouteParams");
+  const nav = ctx.navigation || {};
+  const route = nav.currentRoute || {};
+  // Stable reference on the empty path so `useEffect([params])` doesn't re-fire
+  // every render on a paramless page.
+  return route.params || EMPTY_PARAMS;
+}
+
 /**
  * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
  * the host's translation table and falls back to `fallback ?? key` when
@@ -2792,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;
 
@@ -925,6 +924,15 @@ export function useNavigation(): {
   currentRoute: { pageId: string; params: Record<string, unknown> };
 };
 
+/**
+ * Returns the current route's navigation params — the bag a `goTo(pageId, params)`
+ * carried to this page. The flat accessor for master→detail: navigate with
+ * `goTo(detailPageId, { recordId: row.id })`, then read
+ * `const { recordId } = useRouteParams()`. Empty object when the page was opened
+ * without params. Equivalent to `useNavigation().currentRoute.params`.
+ */
+export function useRouteParams(): Record<string, unknown>;
+
 /**
  * Static API for external URLs. `openURL(url)` opens a URL with the OS
  * handler (web: react-native-web maps to `window.open` / `location.href`;

package/dist/index.js

@@ -42,6 +42,7 @@ export {
   useUser,
   useFill,
   useNavigation,
+  useRouteParams,
   useChildRenderer,
   useRefresh,
   useGeolocation,

package/dist/index.native.js

@@ -42,6 +42,7 @@ export {
   useUser,
   useFill,
   useNavigation,
+  useRouteParams,
   useChildRenderer,
   useRefresh,
   useGeolocation,

package/package.json

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