@colixsystems/widget-sdk 0.8.0 → 0.9.0

package/README.md

@@ -6,9 +6,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.8.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.9.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.8.0
+### What's new in 0.9.0
+
+- **`usePayments()` — incoming app-user payments (REQ-BILL-07-WIDGETPAY).** 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 **hosted Stripe Checkout**; when absent (the platform's built-in **mock** provider, the default until Stripe 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.
+
+### What was in 0.8.0
 
 - **`useDirectory()` — read-only user directory hook (REQ-DIR-01).** Returns `{ users, loading, error, refetch }` where each user is `{ id, name, role }`. Backed by a new `WidgetContext.directory.listUsers(query)` slice and gated by the new `directory.read:users` scope. Use it to build a chat people-list, an @-mention picker, or to resolve an author id to a display name. The host reads `GET /api/v1/app/users`, which hands non-Studio (Player) callers the reduced `{ id, name, role }` projection — email and other admin-only fields never leave the server for an app end-user. `query` is an optional `{ q, role, isActive, limit, offset }` (`q` substring-matches the display name; `role` is `"USER"` (default), `"INTEGRATION"`, or `"ALL"`). Mutating users is not part of the widget surface — the directory is read-only.
 - **`CONTRACT.version` → `1.1.0`** (additive: one new hook, one new context slice, one new scope). No existing export changed signature.
@@ -66,7 +71,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`, `useDatastoreMutation`, `useDirectory`, `useWidgetEvent`, `useTheme`, `useI18n` — hooks that read from the host-provided `WidgetContext`. `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope.
+- `useDatastoreQuery`, `useDatastoreMutation`, `useDirectory`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n` — hooks that read from the host-provided `WidgetContext`. `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet` — re-exported from `react-native`. The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. 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

@@ -97,6 +97,18 @@ const HOOKS = [
     requiredContextSlice: ["events.emit"],
     scopes: null,
   },
+  {
+    name: "usePayments",
+    signature: "usePayments()",
+    returnShape: {
+      requestPayment:
+        "({ amountCents, currency?, description, metadata? }) => Promise<{ id, status, checkoutUrl? }>  // rejects with PaymentError",
+      getPayment:
+        "(paymentId) => Promise<{ id, status, amountCents, currency, description }>",
+    },
+    requiredContextSlice: ["payments.requestPayment"],
+    scopes: ["payments.charge:appUser"],
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -335,6 +347,12 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { emit: "function" },
   },
+  payments: {
+    description:
+      "Incoming app-user payments (REQ-BILL-07-WIDGETPAY). { requestPayment({ amountCents, currency?, description, metadata? }) -> 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.",
+    required: true,
+    fields: { requestPayment: "function", getPayment: "function" },
+  },
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -427,7 +445,7 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.1.0",
+  version: "1.2.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -98,6 +98,18 @@ const HOOKS = [
     requiredContextSlice: ["events.emit"],
     scopes: null,
   },
+  {
+    name: "usePayments",
+    signature: "usePayments()",
+    returnShape: {
+      requestPayment:
+        "({ amountCents, currency?, description, metadata? }) => Promise<{ id, status, checkoutUrl? }>  // rejects with PaymentError",
+      getPayment:
+        "(paymentId) => Promise<{ id, status, amountCents, currency, description }>",
+    },
+    requiredContextSlice: ["payments.requestPayment"],
+    scopes: ["payments.charge:appUser"],
+  },
 ];
 
 // REQ-WSDK-RN-WEB: see contract.cjs for the source-of-truth comment.
@@ -329,6 +341,12 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { emit: "function" },
   },
+  payments: {
+    description:
+      "Incoming app-user payments (REQ-BILL-07-WIDGETPAY). { requestPayment({ amountCents, currency?, description, metadata? }) -> 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.",
+    required: true,
+    fields: { requestPayment: "function", getPayment: "function" },
+  },
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -419,7 +437,7 @@ function deepFreeze(value) {
 }
 
 const CONTRACT = deepFreeze({
-  version: "1.1.0",
+  version: "1.2.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -352,6 +352,112 @@ export function useTheme() {
   return ctx.workspace.theme;
 }
 
+/**
+ * Structured error thrown by `usePayments` callbacks. Carries a stable
+ * `code` so widgets can branch without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "AUTH_REQUIRED"             — no signed-in app user
+ *   - "PAYMENTS_SCOPE_NOT_GRANTED"— widget lacks payments.charge:appUser
+ *   - "INVALID_AMOUNT" / "AMOUNT_TOO_LARGE" / "VALIDATION" — bad request
+ *   - "CONNECT_NOT_READY" / "PAYMENTS_DISABLED" — provider not ready
+ *   - "DECLINED"                  — the charge was declined
+ *   - "INTERNAL"                  — anything else
+ */
+export class PaymentError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "PaymentError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toPaymentError(err) {
+  if (err instanceof PaymentError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : null;
+  const bodyCode =
+    err && err.response && err.response.data && err.response.data.code;
+  const bodyMessage =
+    err && err.response && err.response.data && err.response.data.error;
+  let code = "INTERNAL";
+  if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
+  else if (status === 401) code = "AUTH_REQUIRED";
+  else if (status === 402) code = "DECLINED";
+  else if (status === 403) code = "FORBIDDEN";
+  else if (status === 400) code = "VALIDATION";
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string"
+      ? err.message
+      : "Payment request failed");
+  return new PaymentError(code, message, { cause: 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
+ *       (Stripe provider, `status: "PENDING"`). 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.
+ */
+export function usePayments() {
+  const ctx = useWidgetContextOrThrow("usePayments");
+  if (!ctx.payments || typeof ctx.payments.requestPayment !== "function") {
+    throw new Error(
+      "usePayments: host did not inject a payments client. The widget must " +
+        "declare the payments.charge:appUser scope and be installed in a " +
+        "workspace whose host supports payments.",
+    );
+  }
+  const requestRef = useRef(ctx.payments.requestPayment);
+  const getRef = useRef(
+    typeof ctx.payments.getPayment === "function"
+      ? ctx.payments.getPayment
+      : null,
+  );
+  requestRef.current = ctx.payments.requestPayment;
+  getRef.current =
+    typeof ctx.payments.getPayment === "function"
+      ? ctx.payments.getPayment
+      : null;
+
+  const requestPayment = useCallback(async (args) => {
+    try {
+      return await requestRef.current(args);
+    } catch (err) {
+      throw toPaymentError(err);
+    }
+  }, []);
+  const getPayment = useCallback(async (paymentId) => {
+    if (!getRef.current) {
+      throw new PaymentError(
+        "INTERNAL",
+        "getPayment is not supported by this host.",
+      );
+    }
+    try {
+      return await getRef.current(paymentId);
+    } catch (err) {
+      throw toPaymentError(err);
+    }
+  }, []);
+  return { requestPayment, getPayment };
+}
+
 /**
  * Returns { t, locale }. `t(key, fallback)` resolves `{{t:key}}` against
  * the host's translation table and falls back to `fallback ?? key` when

package/dist/index.d.ts

@@ -188,6 +188,10 @@ export interface WidgetContext<TProps = unknown> {
     listUsers(query?: DirectoryQuery): Promise<DirectoryUser[]>;
   };
   events: { emit(eventName: string, payload?: unknown): void };
+  payments: {
+    requestPayment(args: PaymentRequest): Promise<PaymentResult>;
+    getPayment(paymentId: string): Promise<PaymentResult>;
+  };
   i18n: {
     locale: string;
     t(key: string, vars?: Record<string, unknown>): string;
@@ -316,6 +320,47 @@ 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).
+ */
+export interface PaymentRequest {
+  amountCents: number;
+  currency?: string;
+  description: string;
+  metadata?: Record<string, string>;
+  /** Site-relative path to return to after Checkout (e.g. "/cart"). */
+  returnPath?: string;
+}
+
+export interface PaymentResult {
+  id: string;
+  status: "PENDING" | "PAID" | "FAILED" | "REFUNDED" | "CANCELLED";
+  amountCents?: number;
+  currency?: string;
+  description?: string;
+  /**
+   * Present (Stripe 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 {
+  requestPayment(args: PaymentRequest): Promise<PaymentResult>;
+  getPayment(paymentId: string): Promise<PaymentResult>;
+}
+
+/**
+ * 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.
+ */
+export function usePayments(): PaymentsApi;
+
 export function useTheme(): ThemeTokens;
 
 export function useI18n(): {

package/dist/index.js

@@ -8,10 +8,12 @@ export { validatePropertySchema, validateProps } from "./property-schema.js";
 export {
   WidgetContextProvider,
   DatastoreError,
+  PaymentError,
   useDatastoreQuery,
   useDatastoreMutation,
   useDirectory,
   useWidgetEvent,
+  usePayments,
   useTheme,
   useI18n,
 } from "./hooks.js";

package/dist/index.native.js

@@ -8,10 +8,12 @@ export { validatePropertySchema, validateProps } from "./property-schema.js";
 export {
   WidgetContextProvider,
   DatastoreError,
+  PaymentError,
   useDatastoreQuery,
   useDatastoreMutation,
   useDirectory,
   useWidgetEvent,
+  usePayments,
   useTheme,
   useI18n,
 } from "./hooks.js";

package/dist/primitives.js

@@ -17,19 +17,41 @@
 // The static analyzer's allowedBareImports still rejects direct
 // `react-native` imports; the SDK is the single entry point.
 
-export {
-  Text,
-  View,
-  Pressable,
-  Image,
-  ScrollView,
-  TextInput,
-  // Additional cross-platform primitives the AI agent + handwritten
-  // widgets commonly reach for. All work in both react-native-web and
-  // native react-native without per-platform code.
-  FlatList,
-  SectionList,
-  ActivityIndicator,
-  Switch,
-  StyleSheet,
-} from "react-native";
+// This is the WEB primitive surface (the native shell uses
+// `primitives.native.js`, which Metro selects via the package.json
+// `react-native` field). It imports `react-native-web` directly rather
+// than the bare `react-native` specifier for two reasons:
+//
+//  1. `react-native` is declared an OPTIONAL peer dep of this package.
+//     When the host builds with Vite 8 / rolldown, rolldown intercepts
+//     the bare `react-native` import with a generated
+//     `__vite-optional-peer-dep` stub BEFORE the host's
+//     `react-native$ → react-native-web` alias can apply, leaving some
+//     members (`Switch`, `StyleSheet`, …) `undefined` at runtime.
+//  2. The direct `export { X } from "react-native"` re-export form
+//     additionally failed the production build outright
+//     (`[MISSING_EXPORT] "Pressable" is not exported`) because rolldown
+//     does not statically trace react-native-web's
+//     `export { default as X } from './exports/X'` chains.
+//
+// Importing `react-native-web` as a namespace and re-exporting each
+// member as a local `const` resolves both: react-native-web is a real
+// installed dep (no stub), and runtime property access sidesteps the
+// static re-export tracing. Behaviour is identical to the old
+// `react-native` alias path on the web.
+import * as ReactNative from "react-native-web";
+
+export const Text = ReactNative.Text;
+export const View = ReactNative.View;
+export const Pressable = ReactNative.Pressable;
+export const Image = ReactNative.Image;
+export const ScrollView = ReactNative.ScrollView;
+export const TextInput = ReactNative.TextInput;
+// Additional cross-platform primitives the AI agent + handwritten
+// widgets commonly reach for. All work in both react-native-web and
+// native react-native without per-platform code.
+export const FlatList = ReactNative.FlatList;
+export const SectionList = ReactNative.SectionList;
+export const ActivityIndicator = ReactNative.ActivityIndicator;
+export const Switch = ReactNative.Switch;
+export const StyleSheet = ReactNative.StyleSheet;

package/package.json

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