@colixsystems/widget-sdk 0.277.4 → 0.278.0

package/README.md

@@ -87,7 +87,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.277.4` — 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.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**.
+
+### What's new in 0.278.0 (contract 1.227.0)
+
+**New `usePurchases()` hook: sell digital goods in the native app through the App Store and Google Play.** It runs on the workspace's own RevenueCat project and returns `{ supported, loading, offering, entitlements, error, purchase, restore, refresh }`. `offering` is the current offering (`{ id, packages: [{ id, title, description, priceString, currencyCode }] }`), `entitlements` the signed-in user's active entitlement identifiers, and `purchase(packageId)` / `restore()` resolve the updated entitlements or reject with a `PurchasesError` (`UNSUPPORTED`, `SIGN_IN_REQUIRED`, `CANCELLED`, `NOT_FOUND`, `PURCHASE_FAILED`, `INTERNAL`). It is native-only: a browser has no store billing, so on the web Player `supported` is `false` and the widget must show a visible "available in the app" state. `react-native-purchases` is now a vetted native-only import; prefer the hook, and never configure or log in Purchases yourself.
 
 ### What's new in 0.277.4
 

package/dist/contract.cjs

@@ -3130,6 +3130,37 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-15163 — native-only in-app purchase. Optional slice; the hook reports
+  // supported:false on the web Player rather than throwing at render.
+  {
+    name: "usePurchases",
+    signature: "usePurchases()",
+    description:
+      "Sell digital goods (a subscription, premium content, credits) in the native app through the App Store and Google " +
+      "Play, on the workspace's own RevenueCat project. Returns { supported, loading, offering, entitlements, error, " +
+      "purchase, restore, refresh }. `offering` is the current offering set up in RevenueCat — { id, packages: [{ id, " +
+      "title, description, priceString, currencyCode }] } or null; show priceString as-is, the store localises it. " +
+      "`entitlements` lists the signed-in user's ACTIVE entitlement identifiers — unlock content by checking it. " +
+      "purchase(packageId) opens the store's own sheet and resolves the updated entitlements; restore() re-reads purchases " +
+      "made on another device (offer it: the stores require a way to restore). Both reject with a PurchasesError whose " +
+      ".code is one of UNSUPPORTED | SIGN_IN_REQUIRED | CANCELLED | NOT_FOUND | PURCHASE_FAILED | INTERNAL; CANCELLED means " +
+      "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.",
+    returnShape: {
+      supported: "boolean  // false on the web Player and in an app built without RevenueCat",
+      loading: "boolean",
+      offering: "{ id, packages: [{ id, title, description, priceString, currencyCode }] } | null",
+      entitlements: "string[]  // active entitlement identifiers",
+      error: "PurchasesError | null",
+      purchase: "(packageId: string) => Promise<string[]>  // rejects with PurchasesError",
+      restore: "() => Promise<string[]>  // rejects with PurchasesError",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useAudioPlayer",
     signature: "useAudioPlayer(uri)",
@@ -4432,7 +4463,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "audioRecorder: { isSupported() -> boolean, getPermission() -> Promise<'granted' | 'denied' | 'undetermined'>, " +
       "start() -> Promise<{ getStatus() -> { durationMs, levelDb, ended }, stop() -> Promise<{ file, uri, durationMs, mime, release? }>, cancel() }> }, " +
       "audioPlayer: { isSupported() -> boolean, load(uri, onStatus({ loaded, playing, positionMs, durationMs, error? })) -> " +
-      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } } }. " +
+      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } }, " +
+      "purchases: { isSupported() -> boolean, getOffering() -> Promise<offering | null>, getEntitlements() -> Promise<string[]>, " +
+      "purchase(packageId) -> Promise<string[]>, restore() -> Promise<string[]> } }. " +
+      "purchases backs usePurchases() and is NATIVE-ONLY: the Expo export brokers it through react-native-purchases when the " +
+      "workspace connected RevenueCat; the web Player never does, because a browser has no store billing. " +
       "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner(), usePdfExport().openPdf, useAudioRecorder() and useAudioPlayer(). The web Player brokers them via " +
       "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector, a new browser tab, MediaRecorder and an <audio> element; the Expo export via " +
       "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera, expo-print and expo-audio. " +
@@ -4472,6 +4507,7 @@ const WIDGET_CONTEXT_SHAPE = {
       pdfViewer: "object",
       audioRecorder: "object",
       audioPlayer: "object",
+      purchases: "object",
     },
   },
 };
@@ -4702,6 +4738,18 @@ const VETTED_IMPORTS = [
     description:
       "Native clipboard. The SDK's useClipboard() hook already wraps this; reach for it directly only if you need RN-specific options.",
   },
+  // sc-15163 — native-only: a browser has no App Store / Google Play billing.
+  {
+    specifier: "react-native-purchases",
+    platforms: ["native"],
+    category: "payments",
+    description:
+      "RevenueCat in-app purchase (StoreKit / Play Billing). PREFER usePurchases() from the SDK, which already runs on the " +
+      "app's configured, signed-in customer. Import this directly only for what the hook does not cover, and NEVER call " +
+      "Purchases.configure, logIn or logOut — the app owns them, and it configures Purchases only when the workspace " +
+      "connected RevenueCat. Native-only because no browser offers store billing: author it in widget.native.jsx and give " +
+      "widget.web.jsx a visible 'available in the app' state.",
+  },
   {
     specifier: "expo-haptics",
     platforms: ["native"],
@@ -6577,7 +6625,10 @@ const CONTRACT = deepFreeze({
   // 1.226.0: behaviour (sc-15080) — `<MarkdownInput>` is a rich-text editor
   //    showing the formatted result; `showPreview`, `previewLabel` and
   //    `renderImage` are accepted and ignored.
-  version: "1.226.0",
+  // 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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3126,6 +3126,37 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-15163 — native-only in-app purchase. Optional slice; the hook reports
+  // supported:false on the web Player rather than throwing at render.
+  {
+    name: "usePurchases",
+    signature: "usePurchases()",
+    description:
+      "Sell digital goods (a subscription, premium content, credits) in the native app through the App Store and Google " +
+      "Play, on the workspace's own RevenueCat project. Returns { supported, loading, offering, entitlements, error, " +
+      "purchase, restore, refresh }. `offering` is the current offering set up in RevenueCat — { id, packages: [{ id, " +
+      "title, description, priceString, currencyCode }] } or null; show priceString as-is, the store localises it. " +
+      "`entitlements` lists the signed-in user's ACTIVE entitlement identifiers — unlock content by checking it. " +
+      "purchase(packageId) opens the store's own sheet and resolves the updated entitlements; restore() re-reads purchases " +
+      "made on another device (offer it: the stores require a way to restore). Both reject with a PurchasesError whose " +
+      ".code is one of UNSUPPORTED | SIGN_IN_REQUIRED | CANCELLED | NOT_FOUND | PURCHASE_FAILED | INTERNAL; CANCELLED means " +
+      "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.",
+    returnShape: {
+      supported: "boolean  // false on the web Player and in an app built without RevenueCat",
+      loading: "boolean",
+      offering: "{ id, packages: [{ id, title, description, priceString, currencyCode }] } | null",
+      entitlements: "string[]  // active entitlement identifiers",
+      error: "PurchasesError | null",
+      purchase: "(packageId: string) => Promise<string[]>  // rejects with PurchasesError",
+      restore: "() => Promise<string[]>  // rejects with PurchasesError",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useAudioPlayer",
     signature: "useAudioPlayer(uri)",
@@ -4428,7 +4459,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "audioRecorder: { isSupported() -> boolean, getPermission() -> Promise<'granted' | 'denied' | 'undetermined'>, " +
       "start() -> Promise<{ getStatus() -> { durationMs, levelDb, ended }, stop() -> Promise<{ file, uri, durationMs, mime, release? }>, cancel() }> }, " +
       "audioPlayer: { isSupported() -> boolean, load(uri, onStatus({ loaded, playing, positionMs, durationMs, error? })) -> " +
-      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } } }. " +
+      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } }, " +
+      "purchases: { isSupported() -> boolean, getOffering() -> Promise<offering | null>, getEntitlements() -> Promise<string[]>, " +
+      "purchase(packageId) -> Promise<string[]>, restore() -> Promise<string[]> } }. " +
+      "purchases backs usePurchases() and is NATIVE-ONLY: the Expo export brokers it through react-native-purchases when the " +
+      "workspace connected RevenueCat; the web Player never does, because a browser has no store billing. " +
       "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner(), usePdfExport().openPdf, useAudioRecorder() and useAudioPlayer(). The web Player brokers them via " +
       "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector, a new browser tab, MediaRecorder and an <audio> element; the Expo export via " +
       "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera, expo-print and expo-audio. " +
@@ -4468,6 +4503,7 @@ const WIDGET_CONTEXT_SHAPE = {
       pdfViewer: "object",
       audioRecorder: "object",
       audioPlayer: "object",
+      purchases: "object",
     },
   },
 };
@@ -4698,6 +4734,18 @@ const VETTED_IMPORTS = [
     description:
       "Native clipboard. The SDK's useClipboard() hook already wraps this; reach for it directly only if you need RN-specific options.",
   },
+  // sc-15163 — native-only: a browser has no App Store / Google Play billing.
+  {
+    specifier: "react-native-purchases",
+    platforms: ["native"],
+    category: "payments",
+    description:
+      "RevenueCat in-app purchase (StoreKit / Play Billing). PREFER usePurchases() from the SDK, which already runs on the " +
+      "app's configured, signed-in customer. Import this directly only for what the hook does not cover, and NEVER call " +
+      "Purchases.configure, logIn or logOut — the app owns them, and it configures Purchases only when the workspace " +
+      "connected RevenueCat. Native-only because no browser offers store billing: author it in widget.native.jsx and give " +
+      "widget.web.jsx a visible 'available in the app' state.",
+  },
   {
     specifier: "expo-haptics",
     platforms: ["native"],
@@ -6573,7 +6621,10 @@ const CONTRACT = deepFreeze({
   // 1.226.0: behaviour (sc-15080) — `<MarkdownInput>` is a rich-text editor
   //    showing the formatted result; `showPreview`, `previewLabel` and
   //    `renderImage` are accepted and ignored.
-  version: "1.226.0",
+  // 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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -946,6 +946,14 @@ export interface WidgetContext<TProps = unknown> {
         release(): void;
       };
     };
+    /** sc-15163 — backs usePurchases. Brokered by the Expo export only. */
+    purchases?: {
+      isSupported?(): boolean;
+      getOffering(): Promise<PurchaseOffering | null>;
+      getEntitlements(): Promise<string[]>;
+      purchase(packageId: string): Promise<string[]>;
+      restore(): Promise<string[]>;
+    };
     speech?: {
       isSupported?(): boolean;
       start(
@@ -2895,6 +2903,54 @@ export interface AudioPlayerResult {
  */
 export function useAudioPlayer(uri: string | null | undefined): AudioPlayerResult;
 
+/** One package of the current offering, as the store prices it. */
+export interface PurchasePackage {
+  id: string;
+  title: string;
+  description: string;
+  priceString: string;
+  currencyCode: string;
+}
+
+/** The current offering the workspace set up in RevenueCat. */
+export interface PurchaseOffering {
+  id: string;
+  packages: PurchasePackage[];
+}
+
+/** What `usePurchases()` returns. */
+export interface PurchasesResult {
+  /** False on the web Player: store billing needs the native app. */
+  supported: boolean;
+  loading: boolean;
+  offering: PurchaseOffering | null;
+  /** The signed-in user's active entitlement identifiers. */
+  entitlements: string[];
+  error: PurchasesError | null;
+  purchase(packageId: string): Promise<string[]>;
+  restore(): Promise<string[]>;
+  refresh(): Promise<void>;
+}
+
+/**
+ * Sell digital goods through the App Store and Google Play, on the
+ * workspace's own RevenueCat project. Native-only: on the web Player
+ * `supported` is false — render a visible "not available on the web" state.
+ */
+export function usePurchases(): PurchasesResult;
+
+/** Error surfaced by `usePurchases()`. */
+export class PurchasesError extends Error {
+  code:
+    | "UNSUPPORTED"
+    | "SIGN_IN_REQUIRED"
+    | "CANCELLED"
+    | "NOT_FOUND"
+    | "PURCHASE_FAILED"
+    | "INTERNAL";
+  constructor(code: PurchasesError["code"], message: string, opts?: { cause?: unknown });
+}
+
 /** Error surfaced by `useAudioPlayer()`. */
 export class AudioPlayerError extends Error {
   code: "UNSUPPORTED" | "LOAD_FAILED" | "BLOCKED" | "INTERNAL";

package/dist/index.js

@@ -132,6 +132,8 @@ export {
   useAudioPlayer,
   AudioPlayerError,
 } from "./audio.js";
+// sc-15163 — native-only in-app purchase; the web Player brokers none.
+export { usePurchases, PurchasesError } from "./purchases.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useDatastoreAggregate,

package/dist/index.native.js

@@ -130,6 +130,8 @@ export {
   useAudioPlayer,
   AudioPlayerError,
 } from "./audio.js";
+// sc-15163 — native-only in-app purchase; the web Player brokers none.
+export { usePurchases, PurchasesError } from "./purchases.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useDatastoreAggregate,

package/dist/purchases.js

@@ -0,0 +1,143 @@
+// Host-brokered in-app purchase: `usePurchases()`.
+//
+// Native-only. The Expo export brokers ctx.device.purchases through
+// react-native-purchases on the workspace's own RevenueCat project, which
+// sells through Apple's StoreKit and Google Play Billing. A browser has no
+// store billing, so the web Player brokers nothing and the hook reports
+// `supported: false`; a widget renders its "not available on the web" state.
+//
+// This file avoids JSX so it can ship as a plain .js without a transform.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useWidgetContextOrThrow } from "./hooks.js";
+
+/**
+ * Error surfaced by `usePurchases()` (thrown by `purchase()` / `restore()`
+ * and stored in the hook's `error` slot).
+ *
+ * `code` is one of:
+ *   - "UNSUPPORTED"      — this host sells nothing in-app (the web Player).
+ *   - "SIGN_IN_REQUIRED" — no app user is signed in to buy for.
+ *   - "CANCELLED"        — the buyer closed the store sheet.
+ *   - "NOT_FOUND"        — no package with that id is for sale.
+ *   - "PURCHASE_FAILED"  — the store refused or failed the purchase.
+ *   - "INTERNAL"         — anything else.
+ */
+export class PurchasesError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "PurchasesError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+const KNOWN_CODES = new Set([
+  "UNSUPPORTED",
+  "SIGN_IN_REQUIRED",
+  "CANCELLED",
+  "NOT_FOUND",
+  "PURCHASE_FAILED",
+]);
+
+function toPurchasesError(err) {
+  if (err instanceof PurchasesError) return err;
+  const code = KNOWN_CODES.has(err && err.code) ? err.code : "INTERNAL";
+  const message = (err && typeof err.message === "string" && err.message) || "Purchase failed";
+  return new PurchasesError(code, message, { cause: err });
+}
+
+function isUsable(client) {
+  return Boolean(
+    client &&
+      typeof client.purchase === "function" &&
+      (typeof client.isSupported !== "function" || client.isSupported()),
+  );
+}
+
+const NO_ENTITLEMENTS = Object.freeze([]);
+
+/**
+ * Sell digital goods in the app through the App Store and Google Play.
+ * Returns `{ supported, loading, offering, entitlements, error, purchase,
+ * restore, refresh }`.
+ *
+ * `offering` is the current offering the workspace set up in RevenueCat —
+ * `{ id, packages: [{ id, title, description, priceString, currencyCode }] }`
+ * or null. `entitlements` lists the signed-in user's active entitlement
+ * identifiers. `purchase(packageId)` and `restore()` resolve the updated
+ * entitlements and reject with a `PurchasesError`; a cancelled purchase has
+ * code "CANCELLED" and is usually not worth showing as an error.
+ *
+ * Native-only: on the web Player `supported` is false. ALWAYS render a visible
+ * "not available on the web" state then, never a blank or a dead button.
+ */
+export function usePurchases() {
+  const ctx = useWidgetContextOrThrow("usePurchases");
+  const client = ctx.device && ctx.device.purchases;
+  const clientRef = useRef(client);
+  clientRef.current = client;
+  const supported = isUsable(client);
+
+  const [loading, setLoading] = useState(supported);
+  const [offering, setOffering] = useState(null);
+  const [entitlements, setEntitlements] = useState(NO_ENTITLEMENTS);
+  const [error, setError] = useState(null);
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const refresh = useCallback(async () => {
+    const live = clientRef.current;
+    if (!isUsable(live)) return;
+    setLoading(true);
+    try {
+      const [nextOffering, nextEntitlements] = await Promise.all([
+        live.getOffering(),
+        live.getEntitlements(),
+      ]);
+      if (!mountedRef.current) return;
+      setOffering(nextOffering || null);
+      setEntitlements(nextEntitlements || NO_ENTITLEMENTS);
+      setError(null);
+    } catch (err) {
+      if (mountedRef.current) setError(toPurchasesError(err));
+    } finally {
+      if (mountedRef.current) setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (supported) refresh();
+  }, [supported, refresh]);
+
+  const run = useCallback(async (method, arg) => {
+    const live = clientRef.current;
+    if (!isUsable(live)) {
+      const unsupported = new PurchasesError("UNSUPPORTED", "In-app purchase is not available here.");
+      setError(unsupported);
+      throw unsupported;
+    }
+    try {
+      const next = await live[method](arg);
+      if (mountedRef.current) {
+        setEntitlements(next || NO_ENTITLEMENTS);
+        setError(null);
+      }
+      return next || NO_ENTITLEMENTS;
+    } catch (err) {
+      const wrapped = toPurchasesError(err);
+      if (mountedRef.current) setError(wrapped);
+      throw wrapped;
+    }
+  }, []);
+
+  const purchase = useCallback((packageId) => run("purchase", packageId), [run]);
+  const restore = useCallback(() => run("restore"), [run]);
+
+  return { supported, loading: supported && loading, offering, entitlements, error, purchase, restore, refresh };
+}

package/package.json

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

@@ -3126,6 +3126,37 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-15163 — native-only in-app purchase. Optional slice; the hook reports
+  // supported:false on the web Player rather than throwing at render.
+  {
+    name: "usePurchases",
+    signature: "usePurchases()",
+    description:
+      "Sell digital goods (a subscription, premium content, credits) in the native app through the App Store and Google " +
+      "Play, on the workspace's own RevenueCat project. Returns { supported, loading, offering, entitlements, error, " +
+      "purchase, restore, refresh }. `offering` is the current offering set up in RevenueCat — { id, packages: [{ id, " +
+      "title, description, priceString, currencyCode }] } or null; show priceString as-is, the store localises it. " +
+      "`entitlements` lists the signed-in user's ACTIVE entitlement identifiers — unlock content by checking it. " +
+      "purchase(packageId) opens the store's own sheet and resolves the updated entitlements; restore() re-reads purchases " +
+      "made on another device (offer it: the stores require a way to restore). Both reject with a PurchasesError whose " +
+      ".code is one of UNSUPPORTED | SIGN_IN_REQUIRED | CANCELLED | NOT_FOUND | PURCHASE_FAILED | INTERNAL; CANCELLED means " +
+      "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.",
+    returnShape: {
+      supported: "boolean  // false on the web Player and in an app built without RevenueCat",
+      loading: "boolean",
+      offering: "{ id, packages: [{ id, title, description, priceString, currencyCode }] } | null",
+      entitlements: "string[]  // active entitlement identifiers",
+      error: "PurchasesError | null",
+      purchase: "(packageId: string) => Promise<string[]>  // rejects with PurchasesError",
+      restore: "() => Promise<string[]>  // rejects with PurchasesError",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useAudioPlayer",
     signature: "useAudioPlayer(uri)",
@@ -4428,7 +4459,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "audioRecorder: { isSupported() -> boolean, getPermission() -> Promise<'granted' | 'denied' | 'undetermined'>, " +
       "start() -> Promise<{ getStatus() -> { durationMs, levelDb, ended }, stop() -> Promise<{ file, uri, durationMs, mime, release? }>, cancel() }> }, " +
       "audioPlayer: { isSupported() -> boolean, load(uri, onStatus({ loaded, playing, positionMs, durationMs, error? })) -> " +
-      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } } }. " +
+      "{ play() -> Promise<void>, pause(), seek(ms) -> Promise<void>, release() } }, " +
+      "purchases: { isSupported() -> boolean, getOffering() -> Promise<offering | null>, getEntitlements() -> Promise<string[]>, " +
+      "purchase(packageId) -> Promise<string[]>, restore() -> Promise<string[]> } }. " +
+      "purchases backs usePurchases() and is NATIVE-ONLY: the Expo export brokers it through react-native-purchases when the " +
+      "workspace connected RevenueCat; the web Player never does, because a browser has no store billing. " +
       "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner(), usePdfExport().openPdf, useAudioRecorder() and useAudioPlayer(). The web Player brokers them via " +
       "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector, a new browser tab, MediaRecorder and an <audio> element; the Expo export via " +
       "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera, expo-print and expo-audio. " +
@@ -4468,6 +4503,7 @@ const WIDGET_CONTEXT_SHAPE = {
       pdfViewer: "object",
       audioRecorder: "object",
       audioPlayer: "object",
+      purchases: "object",
     },
   },
 };
@@ -4698,6 +4734,18 @@ const VETTED_IMPORTS = [
     description:
       "Native clipboard. The SDK's useClipboard() hook already wraps this; reach for it directly only if you need RN-specific options.",
   },
+  // sc-15163 — native-only: a browser has no App Store / Google Play billing.
+  {
+    specifier: "react-native-purchases",
+    platforms: ["native"],
+    category: "payments",
+    description:
+      "RevenueCat in-app purchase (StoreKit / Play Billing). PREFER usePurchases() from the SDK, which already runs on the " +
+      "app's configured, signed-in customer. Import this directly only for what the hook does not cover, and NEVER call " +
+      "Purchases.configure, logIn or logOut — the app owns them, and it configures Purchases only when the workspace " +
+      "connected RevenueCat. Native-only because no browser offers store billing: author it in widget.native.jsx and give " +
+      "widget.web.jsx a visible 'available in the app' state.",
+  },
   {
     specifier: "expo-haptics",
     platforms: ["native"],
@@ -6573,7 +6621,10 @@ const CONTRACT = deepFreeze({
   // 1.226.0: behaviour (sc-15080) — `<MarkdownInput>` is a rich-text editor
   //    showing the formatted result; `showPreview`, `previewLabel` and
   //    `renderImage` are accepted and ignored.
-  version: "1.226.0",
+  // 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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,