@wix/himalaya-cli 0.1243.0 → 0.1245.0

package/guides/iap-pricing.md

@@ -1,225 +1,176 @@
-# Shared Apple IAP pricing
-
-`@himalaya/iap` resolves read-only payment mappings and retrieves Apple metadata for
-cards, details, and checkout previews. It neither buys anything nor proves access.
-The mapping provider is an internal client port; a deployed production backend is
-still required. Do not call the purchase-delivery coordinator for price lookup.
-
-## Inputs and states
-
-Create one controller per worker/service with `createPricingController({ mapping,
-getProducts, onState })`. Inject the existing SDK `getProducts` as the real store
-adapter; tests may inject another function. `load(input)` accepts:
-
-- `scope`: app ID, bundle ID, Wix site ID, and optional opaque `contextRevision`.
-  Change the revision whenever a member/audience change affects mapping. Pass no
-  credential or raw member identity.
-- `platform`: the actual trusted host platform. Only `ios` resolves Apple prices.
-- `items`: `{ reference: { kind, id }, commerceDisplayPrice? }`. References are
-  unique by the pair; repeated references retain the first occurrence and its
-  commerce input. Different entity kinds cannot collide.
-
-The injected batch `mapping.resolve({ scope, references })` returns one mapping
-per requested reference: `appleIap` with `productId` and `mappingRevision`,
-`regular`, or `unavailable`. Missing, duplicate, unknown, or malformed routes are
-unresolved. This is not an agreed Scala wire contract or a deployed endpoint.
-
-`getState()` returns a detached serializable snapshot with revision, captured
-scope, and per-reference items. Loading and unavailable items contain **no price**.
-Apple ready items carry `source: "appleIap"`, product ID, mapping revision, and
-exact StoreKit `displayPrice`; regular ready items carry `source: "regular"` and
-the caller's existing commerce price. Copy remains the screen's responsibility.
-When that commerce price is missing or blank, `commercePriceUnavailable` is
-non-retryable: the caller must supply a usable price in a new `load(input)`.
-Refreshing the same input cannot supply it.
-
-Apple strings are displayed unchanged, including spaces and currency placement;
-they are not reconstructed from micros or phone locale. See Apple's
-[displayPrice contract](https://developer.apple.com/documentation/storekit/product/displayprice).
-Only non-consumables are supported here. A lookup failure, empty response, missing
-product, or blank price is `priceUnavailable`, not proof of a network failure or
-nonexistent product: the current native adapter collapses store errors into `[]`.
-There is never a Wix price or external-checkout fallback for an Apple route.
-
-`load` batches unique Apple IDs and joins identical work already in flight within
-this controller. Input identity includes scope, platform, item order/references,
-and commerce display prices. Every call after completion performs a fresh lookup.
-`refresh()` reloads the last captured input, also joining identical in-flight work.
-Changing input invalidates prior work before its results can publish; obsolete
-mapping results do not start a store lookup. `dispose()` clears readable state,
-suppresses later publications/calls, and cannot cancel store/network I/O already
-sent. No persistent or app-wide cache exists; separate workers perform independent
-lookups.
-
-## Complete Tier-5 service example
-
-This example is compiled and executed by `pricing-integration.test.ts` against the
-actual worker bootstrap and SDK dispatch seam. Register it separately in each
-screen worker, injecting the mapping provider and trusted initial input. It is a
-checkout **preview**: purchase readiness stays false independently of metadata.
+# Showing App Store prices on any screen
 
-```ts
-// pricing-worker.ts
-import { defineService } from "@himalaya/state";
-import {
-  createPricingController, getProducts,
-  type PricingInput, type PricingMappingProvider, type PricingState,
-} from "@himalaya/iap";
-
-export interface PriceCopy {
-  loading: string;
-  unavailable: string;
-  apple: string;
-  regular: string;
-}
+`@himalaya/iap` gives every screen one shared way to show the App Store price of an item it
+displays or sells: a program, a product, a plan, or anything else you registered with
+`himi store iap`. Your worker passes its scope and the items on screen. The shared layer looks up
+which items are sold through the App Store, fetches their prices from Apple, and returns display
+state plus a payment route. Your screen binds the result to its own UI.
 
-interface PriceRow {
-  id: string;
-  status: "loading" | "ready" | "unavailable";
-  displayPrice: string;
-  message: string;
-  retryable: boolean;
-  loading: boolean;
-  hideLoading: boolean;
-  hideRetry: boolean;
-}
+> **Not switched on yet.** Wix has not connected the service that maps your catalog to App Store
+> products. Until it does, every screen keeps its existing price and checkout. Apple purchasing is
+> not available in any case: this layer shows prices and blocks the wrong checkout, but never buys.
+> Only one-time purchases (non-consumables) are supported. Subscriptions and consumables are not.
 
-interface PriceServiceState {
-  pricing: PricingState;
-  rows: PriceRow[];
-  canPurchase: boolean;
-  purchaseDisabled: boolean;
-}
+## What you get per item
 
-export function registerPricingService(
-  mapping: PricingMappingProvider, initialInput: PricingInput, copy: PriceCopy,
-) {
-  let input = initialInput;
-  let disposed = false;
-  const controller = createPricingController({
-    mapping, getProducts,
-    onState: () => { void service.publish(); },
-  });
+`pricing.view(reference)` returns plain data you can put in state. Its `route` tells the screen
+what to do:
+
+| `route` | Show | Existing checkout |
+|---|---|---|
+| `disabled` | Your screen's own price, exactly as before | Allowed |
+| `resolving` | A "Loading price…" label, never your own price | Blocked |
+| `appleIap` | `displayPrice` exactly as Apple formats it, plus a "One-time purchase" note | Blocked; purchasing is not available yet |
+| `regular` | `displayPrice` (the commerce price you passed), or nothing | Allowed |
+| `unavailable` | "Price unavailable", plus Retry when `retryable` | Blocked |
+
+Never fall back to your own price or checkout for an item on an App Store route. A missing price
+does not mean the item is free. Only an explicit `regular` route keeps your existing flow.
+
+`iapPriceFields(view, copy)` turns a view into bindable fields (`priceText`, `priceNote`,
+`priceLoading`, `hidePriceRetry`, `actionDisabled`, `actionNote`) using labels from your own copy.
+
+## Catalog references
+
+An item is identified by `{ kind, id }`. The kind is the same entity type `himi store iap` uses
+when it registers the item with Apple:
+
+| `kind` | Item | Helper |
+|---|---|---|
+| `onlineProgram` | An Online Programs program | `onlineProgramItem(program, commercePrice)` |
+| `storesProduct` | A Wix Stores product | Build `{ kind: "storesProduct", id }` |
+| `pricingPlan` | A one-time Pricing Plans plan | Build `{ kind: "pricingPlan", id }` |
+
+## Add it to a worker
+
+This is a complete worker for one screen. Copy the pattern, not the course names.
 
-  function project(pricing: PricingState): PriceRow[] {
-    return pricing.items.map(item => ({
-      id: JSON.stringify([item.reference.kind, item.reference.id]),
-      status: item.status,
-      displayPrice: item.status === "ready" ? item.displayPrice : "",
-      message: item.status === "loading" ? copy.loading : item.status === "unavailable"
-        ? copy.unavailable : item.source === "appleIap" ? copy.apple : copy.regular,
-      retryable: item.status === "unavailable" && item.retryable,
-      loading: item.status === "loading",
-      hideLoading: item.status !== "loading",
-      hideRetry: item.status !== "unavailable" || !item.retryable,
-    }));
+```ts
+// catalog-pricing-worker.ts
+import { defineService } from "@himalaya/state";
+import { get as appInfo } from "@himalaya/app-info";
+import { createIapCatalogPricing, iapPriceFields, onlineProgramItem } from "@himalaya/iap";
+
+const COPY = {
+  loading: "Loading price…",
+  unavailable: "Price unavailable",
+  oneTimePurchase: "One-time purchase",
+  purchaseUnavailable: "Purchasing is not available yet.",
+};
+// This run's prices and buy state must never be restored from a cold-boot snapshot.
+const PRICE_KEYS = ["priceText", "priceNote", "hidePriceRetry", "buyDisabled", "buyNote"];
+
+interface Course { id: string; title: string; commercePrice: string }
+type CourseState = Record<string, unknown>;
+
+/** `startCheckout` is the screen's existing commerce flow. */
+export function registerCourseScreen(course: Course, startCheckout: () => Promise<string>) {
+  const pricing = createIapCatalogPricing({ onChange: () => { void service.publish(); } });
+  const item = onlineProgramItem({ id: course.id }, course.commercePrice)!;
+  let message = "";
+  let scopeIncomplete = false;
+
+  async function hostScope() {
+    const info = await appInfo().catch(() => undefined);
+    scopeIncomplete = !info?.appId || !info?.bundleId || !info?.platform;
+    return { scope: { appId: info?.appId ?? "", bundleId: info?.bundleId ?? "" }, platform: info?.platform ?? "" };
   }
 
-  const actions = {
-    start: (state: PriceServiceState) => ({ ...state, _poll: {
-      id: "pricing", action: "pricing.reload", intervalMs: 60_000, immediate: true,
-    } }),
-    publish: (state: PriceServiceState) => {
-      const pricing = controller.getState();
-      return { ...state, pricing, rows: project(pricing), canPurchase: false, purchaseDisabled: true };
-    },
-    reload: async () => {
-      if (!disposed) await controller.load(input);
-      // Publication uses a separate reducer; returning captured state would race.
-      return undefined;
-    },
-    retry: async () => {
-      if (!disposed) await controller.refresh();
-      return undefined;
-    },
-    setInput: async (_state: PriceServiceState, next: PricingInput) => {
-      if (!disposed) { input = next; await controller.load(input); }
-      return undefined;
-    },
-    dispose: (state: PriceServiceState) => {
-      disposed = true;
-      controller.dispose();
-      return { ...state, pricing: controller.getState(), rows: [], canPurchase: false, purchaseDisabled: true };
+  async function loadPrices() {
+    if (pricing.enabled) await pricing.load({ ...(await hostScope()), items: [item] });
+    void service.publish();
+  }
+
+  function present(state: CourseState): CourseState {
+    if (!pricing.enabled) return { ...state, priceText: course.commercePrice, buyDisabled: false, message };
+    const price = iapPriceFields(pricing.view(item.reference), COPY);
+    return { ...state, priceText: price.priceText, priceNote: price.priceNote, hidePriceRetry: price.hidePriceRetry && !scopeIncomplete,
+      buyDisabled: price.actionDisabled, buyNote: price.actionNote, message };
+  }
+
+  const service = defineService("course", {
+    state: { title: course.title, priceText: "", priceNote: "", hidePriceRetry: true, buyDisabled: pricing.enabled, buyNote: "", message: "" } as CourseState,
+    notHydrated: pricing.enabled ? PRICE_KEYS : [],
+    actions: {
+      // The screen starts the first lookup; the host's poll and Retry only refresh one that exists.
+      start: (state: CourseState) => {
+        void loadPrices();
+        return { ...present(state), _poll: pricing.pollDirective("course.refreshPrice") };
+      },
+      publish: (state: CourseState) => present(state),
+      // Re-reads the host too: `pricing.refresh()` would replay a scope whose identity read failed.
+      refreshPrice: async () => { await loadPrices(); return undefined; },
+      buy: async () => {
+        // Re-check at the moment of the mutation: a price refresh can change the route after render.
+        // While a refresh resolves the route is unknown, so refuse without claiming anything.
+        const start = pricing.checkoutGuard(item.reference);
+        if (start.allowed) message = await startCheckout();
+        else message = start.route === "resolving" ? "" : COPY.purchaseUnavailable;
+        void service.publish();
+        return undefined;
+      },
     },
-  };
-  const initialPricing: PricingState = { ...controller.getState(), items: initialInput.items.map(item => ({
-    reference: { kind: item.reference.kind, id: item.reference.id }, status: "loading",
-  })) };
-  const service = defineService<PriceServiceState, typeof actions>("pricing", {
-    state: { pricing: initialPricing, rows: project(initialPricing), canPurchase: false, purchaseDisabled: true },
-    notHydrated: ["pricing", "rows", "canPurchase", "purchaseDisabled"], actions,
   });
   void service.start();
   return service;
 }
 ```
 
-The bundle must declare `iap`. To derive platform/app identity from the host,
-declare `app_info` too and call `@himalaya/app-info.get()` before registering the
-service. Use its `platform`, `appId`, and `bundleId`, with the caller's site and
-opaque context revision. If the call rejects or identity is absent, keep the
-Apple route unavailable; never assume iOS. Its `environment: dev | prod` describes
-Himalaya serving, **not** Apple Sandbox/production. Do not introduce an app-info
-dependency into the pricing package itself.
-
-Bind price text to `$service:pricing.rows.0.displayPrice` for a single card/detail/
-checkout item, and use the existing bound list template for multiple rows. Bind
-loading visibility to `hideLoading`, Retry visibility to `hideRetry`, and the
-purchase button's `disabledPath` to `$service:pricing.purchaseDisabled`. The Retry
-action is `tier5.pricing.retry`. Existing Text, ActivityIndicator, and Button components
-are sufficient; keep labels in the consuming copy pack and use stable component
-IDs. Regular commerce route/checkout remains owned by the existing commerce flow.
-
-## Lifecycle and purchase boundaries
-
-The service arms `_poll` at module evaluation with an immediate first load and a
-60-second visible cadence. The **host** schedules it: worker JS has no ordinary
-timers. Current iOS pooling pauses off-screen polls, resumes immediately on return,
-and the lifecycle scheduler pauses in the background and fires on resume. Worker
-teardown cancels polling. `_poll` has no explicit stop directive; a disposed
-service ignores subsequent ticks until its worker is destroyed.
-
-Use the same module-evaluation registration on card, detail, and checkout entry;
-checkout opens with a fresh controller/lookup, or call `reload` if retaining its
-controller. Route supported caller scope/reference changes through `setInput`.
-Do not use descriptor `onAppear` as a reliable iOS return callback: retained
-screens do not necessarily remount. Prices and derived fields must be excluded
-from persisted worker hydration, as above, on hosts supporting `notHydrated`.
-
-Every new lookup clears the amount immediately. A failed periodic/background
-refresh shows unavailable with Retry rather than keeping a prior amount as freshly
-confirmed. Overlapping entry, poll, checkout, and Retry requests join matching
-in-flight work. No polling continues while the iOS host has pooled/backgrounded
-the worker.
-
-No Storefront update bridge is implemented in this slice. Supported invalidations
-refresh prices; a storefront change while visible may remain undetected until the
-next poll or explicit refresh. This does not establish immediate storefront
-notification. Native `Storefront.updates` remains a separate follow-up.
-
-Price metadata is not purchase authorization or entitlement. A future activated
-checkout must compare its purchase context's Apple product ID with the displayed
-ready state; if they differ, refresh mapping/price and show the new amount before
-allowing purchase. The existing purchase coordinator remains unchanged, and this
-preview never invokes it. Mapping fixtures and their failure scenarios belong only
-in the local demonstration. Production mapping, checkout activation, and template
-migration are still required before rollout.
-
-The dedicated iOS LiftGear QA binary opts into the existing managed transaction
-API before shared capability registration. Its native identity requires both
-`com.alexchudnovsky.liftgear` and baked app
-`alexanderch3.fit-gear-2-push-test`; the tenant is `liftgear-sandbox-lab`.
-This opt-in cannot be selected by worker input, member identity, or OTA content.
-Other Branded Lite identities retain their existing registration behavior.
-For this dedicated QA identity, a pinned baked config with the
-`liftgear-pricing` scheme and a pricing-card home supplies the navigation menu
-and initial screen. This keeps the embedded demonstration visible after an
-update over an existing LiftGear installation or a live config refresh, without
-changing stored member data or managed purchase policy. Ordinary or incomplete
-baked configs continue to use the cached navigation. This is a bounded preview
-host rule, not a general fix for distribution release routing.
-The separate, explicitly armed purchase demonstration calls
-`purchaseForVerification` with a labelled synthetic association, reports Apple's
-actual transaction environment, and leaves the transaction unfinished. It has
-no transaction-server integration or program-access delivery. Pricing alone
-does not arm the demonstration or start a purchase.
+Bind the fields in the screen descriptor and declare both capabilities the worker calls. To show
+real App Store prices, the app must also grant `iap` (and `app_info`) in its `config.ts`
+`capabilities`, so its native shell registers the store bridge; until it does, the screen fails
+closed to "Price unavailable" rather than showing a price it could not confirm.
+
+```json
+{
+  "logicBundle": { "declaredCapabilities": ["iap", "app_info"] },
+  "price":   { "type": "Text",   "props": { "text": "$service:course.priceText", "collapseWhenEmpty": true } },
+  "note":    { "type": "Text",   "props": { "text": "$service:course.priceNote", "collapseWhenEmpty": true } },
+  "retry":   { "type": "Button", "props": { "title": "Try again", "action": { "actionId": "tier5.course.refreshPrice" } },
+               "modifiers": { "hiddenPath": "$service:course.hidePriceRetry" } },
+  "buy":     { "type": "Button", "props": { "title": "Enrol", "disabledPath": "$service:course.buyDisabled",
+               "action": { "actionId": "tier5.course.buy" } } },
+  "buyNote": { "type": "Text",   "props": { "text": "$service:course.buyNote", "collapseWhenEmpty": true } }
+}
+```
+
+## Rules
+
+- **One pricing instance per worker, one `load` per set of visible items.** Pass every item the
+  screen shows in a single call; the layer batches the lookup and fetches each Apple product once.
+- **Guard the action, not only the button.** Call `checkoutGuard` immediately before a commerce flow
+  starts; actions can run without a tap. Before each later step of a flow that already started (a
+  payment after a join or reservation), call `continueCheckoutGuard`: it lets the step through on the
+  route the last lookup settled, so a routine refresh cannot strand the flow halfway, and stops it
+  once a refresh settles on an App Store route. If the flow pays through `payOrder` from
+  `@wix/himalaya/checkout`, pass the same check as `mayCharge`; it runs again right before the wallet
+  charges and before the hosted cashier opens.
+- **One writer.** Publish through a synchronous action that reads `pricing.view` at that moment.
+  An async action that returns its own state can land after a newer price and repaint a stale one.
+- **No timers.** `pollDirective` asks the app to refresh every 60 seconds while the screen is
+  visible and on return to it. Point it and Retry at an action that reads the host and calls `load`
+  again, so a failed identity read recovers; `refresh` replays the last scope unchanged. Every
+  lookup clears the old price first.
+- **Keep prices out of hydration** with `notHydrated`, so a cold start never shows an old amount.
+- **Content first.** A pricing failure is per item. Never replace the screen with an error because a
+  price could not load.
+- **iOS only.** On Android, web and macOS, App Store routes come back `unavailable`. Regular
+  routes are unaffected.
+
+## Adopting it
+
+- **Starter templates with Online Programs** (`branded-lite`, `yoga-studio`) already include it on
+  their Programs list and program screens.
+- **Existing screens, including apps created from a template before this existed:** an SDK update
+  never changes a screen that does not call this layer. Add the worker calls, the bindings and the
+  two capabilities above. After that, screens pick up layer fixes on their next build.
+- **Custom screens:** follow the worker above for any item you sell, whatever its vertical.
+- **New item types:** use the kind `himi store iap` registers for it, build `{ kind, id }`, and call
+  the same layer. Never write your own mapping lookup, App Store price request or payment guard.
+
+## What turns it on
+
+Register your digital products with `himi store iap` (see `himi docs iap-products`). When Wix
+connects the mapping service those registrations feed, screens that use this layer start showing
+App Store prices on their next build — in an app that grants the `iap` capability in `config.ts`.
+Screens that do not use the layer are unaffected.

package/guides/index.json

@@ -20,6 +20,7 @@
   ],
   "guardrails": [
     "Prefer Tier-5 (SDUI descriptor + JS worker) over native screens — reach for native only when SDUI genuinely can't express it.",
+    "A screen that shows or sells an item that may be an App Store in-app purchase (a program, product or plan — template or custom screen alike) uses the shared layer `createIapCatalogPricing` from `@himalaya/iap` (`himi docs iap-pricing`): it batches the mapping lookup, fetches Apple prices and decides the payment route. Never hand-wire a mapping, an Apple price request or a payment guard in a worker. Call `checkoutGuard` immediately before a commerce flow starts, and `continueCheckoutGuard` before each later step of a flow already under way (a payment after a join), so a routine price refresh cannot strand it halfway. It is off until Wix connects the mapping service, and Apple purchasing is not available yet.",
     "Keep structure descriptor-authored: use FragmentSlot for enumerable variants and bound list/grid templates for repetition. Use WorkerSubtree only for runtime-unknowable structure, with an explicit screen allowlist, policy budgets, and shipped fallback.",
     "Bindings ($service:<svc>.<path>, $item.<field>, $flag:<key>) are plain strings in ANY prop — INCLUDING Modifiers token refs (background, color, tint), so a worker can drive per-item theming, not just text. They CANNOT target strict-enum fields (style, size, alignment, severity, presentation, …) — those fail at render, not validation.",
     "Workers are sandboxed: no DOM, no timers, no raw fetch. Produce state synchronously in actions; do not rely on an ambient refresh tick.",
@@ -178,12 +179,6 @@
       "category": "Workers & SDKs",
       "file": "capabilities.md"
     },
-    {
-      "id": "iap-pricing",
-      "title": "Apple IAP pricing in a worker",
-      "category": "Workers & SDKs",
-      "file": "iap-pricing.md"
-    },
     {
       "id": "wix-api-usage",
       "title": "Call Wix APIs from a worker",
@@ -327,6 +322,12 @@
       "title": "Registering digital products as App Store in-app purchases",
       "category": "CLI & Loop",
       "file": "iap-products.md"
+    },
+    {
+      "id": "iap-pricing",
+      "title": "Showing App Store prices on any screen",
+      "category": "Workers & SDKs",
+      "file": "iap-pricing.md"
     }
   ],
   "componentReferenceFile": "component-reference.json",

package/guides/sdk-reference.json

@@ -1777,6 +1777,102 @@
         "jsdoc": "/** Creates one worker's read-only pricing controller with injected mapping, store lookup, and state publication. */",
         "decl": "export function createPricingController(deps: PricingDependencies): PricingController;"
       },
+      {
+        "name": "IAP_CATALOG_KINDS",
+        "kind": "const",
+        "jsdoc": "/** The Wix entity types `himi store iap` writes into its Wix→Apple mapping, so a mapping\n *  backend can serve that export without translating kinds. */",
+        "decl": "export const IAP_CATALOG_KINDS = [\"onlineProgram\", \"storesProduct\", \"pricingPlan\"] as const;"
+      },
+      {
+        "name": "IapCatalogKind",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type IapCatalogKind = typeof IAP_CATALOG_KINDS[number];"
+      },
+      {
+        "name": "IapCatalogItem",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogItem {\n  reference: CatalogReference;\n  /** The screen's own formatted commerce price; shown only on an explicit regular route. */\n  commerceDisplayPrice?: string;\n}"
+      },
+      {
+        "name": "IapCatalogScope",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogScope {\n  appId: string;\n  bundleId: string;\n  /** Wix metaSiteId. Omit it to use the connected mapping source's bound site. */\n  siteId?: string;\n  contextRevision?: string;\n}"
+      },
+      {
+        "name": "IapCatalogInput",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogInput {\n  scope: IapCatalogScope;\n  /** The host's own platform (from `@himalaya/app-info`); only \"ios\" resolves Apple prices. */\n  platform: string;\n  items: IapCatalogItem[];\n}"
+      },
+      {
+        "name": "IapPaymentRoute",
+        "kind": "type",
+        "jsdoc": "/** `disabled` means no backend is connected: the screen's existing commerce behavior applies. */",
+        "decl": "export type IapPaymentRoute = \"disabled\" | \"regular\" | \"appleIap\" | \"resolving\" | \"unavailable\";"
+      },
+      {
+        "name": "IapItemView",
+        "kind": "interface",
+        "jsdoc": "/** Serializable per-item state a screen binds. Carries no credential, transaction or entitlement. */",
+        "decl": "export interface IapItemView {\n  reference: CatalogReference;\n  route: IapPaymentRoute;\n  /** Apple: StoreKit's string verbatim. Regular: the caller's commerce price. Otherwise \"\". */\n  displayPrice: string;\n  reason?: PricingUnavailableReason;\n  retryable: boolean;\n  /** True only when the existing commerce checkout may run: disabled or an explicit regular route. */\n  canStartRegularCheckout: boolean;\n  /** Apple purchasing is not available until a backend verifies transactions. */\n  purchasable: false;\n}"
+      },
+      {
+        "name": "IapCheckoutDecision",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCheckoutDecision {\n  allowed: boolean;\n  route: IapPaymentRoute;\n}"
+      },
+      {
+        "name": "IapMappingSource",
+        "kind": "interface",
+        "jsdoc": "/** A deployed Wix→Apple mapping backend. Never supplied by a screen. */",
+        "decl": "export interface IapMappingSource {\n  mapping: PricingMappingProvider;\n  /** The site this backend serves, used when the caller passes no site. */\n  siteId?: string;\n}"
+      },
+      {
+        "name": "IapPollDirective",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapPollDirective {\n  id: string;\n  action: string;\n  intervalMs: number;\n  immediate: boolean;\n}"
+      },
+      {
+        "name": "IapCatalogPricing",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapCatalogPricing {\n  readonly enabled: boolean;\n  /** Batched mapping + Apple lookup for the items a screen shows. */\n  load(input: IapCatalogInput): Promise<void>;\n  refresh(): Promise<void>;\n  view(reference: CatalogReference): IapItemView;\n  /** May a commerce flow START now? Re-read immediately before the first mutation: the route as it\n   *  is now, so a refresh in flight (`resolving`) blocks. */\n  checkoutGuard(reference: CatalogReference): IapCheckoutDecision;\n  /** May a flow that already STARTED take its next commerce step (e.g. pay after a join)? While no\n   *  new answer exists (a refresh in flight, or a mapping backend that did not answer) it uses the\n   *  route the last settled lookup gave for the current scope, so a routine refresh cannot strand a\n   *  regular checkout halfway; any new answer other than regular stops it. */\n  continueCheckoutGuard(reference: CatalogReference): IapCheckoutDecision;\n  /** The host-scheduled visible refresh; undefined while disabled. */\n  pollDirective(action: string): IapPollDirective | undefined;\n  dispose(): void;\n}"
+      },
+      {
+        "name": "IapPriceCopy",
+        "kind": "interface",
+        "jsdoc": "/** Labels come from the screen's copy pack; the shared layer only chooses between them. */",
+        "decl": "export interface IapPriceCopy {\n  loading: string;\n  unavailable: string;\n  oneTimePurchase: string;\n  purchaseUnavailable: string;\n}"
+      },
+      {
+        "name": "IapPriceFields",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface IapPriceFields {\n  priceText: string;\n  priceNote: string;\n  priceLoading: boolean;\n  hidePriceRetry: boolean;\n  actionDisabled: boolean;\n  actionNote: string;\n}"
+      },
+      {
+        "name": "createIapCatalogPricing",
+        "kind": "function",
+        "jsdoc": "/** One screen worker's catalog pricing. Activation comes only from the connected mapping\n *  source, so a screen cannot turn Apple prices on by supplying its own mapping. */",
+        "decl": "export function createIapCatalogPricing(options: { onChange?(): void } = {}): IapCatalogPricing;"
+      },
+      {
+        "name": "iapPriceFields",
+        "kind": "function",
+        "jsdoc": "/** Bindable display state for one item. A screen spreads these into its own state and binds\n *  them; the labels stay in the screen's copy pack. */",
+        "decl": "export function iapPriceFields(view: IapItemView, copy: IapPriceCopy): IapPriceFields;"
+      },
+      {
+        "name": "onlineProgramItem",
+        "kind": "function",
+        "jsdoc": "/** An Online Programs program as a shared IAP catalog item. A program without a Wix ID cannot be\n *  mapped (a title fallback is not an identity), so it has no item and its screen shows no price. */",
+        "decl": "export function onlineProgramItem(program: { id?: string | null }, commerceDisplayPrice?: string): IapCatalogItem | undefined;"
+      },
       {
         "name": "ProductType",
         "kind": "type",

package/guides/tier-5-add-a-screen.md

@@ -479,6 +479,15 @@ This is what makes the fail-closed capability gates readable. `local_database: e
 "X" is not declared in the app's dataSchema` is a message written to be read — before
 #2288 an author only ever saw an eternal spinner.
 
+### Show App Store prices for catalog items
+
+A screen that shows or sells a program, product or plan that may be an App Store in-app purchase
+does not look up mappings or Apple prices itself. It uses the shared catalog layer
+(`createIapCatalogPricing` in `@himalaya/iap`), which also hands it the `_poll` directive below and
+the guards a commerce flow must call: `checkoutGuard` before it starts, `continueCheckoutGuard`
+before each later step. The adoption guide, with a compiled and tested
+worker example, is `himi docs iap-pricing` ([iap-pricing-for-screens.md](iap-pricing-for-screens.md)).
+
 ### Refresh on a cadence with `_poll` (the worker has no clock)
 
 A worker is a pure reducer with **no `setTimeout` and no `setInterval`** — its sandbox

package/guides/wix-api-usage.md

@@ -281,6 +281,17 @@ If a record genuinely carries no currency, fall back to a constant your app owns
 site-properties read that will 403. An owner-scope app (a dashboard/owner surface holding a `User`
 instance) *can* read the site currency; a consumer/visitor app cannot.
 
+### Items that may be sold as App Store in-app purchases
+
+A program, product or plan the owner registered with `himi store iap` may have to be sold through
+the App Store instead of your commerce flow. Do not decide that in your worker. Pass the items on
+screen to the shared `createIapCatalogPricing` from `@himalaya/iap` (`himi docs iap-pricing`): it
+looks up each item's route in one batch, fetches Apple's localized price, and returns what to show
+and whether your existing checkout may run. Bind its fields, call `checkoutGuard` right before a
+commerce flow starts and `continueCheckoutGuard` before each later step of it, and declare `iap` and
+`app_info`. While Wix has not connected the mapping service
+it reports `disabled` and your screen behaves exactly as before.
+
 ## Testing
 
 Fake the bridge — stub `globalThis.himalaya.wixApi.call` to return a canned parsed object per `(method, path)` — or use

package/guides/wix-site-to-himi-app.md

@@ -124,7 +124,7 @@ for **behavior** is the website; design authority for **layout** is
 
 | Website | Mobile |
 |---|---|
-| Vertical (book, shop, events, forum, members, blog) | Template/overlay screen; bind with `himi sdk` + live `@himalaya/wix-*` |
+| Vertical (book, shop, events, forum, members, blog) | Template/overlay screen; bind with `himi sdk` + live `@himalaya/wix-*`. Any screen showing a digital item's price (program, product, plan) also uses the shared IAP pricing layer — `himi docs iap-pricing` — whether it came from a template or you wrote it |
 | Custom content / CMS / forms | One T5 screen per *job*; data = adopted CMS (`wixId`) or a form worker (`himi docs recipe-form-submit`) |
 | Velo page modules | Briefing only: field names, collection ids, submit flow. **Rewrite** as a worker. Never copy Velo JS. Site HTTP functions (`/_functions/`) are a separate API: `himi docs wix-site-http-functions` / `himi site function` — analyze never invokes them |
 | Lightboxes, popups, multi-column editors | Push screen or sheet — not a ported lightbox |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1243.0",
+  "version": "0.1245.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "7334685c40352434e2281db8d3506edef751ff4142ca450fc5c38c3d"
+  "falconPackageHash": "09f05672ac223575259bf3c6b41d9dbdb7ad92bd5de82076c956864c"
 }

package/templates/beauty-salon-owner/dev/index.ts

@@ -52293,7 +52293,7 @@ const SCREENS = runtimeSetting({
                 "package": "himalaya",
                 "type": "Button",
                 "props": {
-                  "title": "Sign out",
+                  "title": "Sign out of Wix",
                   "style": "secondary",
                   "fullWidth": true,
                   "action": {