@wix/himalaya-cli 0.1320.0 → 0.1321.0

package/guides/iap-pricing.md

@@ -6,9 +6,11 @@ displays or sells: a program, a product, a plan, or anything else you registered
 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.
 
-> **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.
+> **On for bound apps only.** The mapping is read from the app's purchases catalog, which
+> `himi store iap connect` sets up. An app with no purchases-app binding reads every item as
+> `disabled` and keeps its existing price and checkout. This page shows prices and blocks the wrong
+> checkout; selling an App Store item is the shared checkout's job (`createIapCommerce` +
+> `commerce.purchaseFields`, [Wix Apple-IAP checkout](iap-wix-checkout.md#using-it-from-a-screen)).
 > Only one-time purchases (non-consumables) are supported. Subscriptions and consumables are not.
 
 ## What you get per item
@@ -20,7 +22,7 @@ what to do:
 |---|---|---|
 | `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 |
+| `appleIap` | `displayPrice` exactly as Apple formats it, plus a "One-time purchase" note | Blocked; the shared checkout sells it |
 | `regular` | `displayPrice` (the commerce price you passed), or nothing | Allowed |
 | `unavailable` | "Price unavailable", plus Retry when `retryable` | Blocked |
 
@@ -34,10 +36,9 @@ does not mean the item is free. Only an explicit `regular` route keeps your exis
 returns `null` for any other route. It is for a checkout to compare with the product it is asked to
 sell. Do not put it in screen state.
 
-> **Buying is not switched on.** `@wix/himalaya/iap-checkout` is a shared App Store checkout,
-> `createAppleIapCheckout`, built on this layer. It answers `notEnabled` and makes no call until Wix
-> enables it, so keep App Store items blocked as described above. Never build your own purchase
-> flow for them.
+> **Buy through the shared checkout only.** `@wix/himalaya/iap-checkout` (`createIapCommerce`) is
+> the App Store checkout built on this layer, and it sells only in a bound app. Keep App Store items
+> blocked in your own checkout as described above. Never build your own purchase flow for them.
 
 ## Catalog references
 
@@ -52,13 +53,16 @@ when it registers the item with Apple:
 
 ## Add it to a worker
 
-This is a complete worker for one screen. Copy the pattern, not the course names.
+This is a complete worker for one screen that shows an App Store price and guards its existing
+checkout. Copy the pattern, not the course names. A screen that also SELLS the item passes its
+vertical adapter to `createIapCommerce` and binds Get access with `commerce.purchaseFields` instead of
+blocking ([checkout recipe](iap-wix-checkout.md#using-it-from-a-screen)).
 
 ```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";
+import { iapPriceFields, onlineProgramItem } from "@himalaya/iap";
+import { createIapCommerce } from "@himalaya/iap-checkout";
 
 const COPY = {
   loading: "Loading price…",
@@ -74,25 +78,25 @@ 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(); } });
+  // No adapters: this screen shows the price and keeps its own checkout. `commerce.pricing` is the
+  // shared `createIapCatalogPricing` layer; the host scopes its lookup (app identity, platform, and
+  // the app's purchases-app site when it has one).
+  const commerce = createIapCommerce({ onChange: () => { void service.publish(); } });
+  const pricing = commerce.pricing;
   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 ?? "" };
-  }
-
   async function loadPrices() {
-    if (pricing.enabled) await pricing.load({ ...(await hostScope()), items: [item] });
+    if (pricing.enabled) scopeIncomplete = !(await commerce.loadPrices([item])).scopeComplete;
     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);
+    const view = pricing.view(item.reference);
+    // `disabled`: no source, or an app that sells nothing through the App Store — the screen's own price.
+    if (view.route === "disabled") return { ...state, priceText: course.commercePrice, buyDisabled: false, message };
+    const price = iapPriceFields(view, COPY);
     return { ...state, priceText: price.priceText, priceNote: price.priceNote, hidePriceRetry: price.hidePriceRetry && !scopeIncomplete,
       buyDisabled: price.actionDisabled, buyNote: price.actionNote, message };
   }
@@ -125,14 +129,14 @@ export function registerCourseScreen(course: Course, startCheckout: () => Promis
 }
 ```
 
-Bind the fields in the screen descriptor and declare both capabilities the worker calls. To show
+Bind the fields in the screen descriptor and declare the 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"] },
+  "logicBundle": { "declaredCapabilities": ["iap", "app_info", "wix_api"] },
   "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" } },
@@ -163,8 +167,9 @@ closed to "Price unavailable" rather than showing a price it could not confirm.
 - **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.
+- **iOS only.** Android, web and macOS binaries carry no purchases-app binding, so the shipped
+  source reads every item there as `disabled` and the screen's own price and checkout apply. A
+  mapping that does name an App Store product on those hosts comes back `unavailable`.
 
 ## Adopting it
 
@@ -173,7 +178,9 @@ closed to "Price unavailable" rather than showing a price it could not confirm.
 - **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.
+- **Custom screens:** follow the worker above for any item you price, and the
+  [checkout recipe](iap-wix-checkout.md#using-it-from-a-screen) 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.
 

package/guides/index.json

@@ -20,7 +20,8 @@
   ],
   "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.",
+    "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.",
+    "To SELL an App Store item, a screen composes `createIapCommerce` from `@himalaya/iap-checkout` once per worker (its catalog pricing plus the shared checkout, with the vertical's order adapter) and binds its Get access action with `commerce.purchaseFields`: the order, Apple's sheet, proof delivery, finishing and the access read all happen inside it. Never call StoreKit (`purchaseForVerification`), `finishTransaction` or the payment client from a worker, never fall back to Wix checkout for an App Store item, and show access only when it reports `accessReady`. Purchasing stays unavailable until Wix provides its routes and mapping.",
     "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.",

package/guides/sdk-reference.json

@@ -432,8 +432,8 @@
       {
         "name": "BiometricKind",
         "kind": "type",
-        "jsdoc": "",
-        "decl": "export type BiometricKind = \"face\" | \"fingerprint\" | \"iris\" | \"none\";"
+        "jsdoc": "/**\n * The enrolled biometric, as far as the platform can tell:\n * - `\"face\"` / `\"fingerprint\"` / `\"iris\"` — that modality.\n * - `\"biometric\"` — a biometric is enrolled but the platform can't say which\n *   (Android phones with both face and fingerprint hardware; the web). Label\n *   the unlock neutrally (\"Use biometrics\") rather than guessing a modality.\n * - `\"none\"` — nothing enrolled, or no hardware.\n *\n * Additive: treat any value you don't recognise like `\"biometric\"`.\n */",
+        "decl": "export type BiometricKind = \"face\" | \"fingerprint\" | \"iris\" | \"biometric\" | \"none\";"
       },
       {
         "name": "available",
@@ -1878,7 +1878,7 @@
         "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}"
+        "decl": "export interface IapMappingSource {\n  mapping: PricingMappingProvider;\n  /** Whether this app sells through the App Store at all — the binary carries a purchases-app binding.\n   *  When it answers false, every item reads `disabled` with no lookup, exactly as with no source, so the\n   *  screen's own commerce applies; asked again on every load. Absent means always active. */\n  active?(): Promise<boolean>;\n  /** The site this backend serves, used when the caller passes no site. */\n  siteId?: string;\n}"
       },
       {
         "name": "IapPollDirective",
@@ -2065,7 +2065,7 @@
       {
         "name": "createWixIapClient",
         "kind": "function",
-        "jsdoc": "/**\n * Creates a client for Wix's in-app-purchase payments service (`mobile-apps-wix-iap`), which pays\n * a Wix order with a store purchase the member makes in the app.\n *\n * NOT ENABLED and not production-ready. No app wires it, and no call reaches the service: it has\n * no public gateway route yet, so `route` must be supplied and there is no default. It calls\n * StartPayment (`POST …/payments/start`), CompletePayment (`POST …/payments/complete`)\n * and GetPayment (`GET …/payments/{id}`) through the\n * `wix_api` bridge. A matched or approved Payment is not durable access and never finishes the\n * store transaction.\n *\n * Production use stays blocked: there is no public route or member authorization on the service,\n * no trusted app-binding source, and checkout stays disabled. When this client uses the host\n * bridge, it also requires the host's identity clock and passes that captured expectation\n * through the bridge. An injected transport keeps the previous call shape unless the session\n * itself exposes an identity.\n */",
+        "jsdoc": "/**\n * Creates a client for Wix's in-app-purchase payments service (`mobile-apps-wix-iap`), which pays\n * a Wix order with a store purchase the member makes in the app.\n *\n * The shared checkout (`createIapCommerce`) builds it with Serve's IAP route for an app whose binary\n * carries a purchases-app binding; `route` stays a parameter with no default. It calls\n * StartPayment (`POST …/payments/start`), CompletePayment (`POST …/payments/complete`)\n * and GetPayment (`GET …/payments/{id}`) through the\n * `wix_api` bridge. A matched or approved Payment is not durable access and never finishes the\n * store transaction.\n *\n * A sale needs the binding baked into the binary and an active mapping for the item; without them\n * nothing is offered, and before a production Serve release carries the IAP routes the mapping read\n * fails, so nothing is offered either. When this client uses the host\n * bridge, it also requires the host's identity clock and passes that captured expectation\n * through the bridge. An injected transport keeps the previous call shape unless the session\n * itself exposes an identity.\n */",
         "decl": "export function createWixIapClient(deps: WixIapClientDependencies): WixIapClient;",
         "verified": false
       },
@@ -2079,7 +2079,7 @@
         "name": "HostIdentitySource",
         "kind": "interface",
         "jsdoc": "/** A session provider that can also name the principal captured for one generation. */",
-        "decl": "export interface HostIdentitySource {\n  readonly identityBound: boolean;\n  identity(session: SessionSnapshot): HostCallExpectation | null;\n}"
+        "decl": "export interface HostIdentitySource {\n  readonly identityBound: boolean;\n  identity(session: SessionSnapshot): HostCallExpectation | null;\n  /** The site the native bridge fences protected calls to, from the latest ready snapshot. Null\n   *  when the host installed no session source: iOS publishes the bridge (`identityBound`) to\n   *  every worker that has `wix_api`, with or without one. */\n  site(): string | null;\n}"
       },
       {
         "name": "HostSessionProvider",
@@ -2248,6 +2248,18 @@
         "kind": "const",
         "jsdoc": "/** The managed native verbs as the delivery coordinator's store. */",
         "decl": "export const appleManagedStore: TransactionStore = { purchaseForVerification, getUnfinishedTransactions, finishTransaction };"
+      },
+      {
+        "name": "hostAppBindingSource",
+        "kind": "function",
+        "jsdoc": "/** The purchases-service binding the host baked into this binary at build time (the app's build\n *  contract → Info.plist), checked natively against the running bundle, app and site. Never read\n *  from a screen, OTA config or navigation param: a worker cannot choose which purchases app it\n *  sells through. Null means not provisioned: an unbound build, an older binary without the verb,\n *  or a platform with no managed App Store purchasing. A host that has the verb and fails to answer\n *  proves neither, so that read rejects and is not kept: the caller must not fall back to the\n *  unbound app's commerce. The binding cannot change while the process runs, so a source asks the\n *  host once. */",
+        "decl": "export function hostAppBindingSource(): AppBindingSource;"
+      },
+      {
+        "name": "sharedHostAppBindingSource",
+        "kind": "function",
+        "jsdoc": "/** One binding source per worker, shared by pricing and checkout, so one screen never acts on two\n *  different answers to the same question. */",
+        "decl": "export function sharedHostAppBindingSource(): AppBindingSource;"
       }
     ]
   },

package/guides/tokens.md

@@ -18,7 +18,7 @@ one registry, mirrored byte-for-byte by the iOS + Android decoders.
 | `motions` | name → { duration, easing?, spring? } | optional |
 | `materials` | name → { style, tint?, opacity?, blur? } | optional |
 | `tabBar` / `drawer` / `sidebar` | nav-chrome style blocks | optional |
-| `kit` | { material?, variant?, density?, motion? } | optional — the active design kit |
+| `kit` | { material?, variant?, density?, motion?, reduceMotion?, colorScheme? } | optional — the active design kit |
 | `contentMaxWidth` | { base, medium?, expanded? } | optional |
 | `elevations` | name → { level?, tint?, shadow?, border? } | optional — a Card wears `card` |
 | `controls` | { button?: { sm?, md?, lg?, variants? } } | optional — every Button's size and paint |
@@ -39,6 +39,27 @@ platform's own UI face — SF Pro on iOS/macOS, Roboto on Android, the system UI
 A color is a hex string, OR a per-scheme object `{ light, dark?, highContrast? }`. In the
 object form **`light` is required**; `dark`/`highContrast` fall back to it.
 
+## Light or dark — `kit.colorScheme`
+
+By default an app follows the device appearance. To pin it, set `kit.colorScheme` — it ships
+OTA with the tokens, so a published release re-skins installed apps without a new binary:
+
+| value | effect |
+|---|---|
+| `"system"` (or absent) | follow the device light/dark setting |
+| `"light"` | always light |
+| `"dark"` | always dark |
+
+Only those three lowercase values are recognised: another string counts as `"system"` and
+`himi validate` warns; a non-string (a number, a boolean) is an error, because it fails the
+whole tokens.json on device. The pin replaces only the device light/dark signal: an explicit
+in-app theme choice (`theme.set`, a host's own Appearance setting), a preview's scheme pin,
+and the OS high-contrast setting still win over it. Native chrome — the status bar and the
+navigation bar — follows the pin too. Binaries older than the core release that added it
+ignore the key and keep following the device. Set it in the top-level `kit` block (an idiom
+overlay cannot change it), merged into the existing block rather than replacing it; adopting a
+design kit keeps it.
+
 ## Motion
 
 `easing` is `linear`, `easeIn`, `easeOut`, `easeInOut`, `spring` or `emphasized` (Material 3's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1320.0",
+  "version": "0.1321.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": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "551309f221b2f15b7f02099f9470e8021a0e0de81fba7b30dea7434b"
+  "falconPackageHash": "3318113ec10ae018bbbe09e99bb3bef1207460516f9ca12d20e128ff"
 }

package/templates/branded-lite/dev/index.ts

@@ -85162,6 +85162,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                             "actionId": "tier5.himiBrandedProgram.enroll"
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.enrollHidden"
                       }
                     },
                     {
@@ -85175,6 +85178,44 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                           "color": "textSecondary",
                           "collapseWhenEmpty": true
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.enrollHidden"
+                      }
+                    },
+                    {
+                      "id": "himi_program.buy",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Button",
+                        "props": {
+                          "title": "$service:himiBrandedProgram.buyLabel",
+                          "style": "primary",
+                          "fullWidth": true,
+                          "disabledPath": "$service:himiBrandedProgram.buyDisabled",
+                          "action": {
+                            "actionId": "tier5.himiBrandedProgram.buy"
+                          }
+                        }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.buyHidden"
+                      }
+                    },
+                    {
+                      "id": "himi_program.buy_note",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "$service:himiBrandedProgram.buyNote",
+                          "style": "footnote",
+                          "color": "textSecondary",
+                          "collapseWhenEmpty": true
+                        }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.buyHidden"
                       }
                     },
                     {

package/templates/branded-lite/tier5-src/_shared/iap-worker.ts

@@ -1,49 +1,11 @@
-// Worker-side glue for the shared IAP catalog layer (`@himalaya/iap` → createIapCatalogPricing),
-// shared by every screen that shows or sells an IAP-backed item. Mapping, Apple prices and payment
-// guards live in the SDK; this only supplies the host scope, the copy, and the hydration reset.
-import { get as appInfo } from "@himalaya/app-info";
-import type { IapCatalogScope, IapPriceCopy } from "@himalaya/iap";
+// Worker-side glue for the shared IAP layer (`@himalaya/iap` catalog pricing and
+// `@himalaya/iap-checkout` → createIapCommerce), shared by every screen that shows or sells an
+// IAP-backed item. Mapping, Apple prices, payment guards, the host scope and the sale live in the
+// SDK; this only supplies the copy and the hydration reset.
+import type { IapPriceCopy } from "@himalaya/iap";
+import type { IapPurchaseCopy } from "@himalaya/iap-checkout";
 import { copyParam } from "./himi-copy.js";
 
-export interface HostIapScope {
-  scope: IapCatalogScope;
-  platform: string;
-}
-
-let hostScope: Promise<HostIapScope> | undefined;
-
-/** Read once per worker, and only by an enabled screen: a disabled one makes no app-info call.
- *  App identity and platform come from the host, never a screen param. The site is the host-owned
- *  native preference business (the web partition uses an OAuth client ID); without one, the mapping source's
- *  bound site applies. A failed read leaves identity empty, which fails every item closed — and is
- *  not kept, so the next lookup asks the host again instead of staying invalid for good. */
-export function hostIapScope(): Promise<HostIapScope> {
-  return hostScope ??= readHostScope().then((read) => {
-    if (!hostScopeComplete(read)) hostScope = undefined;
-    return read;
-  });
-}
-
-/** An incomplete scope prices every item `invalidInput`, which the shared layer never offers to
- *  retry — so a screen offers Retry itself while its own host read is what failed. */
-export function hostScopeComplete(read: HostIapScope): boolean {
-  return !!read.scope.appId && !!read.scope.bundleId && !!read.platform;
-}
-
-async function readHostScope(): Promise<HostIapScope> {
-  const identity = await appInfo().catch(() => undefined);
-  const siteId = identity?.platform === "web" ? "" : hostSiteId();
-  return {
-    scope: { appId: identity?.appId ?? "", bundleId: identity?.bundleId ?? "", ...(siteId ? { siteId } : {}) },
-    platform: identity?.platform ?? "",
-  };
-}
-
-function hostSiteId(): string {
-  const value = (globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input?.__himiPreferenceBusiness;
-  return typeof value === "string" ? value.trim() : "";
-}
-
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
 export function iapPriceCopy(prefix: string): IapPriceCopy {
   return {
@@ -54,6 +16,21 @@ export function iapPriceCopy(prefix: string): IapPriceCopy {
   };
 }
 
+/** App Store purchase labels from the screen's copy pack (`<prefix>.buyCta`, …), for
+ *  `iapPurchaseFields`. Customer copy only: no backend names, ids or diagnostics. */
+export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
+  return {
+    buy: copyParam(`${prefix}.buyCta`, "Get access"),
+    processing: copyParam(`${prefix}.purchaseProcessingText`, "Processing your purchase…"),
+    awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
+    unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
+    signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    retry: copyParam(`${prefix}.purchaseRetryText`, "Something went wrong. Try again."),
+    priceChanged: copyParam(`${prefix}.purchasePriceChangedText`, "The price changed. Check it and try again."),
+    support: copyParam(`${prefix}.purchaseSupportText`, "We couldn't finish this purchase. Contact support."),
+  };
+}
+
 /** What `notHydrated` does, for a runtime that ignores the option (a binary older than it, still
  *  served new bundles): put the listed keys back to their declared values before any action runs,
  *  so a persisted price or an enabled purchase action never paints as this run's. */

package/templates/branded-lite/tier5-src/himi-branded-lite-program/index.ts

@@ -14,8 +14,11 @@
 // back APPROVAL_PENDING (the owner approves; there is nothing to charge). Any failure
 // degrades to the site-directing message rather than a dead button.
 //
-// App Store prices and the payment route come from the shared IAP catalog layer (@himalaya/iap).
-// Until a mapping backend is connected it is disabled, and this worker runs its pre-pricing path.
+// App Store prices, the payment route and the App Store sale come from the shared IAP layer
+// (`createIapCommerce` in @himalaya/iap-checkout). An app that sells nothing through the App Store
+// reads every program as `disabled` and keeps Enrol on its own commerce. An Apple-routed program
+// offers Get access in place of Enrol and sells only through the shared checkout, never through the
+// Wix payment rail.
 import { defineService } from "@himalaya/state";
 import {
   getProgram,
@@ -31,8 +34,9 @@ import { cleanTitle, initials } from "../_shared/himi-text.js";
 import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
 import { payCashierOrder } from "@himalaya/checkout";
 import { formatCurrency } from "../_shared/engine-intl.js";
-import { createIapCatalogPricing, iapPriceFields, onlineProgramItem, type IapCatalogItem, type IapPollDirective, type IapPriceFields } from "@himalaya/iap";
-import { hostIapScope, hostScopeComplete, iapPriceCopy, resetUnhydratedKeysOnOlderRuntime } from "../_shared/iap-worker.js";
+import { iapPriceFields, onlineProgramItem, type IapCatalogItem, type IapPollDirective, type IapPriceFields } from "@himalaya/iap";
+import { createIapCommerce, onlineProgramOrders, type IapPurchaseFields } from "@himalaya/iap-checkout";
+import { iapPriceCopy, iapPurchaseCopy, resetUnhydratedKeysOnOlderRuntime } from "../_shared/iap-worker.js";
 
 /** Wix Online Programs appDefId — the vertical a participant's cashier order is
  *  paid under (mirrors AppDefId.CHALLENGES in Wix's RN apps). */
@@ -66,6 +70,13 @@ interface State {
   /** Bound to the Enrol CTA's `disabledPath`; `enroll` re-checks the route itself regardless. */
   enrollDisabled: boolean;
   enrollNote: string;
+  /** An App Store program sells through Get access instead. */
+  enrollHidden: boolean;
+  /** The shared checkout's action (`commerce.purchaseFields`): shown only on the App Store route. */
+  buyHidden: boolean;
+  buyLabel: string;
+  buyDisabled: boolean;
+  buyNote: string;
   _poll?: IapPollDirective;
 }
 
@@ -174,15 +185,6 @@ async function fetchProgram(id: string): Promise<WixProgram | undefined> {
   }
 }
 
-async function load(state: State, arg?: unknown): Promise<State> {
-  stashCopy(arg);
-  try {
-    return ready(state, await fetchProgram(inputId()));
-  } catch {
-    return derive({ ...state, status: "error" });
-  }
-}
-
 /** Whether the existing commerce flow may start (before the join) and continue (before the Wix
  *  payment): a price refresh can move the program onto a route this flow must not charge. */
 interface CommerceGuards {
@@ -190,8 +192,6 @@ interface CommerceGuards {
   mayContinue(): boolean;
 }
 
-const ALWAYS_ALLOWED: CommerceGuards = { mayStart: () => true, mayContinue: () => true };
-
 async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<string> {
   const blocked = () => iapPriceCopy("program").purchaseUnavailable;
   if (!guards.mayStart()) return blocked();
@@ -251,27 +251,27 @@ async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<
   return copyTemplate("program.joinOnSiteMessage", "Enrolment happens on the website — visit the site to join {name}.", { name });
 }
 
-async function enroll(state: State): Promise<State> {
-  if (!inputId()) return state;
-  return derive({ ...state, actionMessage: await enrollmentMessage(state.name, ALWAYS_ALLOWED) });
-}
-
-// ── App Store pricing (enabled only when a mapping backend is connected) ─────
+// ── Content, App Store pricing and sale ─────
 //
-// One writer: `loadPriced` and `enrollPriced` keep their results here and every state change goes
-// through the synchronous `pricingPublish`, which re-reads the latest content and route. An async
-// action returning its own state could land after a refresh and revive a stale price or route.
+// One writer: `load`, `enroll` and `buy` keep their results here and every state
+// change goes through the synchronous `pricingPublish`, which re-reads the latest content, route
+// and checkout state. An async action returning its own state could land after a refresh and
+// revive a stale price, route or purchase.
 
-const pricing = createIapCatalogPricing({ onChange: () => { void svc.pricingPublish(); } });
-const PRICING_NOT_HYDRATED = ["priceLine", "priceNote", "hidePriceRetry", "enrollDisabled", "enrollNote"] as const;
+const commerce = createIapCommerce({ adapters: [onlineProgramOrders], onChange: () => { void svc.pricingPublish(); } });
+const pricing = commerce.pricing;
+const PRICING_NOT_HYDRATED = [
+  "priceLine", "priceNote", "hidePriceRetry", "enrollDisabled", "enrollNote", "enrollHidden", "buyHidden", "buyLabel", "buyDisabled", "buyNote",
+] as const;
 const CONTENT_KEYS = ["status", "name", "description", "meta", "image", "initial", "emptyText"] as const;
 type Content = Pick<State, (typeof CONTENT_KEYS)[number]>;
 const NO_PRICE: IapPriceFields = { priceText: "", priceNote: "", priceLoading: false, hidePriceRetry: true, actionDisabled: true, actionNote: "" };
+const NOT_APPLE: IapPurchaseFields = { appleRoute: false, accessReady: false, buyLabel: "", buyDisabled: true, buyBusy: false, buyNote: "" };
 let content: Content;
 let pricedItem: IapCatalogItem | undefined;
-let scopeIncomplete = false;
 let actionMessage = "";
 let loadSeq = 0;
+let commerceStarted = false;
 
 function contentOf(state: State): Content {
   return Object.fromEntries(CONTENT_KEYS.map((key) => [key, state[key]])) as Content;
@@ -279,7 +279,7 @@ function contentOf(state: State): Content {
 
 const programReference = () => onlineProgramItem({ id: inputId() })?.reference;
 
-async function loadPriced(state: State, arg?: unknown): Promise<undefined> {
+async function load(state: State, arg?: unknown): Promise<undefined> {
   stashCopy(arg);
   const seq = ++loadSeq;
   const found = await fetchProgram(inputId()).then((program) => ({ program }), () => undefined);
@@ -288,20 +288,27 @@ async function loadPriced(state: State, arg?: unknown): Promise<undefined> {
   pricedItem = found?.program ? onlineProgramItem({ id: inputId() }, priceOf(found.program)) : pricedItem;
   void svc.pricingPublish();
   if (found?.program) void priceProgram();
+  void resumeCommerce();
   return undefined;
 }
 
+/** First entry recovers held purchases; every later one (a return to the screen) reconciles. */
+async function resumeCommerce(): Promise<void> {
+  const first = !commerceStarted;
+  commerceStarted = true;
+  await (first ? commerce.start() : commerce.reconcile());
+  void svc.pricingPublish();
+}
+
 /** Content never waits on this, and the host scope is re-read each time, so a failed app-info
  *  read recovers on the next refresh. */
 async function priceProgram(): Promise<void> {
-  // The Retry action is declared in both modes; with no backend it must not reach the host.
-  if (!pricing.enabled) return;
-  const host = await hostIapScope();
-  scopeIncomplete = !hostScopeComplete(host);
-  if (pricedItem) await pricing.load({ ...host, items: [pricedItem] });
+  if (!pricedItem) return;
+  await commerce.loadPrices([pricedItem]);
+  void svc.pricingPublish();
 }
 
-async function enrollPriced(): Promise<undefined> {
+async function enroll(): Promise<undefined> {
   const reference = programReference();
   if (!reference) return undefined;
   // A tap that lands as a refresh starts is refused without a verdict: the route is unknown, not
@@ -314,13 +321,29 @@ async function enrollPriced(): Promise<undefined> {
   return undefined;
 }
 
+/** The App Store sale: only through the shared checkout, and only for the route the price shows. */
+async function buy(): Promise<undefined> {
+  const reference = programReference();
+  if (!reference) return undefined;
+  await commerce.buy({ reference });
+  void svc.pricingPublish();
+  return undefined;
+}
+
 function pricedState(state: State): State {
   const reference = programReference();
-  const price = reference ? iapPriceFields(pricing.view(reference), iapPriceCopy("program")) : NO_PRICE;
+  const view = reference && pricing.view(reference);
+  const price = view ? iapPriceFields(view, iapPriceCopy("program")) : NO_PRICE;
+  const purchase = reference ? commerce.purchaseFields(reference, iapPurchaseCopy("program")) : NOT_APPLE;
+  const poll = commerce.pollDirective("himiBrandedProgram.iapPoll");
   return derive({
-    ...state, ...content, actionMessage,
-    priceLine: price.priceText, priceNote: price.priceNote, hidePriceRetry: price.hidePriceRetry && !scopeIncomplete,
-    enrollDisabled: price.actionDisabled, enrollNote: price.actionNote,
+    ...state, ...content,
+    actionMessage: purchase.accessReady ? copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name: content.name }) : actionMessage,
+    // `disabled`: this app sells nothing through the App Store, so the program shows its own price.
+    priceLine: view?.route === "disabled" ? pricedItem?.commerceDisplayPrice ?? "" : price.priceText, priceNote: price.priceNote, hidePriceRetry: view?.route === "disabled" || (price.hidePriceRetry && commerce.scopeComplete()),
+    enrollDisabled: price.actionDisabled, enrollNote: price.actionNote, enrollHidden: purchase.appleRoute,
+    buyHidden: !purchase.appleRoute || purchase.accessReady, buyLabel: purchase.buyLabel, buyDisabled: purchase.buyDisabled, buyNote: purchase.buyNote,
+    ...(poll ? { _poll: poll } : {}),
   });
 }
 
@@ -344,34 +367,41 @@ const INITIAL_STATE: State = derive({
   hideContent: true,
   priceNote: "",
   hidePriceRetry: true,
-  enrollDisabled: pricing.enabled,
+  enrollDisabled: true,
   enrollNote: "",
+  enrollHidden: false,
+  buyHidden: true,
+  buyLabel: "",
+  buyDisabled: true,
+  buyNote: "",
 });
 
 type Actions = {
   load: (state: State, arg?: unknown) => Promise<State | undefined>;
   enroll: (state: State) => Promise<State | undefined>;
+  buy: (state: State) => Promise<State | undefined>;
   pricingPublish: (state: State) => State;
   pricingStart: (state: State) => State;
   pricingRefresh: (state: State) => Promise<undefined>;
+  iapPoll: (state: State) => Promise<undefined>;
 };
 
 const svc = defineService<State, Actions>("himiBrandedProgram", {
   state: INITIAL_STATE,
-  ...(pricing.enabled ? { notHydrated: [...PRICING_NOT_HYDRATED] } : {}),
+  notHydrated: [...PRICING_NOT_HYDRATED],
   actions: {
-    load: pricing.enabled ? loadPriced : load,
-    enroll: pricing.enabled ? enrollPriced : enroll,
+    load,
+    enroll,
+    buy,
     pricingPublish: pricedState,
-    pricingStart: (state) => ({ ...pricedState(state), _poll: pricing.pollDirective("himiBrandedProgram.pricingRefresh") }),
+    pricingStart: pricedState,
     pricingRefresh: async () => { await priceProgram(); return undefined; },
+    iapPoll: async () => { await commerce.poll(); void svc.pricingPublish(); return undefined; },
   },
 });
 
 content = contentOf(svc.getState());
-if (pricing.enabled) {
-  resetUnhydratedKeysOnOlderRuntime(svc, INITIAL_STATE, PRICING_NOT_HYDRATED);
-  void svc.pricingStart();
-}
+resetUnhydratedKeysOnOlderRuntime(svc, INITIAL_STATE, PRICING_NOT_HYDRATED);
+void svc.pricingStart();
 
 export { svc };