@wix/himalaya-cli 0.1240.0 → 0.1241.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/iap/src/index.d.ts

@@ -1,6 +1,8 @@
 import type { TransactionStore } from "./delivery-contract.js";
 export * from "./delivery-contract.js";
 export * from "./delivery.js";
+export * from "./pricing-contract.js";
+export * from "./pricing.js";
 /** The three store product categories. */
 export type ProductType = "subscription" | "nonConsumable" | "consumable";
 export interface Product {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/iap/src/pricing-contract.d.ts

@@ -0,0 +1,81 @@
+import type { Product } from "./index.js";
+export interface CatalogReference {
+    kind: string;
+    id: string;
+}
+/** Opaque context revision changes whenever a mapping-dependent audience changes. */
+export interface PricingScope {
+    appId: string;
+    bundleId: string;
+    siteId: string;
+    contextRevision?: string;
+}
+export interface PricingItem {
+    reference: CatalogReference;
+    /** Owned/formatted by the commerce caller; used only for an explicit regular route. */
+    commerceDisplayPrice?: string;
+}
+export interface PricingInput {
+    scope: PricingScope;
+    /** Trusted host platform; only "ios" performs Apple lookup. */
+    platform: string;
+    items: PricingItem[];
+}
+export type PricingMapping = {
+    reference: CatalogReference;
+} & ({
+    route: "appleIap";
+    productId: string;
+    mappingRevision: string;
+} | {
+    route: "regular";
+} | {
+    route: "unavailable";
+});
+/** Internal client port, not an agreed/deployed backend API. Never requires purchase context. */
+export interface PricingMappingProvider {
+    resolve(input: {
+        scope: PricingScope;
+        references: CatalogReference[];
+    }): Promise<PricingMapping[]>;
+}
+export type PricingUnavailableReason = "invalidInput" | "mappingUnavailable" | "mappingUnresolved" | "unsupportedPlatform" | "unsupportedProductType" | "priceUnavailable" | "commercePriceUnavailable";
+export type ItemPriceState = {
+    reference: CatalogReference;
+} & ({
+    status: "loading";
+} | {
+    status: "ready";
+    source: "appleIap";
+    displayPrice: string;
+    productId: string;
+    mappingRevision: string;
+} | {
+    status: "ready";
+    source: "regular";
+    displayPrice: string;
+} | {
+    status: "unavailable";
+    reason: PricingUnavailableReason;
+    retryable: boolean;
+});
+/** Contains no credentials, transaction proof, entitlement, or purchase authorization. */
+export interface PricingState {
+    revision: number;
+    scope: PricingScope | null;
+    items: ItemPriceState[];
+}
+export interface PricingDependencies {
+    mapping: PricingMappingProvider;
+    getProducts(productIds: string[]): Promise<Product[]>;
+    onState?(state: PricingState): void;
+}
+export interface PricingController {
+    /** Fresh lookup; identical in-flight input is shared. Completed prices are never cached. */
+    load(input: PricingInput): Promise<void>;
+    /** Reloads the last input, joining a matching lookup already in progress. */
+    refresh(): Promise<void>;
+    getState(): PricingState;
+    /** Clears state and suppresses subsequent calls/publications; cannot cancel native I/O. */
+    dispose(): void;
+}

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/iap/src/pricing.d.ts

@@ -0,0 +1,3 @@
+import type { PricingController, PricingDependencies } from "./pricing-contract.js";
+/** Creates one worker's read-only pricing controller with injected mapping, store lookup, and state publication. */
+export declare function createPricingController(deps: PricingDependencies): PricingController;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/iap.mjs

@@ -25,7 +25,7 @@ function createPurchaseCoordinator(deps) {
   let outcome = "idle";
   let purchasing = false;
   let signInPrompt = false;
-  let unavailable = null;
+  let unavailable2 = null;
   let pendingApproval = null;
   let errorCode = null;
   let errorFromReconcile = false;
@@ -61,7 +61,7 @@ function createPurchaseCoordinator(deps) {
     if (disposed || !sessionMatches()) return { phase: "idle", errorCode: null, items: [], unfinishedCount: null, nextWakeAt: null };
     const snapshot = [...items.values()].map((item) => ({ ...item.state }));
     const due = snapshot.map((item) => item.nextAttemptAt).filter((at) => at !== null);
-    return { phase: currentPhase(), errorCode: errorCode ?? unavailable?.code ?? null, items: snapshot, unfinishedCount, nextWakeAt: due.length > 0 ? Math.min(...due) : null };
+    return { phase: currentPhase(), errorCode: errorCode ?? unavailable2?.code ?? null, items: snapshot, unfinishedCount, nextWakeAt: due.length > 0 ? Math.min(...due) : null };
   }
   function dispose() {
     disposed = true;
@@ -73,7 +73,7 @@ function createPurchaseCoordinator(deps) {
     setError(null, false);
     outcome = "idle";
     pendingApproval = null;
-    unavailable = null;
+    unavailable2 = null;
     releaseSignIn();
     if (session.kind !== "member") {
       requireSignIn();
@@ -132,7 +132,7 @@ function createPurchaseCoordinator(deps) {
     }
   }
   function clearReconcileProblem() {
-    if (unavailable?.from === "reconcile") unavailable = null;
+    if (unavailable2?.from === "reconcile") unavailable2 = null;
     if (errorFromReconcile) setError(null, false);
   }
   async function runRetry() {
@@ -297,7 +297,7 @@ function createPurchaseCoordinator(deps) {
     outcome = "idle";
     purchasing = false;
     signInPrompt = false;
-    unavailable = null;
+    unavailable2 = null;
     pendingApproval = null;
     unfinishedCount = null;
     setError(null, false);
@@ -355,8 +355,8 @@ function createPurchaseCoordinator(deps) {
   }
   function failStore(code, fromReconcile) {
     setError(code, fromReconcile);
-    if (UNAVAILABLE_CODES.has(code) && unavailable?.from !== "purchase") {
-      unavailable = { from: fromReconcile ? "reconcile" : "purchase", code };
+    if (UNAVAILABLE_CODES.has(code) && unavailable2?.from !== "purchase") {
+      unavailable2 = { from: fromReconcile ? "reconcile" : "purchase", code };
     }
     publish();
   }
@@ -373,9 +373,9 @@ function createPurchaseCoordinator(deps) {
   }
   function currentPhase() {
     if (purchasing) return "purchasing";
-    if (unavailable?.from === "purchase") return "unavailable";
+    if (unavailable2?.from === "purchase") return "unavailable";
     if (signInPrompt) return "signInRequired";
-    if (unavailable?.from === "reconcile") return "unavailable";
+    if (unavailable2?.from === "reconcile") return "unavailable";
     return outcome;
   }
   function setError(code, fromReconcile) {
@@ -514,6 +514,140 @@ function createSerialQueue() {
   };
 }
 
+// ../../core/sdk/iap/src/pricing.ts
+function createPricingController(deps) {
+  let state = { revision: 0, scope: null, items: [] };
+  let lastInput;
+  let active;
+  let disposed = false;
+  function load(input) {
+    if (disposed) return Promise.resolve();
+    const captured = captureInput(input);
+    const key = JSON.stringify(captured);
+    if (active?.key === key) return active.promise;
+    lastInput = captured;
+    const revision = state.revision + 1;
+    let complete;
+    const promise = new Promise((resolve) => {
+      complete = resolve;
+    });
+    active = { key, promise };
+    publish({ revision, scope: captured.scope, items: captured.items.map((item) => ({ reference: item.reference, status: "loading" })) });
+    void run(captured, revision).finally(complete);
+    return promise;
+  }
+  async function run(input, revision) {
+    const current = () => !disposed && state.revision === revision;
+    if (!current()) return;
+    const items = await resolvePrices(input, deps, current);
+    if (!current()) return;
+    active = void 0;
+    publish({ revision, scope: input.scope, items });
+  }
+  function publish(next) {
+    state = next;
+    try {
+      deps.onState?.(getState());
+    } catch {
+    }
+  }
+  function getState() {
+    return {
+      ...state,
+      scope: state.scope ? { ...state.scope } : null,
+      items: state.items.map((item) => ({ ...item, reference: { ...item.reference } }))
+    };
+  }
+  function dispose() {
+    disposed = true;
+    active = void 0;
+    lastInput = void 0;
+    state = { revision: state.revision + 1, scope: null, items: [] };
+  }
+  return { load, refresh: () => lastInput ? load(lastInput) : Promise.resolve(), getState, dispose };
+}
+function captureInput(input) {
+  const scope = {
+    appId: input.scope.appId,
+    bundleId: input.scope.bundleId,
+    siteId: input.scope.siteId,
+    ...input.scope.contextRevision === void 0 ? {} : { contextRevision: input.scope.contextRevision }
+  };
+  const items = /* @__PURE__ */ new Map();
+  for (const item of input.items) {
+    const reference = { kind: item.reference.kind, id: item.reference.id };
+    const key = JSON.stringify([reference.kind, reference.id]);
+    if (!items.has(key)) items.set(key, { reference, ...item.commerceDisplayPrice === void 0 ? {} : { commerceDisplayPrice: item.commerceDisplayPrice } });
+  }
+  return { scope, platform: input.platform, items: [...items.values()] };
+}
+async function resolvePrices(input, deps, current) {
+  if (input.items.length === 0) return [];
+  if (![input.scope.appId, input.scope.bundleId, input.scope.siteId].every(nonempty)) {
+    return input.items.map((item) => unavailable(item.reference, "invalidInput"));
+  }
+  const mappings = await resolveMappings(input, deps);
+  if (!current()) return [];
+  if (mappings === null) return input.items.map((item) => unavailable(item.reference, "mappingUnavailable"));
+  const routes = input.items.map((item) => resolveRoute(item, mappings, input.platform));
+  const ids = [...new Set(routes.flatMap((route) => route.status === "loading" ? [route.mapping.productId] : []))];
+  const products = ids.length ? await lookupProducts(ids, deps) : [];
+  return routes.map((route) => route.status === "loading" ? applePrice(route.mapping, products) : route);
+}
+async function resolveMappings(input, deps) {
+  try {
+    const references = input.items.filter((item) => nonempty(item.reference.kind) && nonempty(item.reference.id)).map((item) => ({ ...item.reference }));
+    if (!references.length) return [];
+    const result = await deps.mapping.resolve({ scope: { ...input.scope }, references });
+    return Array.isArray(result) ? result : [];
+  } catch {
+    return null;
+  }
+}
+async function lookupProducts(ids, deps) {
+  try {
+    const products = await deps.getProducts(ids);
+    return Array.isArray(products) ? products : [];
+  } catch {
+    return [];
+  }
+}
+function resolveRoute(item, mappings, platform) {
+  if (!nonempty(item.reference.kind) || !nonempty(item.reference.id)) return unavailable(item.reference, "invalidInput");
+  const matches = mappings.filter((value) => isObject2(value) && sameReference(value.reference, item.reference));
+  if (matches.length !== 1) return unavailable(item.reference, "mappingUnresolved");
+  const mapping = matches[0];
+  if (mapping.route === "regular") return regularPrice(item);
+  if (mapping.route !== "appleIap" || !nonempty(mapping.productId) || mapping.productId.includes(",") || !nonempty(mapping.mappingRevision)) {
+    return unavailable(item.reference, "mappingUnresolved");
+  }
+  if (platform !== "ios") return unavailable(item.reference, "unsupportedPlatform");
+  return { status: "loading", mapping: { reference: item.reference, route: "appleIap", productId: mapping.productId, mappingRevision: mapping.mappingRevision } };
+}
+function regularPrice(item) {
+  return nonempty(item.commerceDisplayPrice) ? { reference: item.reference, status: "ready", source: "regular", displayPrice: item.commerceDisplayPrice } : unavailable(item.reference, "commercePriceUnavailable");
+}
+function applePrice(mapping, products) {
+  const matches = products.filter((value) => isObject2(value) && value.id === mapping.productId);
+  const product = matches[0];
+  if (matches.length !== 1 || !nonempty(product?.displayPrice)) return unavailable(mapping.reference, "priceUnavailable");
+  if (product?.type !== "nonConsumable") return unavailable(mapping.reference, "unsupportedProductType");
+  return {
+    reference: mapping.reference,
+    status: "ready",
+    source: "appleIap",
+    productId: mapping.productId,
+    mappingRevision: mapping.mappingRevision,
+    displayPrice: product.displayPrice
+  };
+}
+function unavailable(reference, reason) {
+  return { reference, status: "unavailable", reason, retryable: !["invalidInput", "unsupportedPlatform", "unsupportedProductType", "commercePriceUnavailable"].includes(reason) };
+}
+var isObject2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+var sameReference = (value, reference) => isObject2(value) && value.kind === reference.kind && value.id === reference.id;
+
 // ../../core/sdk/iap/src/index.ts
 async function getPaywallConfig() {
   const r = await dispatch("capability.iap.getPaywallConfig");
@@ -561,7 +695,7 @@ function normalizeStatus(s) {
 }
 var version = 2;
 async function purchaseForVerification(input) {
-  if (!nonempty(input?.productId) || !isUUID(input?.appAccountToken)) return failure("invalidArgument");
+  if (!nonempty2(input?.productId) || !isUUID(input?.appAccountToken)) return failure("invalidArgument");
   const result = await managedDispatch(() => dispatch("capability.iap.purchaseForVerification", input));
   if (result?.status === "purchased" && isAppleTransaction(result.transaction)) {
     return { status: "purchased", transaction: decodeTransaction(result.transaction) };
@@ -577,7 +711,7 @@ async function getUnfinishedTransactions() {
   return decodeFailure(result);
 }
 async function finishTransaction(input) {
-  if (!nonempty(input?.transactionId)) return failure("invalidArgument");
+  if (!nonempty2(input?.transactionId)) return failure("invalidArgument");
   const result = await managedDispatch(() => dispatch("capability.iap.finishTransaction", input));
   if (result?.status === "finished" || result?.status === "notFound") return { status: result.status };
   return decodeFailure(result);
@@ -585,13 +719,13 @@ async function finishTransaction(input) {
 var appleManagedStore = { purchaseForVerification, getUnfinishedTransactions, finishTransaction };
 var transactionErrors = /* @__PURE__ */ new Set(["unsupported", "unavailable", "invalidArgument", "invalidResponse", "notEnabled", "unsupportedProductType", "unknownProduct", "verificationFailed", "persistenceFailed", "ownershipConflict", "storeError", "busy"]);
 var failure = (code) => ({ status: "failed", code });
-var nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+var nonempty2 = (value) => typeof value === "string" && value.trim().length > 0;
 var isUUID = (value) => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value) && value.length === 36;
-var isObject2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var isObject3 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 async function managedDispatch(invoke) {
   try {
     const value = await invoke();
-    return isObject2(value) ? value : null;
+    return isObject3(value) ? value : null;
   } catch {
     return failure("unavailable");
   }
@@ -600,8 +734,8 @@ function decodeFailure(value) {
   return value?.status === "failed" && transactionErrors.has(value.code) ? failure(value.code) : failure("invalidResponse");
 }
 function isAppleTransaction(value) {
-  if (!isObject2(value)) return false;
-  return value.store === "apple" && typeof value.signedTransaction === "string" && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value.signedTransaction) && nonempty(value.transactionId) && nonempty(value.originalTransactionId) && nonempty(value.productId) && (value.appAccountToken === null || isUUID(value.appAccountToken)) && ["production", "sandbox", "xcode", "unknown"].includes(value.environment);
+  if (!isObject3(value)) return false;
+  return value.store === "apple" && typeof value.signedTransaction === "string" && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value.signedTransaction) && nonempty2(value.transactionId) && nonempty2(value.originalTransactionId) && nonempty2(value.productId) && (value.appAccountToken === null || isUUID(value.appAccountToken)) && ["production", "sandbox", "xcode", "unknown"].includes(value.environment);
 }
 function decodeTransaction(value) {
   const { store, signedTransaction, transactionId, originalTransactionId, productId, appAccountToken, environment } = value;
@@ -612,6 +746,7 @@ export {
   MAX_RETRY_DELAY_MS,
   appleManagedStore,
   consume,
+  createPricingController,
   createPurchaseCoordinator,
   entitlements,
   finishTransaction,

package/dist/cli.mjs

@@ -6878,6 +6878,7 @@ function resolveTranslation(value, catalog, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
+    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s2) => s2 !== "t").join("|")})\\b|^\\$t:`
@@ -13431,6 +13432,7 @@ function resolveIdiom(tokens2, ctx = {}) {
 var IDIOM_CONTEXTS, UNSAFE_KEYS;
 var init_idiom = __esm({
   "../../core/ts/src/idiom.ts"() {
+    "use strict";
     IDIOM_CONTEXTS = {
       ios: { native: ["ios"] },
       android: { native: ["material"] },

package/guides/iap-pricing.md

@@ -0,0 +1,225 @@
+# 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.
+
+```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;
+}
+
+interface PriceRow {
+  id: string;
+  status: "loading" | "ready" | "unavailable";
+  displayPrice: string;
+  message: string;
+  retryable: boolean;
+  loading: boolean;
+  hideLoading: boolean;
+  hideRetry: boolean;
+}
+
+interface PriceServiceState {
+  pricing: PricingState;
+  rows: PriceRow[];
+  canPurchase: boolean;
+  purchaseDisabled: boolean;
+}
+
+export function registerPricingService(
+  mapping: PricingMappingProvider, initialInput: PricingInput, copy: PriceCopy,
+) {
+  let input = initialInput;
+  let disposed = false;
+  const controller = createPricingController({
+    mapping, getProducts,
+    onState: () => { void service.publish(); },
+  });
+
+  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,
+    }));
+  }
+
+  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 };
+    },
+  };
+  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.

package/guides/index.json

@@ -178,6 +178,12 @@
       "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",

package/guides/sdk-reference.json

@@ -1705,6 +1705,78 @@
         "jsdoc": "/** Creates a coordinator owned by the host/service lifecycle, not by a screen or render.\n *  Closures, not classes: Tier-5 bundles must also evaluate on Hermes, which has no `class`. */",
         "decl": "export function createPurchaseCoordinator(deps: PurchaseCoordinatorDependencies): PurchaseCoordinator;"
       },
+      {
+        "name": "CatalogReference",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface CatalogReference {\n  kind: string;\n  id: string;\n}"
+      },
+      {
+        "name": "PricingScope",
+        "kind": "interface",
+        "jsdoc": "/** Opaque context revision changes whenever a mapping-dependent audience changes. */",
+        "decl": "export interface PricingScope {\n  appId: string;\n  bundleId: string;\n  siteId: string;\n  contextRevision?: string;\n}"
+      },
+      {
+        "name": "PricingItem",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PricingItem {\n  reference: CatalogReference;\n  /** Owned/formatted by the commerce caller; used only for an explicit regular route. */\n  commerceDisplayPrice?: string;\n}"
+      },
+      {
+        "name": "PricingInput",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PricingInput {\n  scope: PricingScope;\n  /** Trusted host platform; only \"ios\" performs Apple lookup. */\n  platform: string;\n  items: PricingItem[];\n}"
+      },
+      {
+        "name": "PricingMapping",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type PricingMapping = { reference: CatalogReference } & (\n  | { route: \"appleIap\"; productId: string; mappingRevision: string }\n  | { route: \"regular\" }\n  | { route: \"unavailable\" }\n);"
+      },
+      {
+        "name": "PricingMappingProvider",
+        "kind": "interface",
+        "jsdoc": "/** Internal client port, not an agreed/deployed backend API. Never requires purchase context. */",
+        "decl": "export interface PricingMappingProvider {\n  resolve(input: { scope: PricingScope; references: CatalogReference[] }): Promise<PricingMapping[]>;\n}"
+      },
+      {
+        "name": "PricingUnavailableReason",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type PricingUnavailableReason = \"invalidInput\" | \"mappingUnavailable\" | \"mappingUnresolved\"\n  | \"unsupportedPlatform\" | \"unsupportedProductType\" | \"priceUnavailable\" | \"commercePriceUnavailable\";"
+      },
+      {
+        "name": "ItemPriceState",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type ItemPriceState = { reference: CatalogReference } & (\n  | { status: \"loading\" }\n  | { status: \"ready\"; source: \"appleIap\"; displayPrice: string; productId: string; mappingRevision: string }\n  | { status: \"ready\"; source: \"regular\"; displayPrice: string }\n  | { status: \"unavailable\"; reason: PricingUnavailableReason; retryable: boolean }\n);"
+      },
+      {
+        "name": "PricingState",
+        "kind": "interface",
+        "jsdoc": "/** Contains no credentials, transaction proof, entitlement, or purchase authorization. */",
+        "decl": "export interface PricingState {\n  revision: number;\n  scope: PricingScope | null;\n  items: ItemPriceState[];\n}"
+      },
+      {
+        "name": "PricingDependencies",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PricingDependencies {\n  mapping: PricingMappingProvider;\n  getProducts(productIds: string[]): Promise<Product[]>;\n  onState?(state: PricingState): void;\n}"
+      },
+      {
+        "name": "PricingController",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface PricingController {\n  /** Fresh lookup; identical in-flight input is shared. Completed prices are never cached. */\n  load(input: PricingInput): Promise<void>;\n  /** Reloads the last input, joining a matching lookup already in progress. */\n  refresh(): Promise<void>;\n  getState(): PricingState;\n  /** Clears state and suppresses subsequent calls/publications; cannot cancel native I/O. */\n  dispose(): void;\n}"
+      },
+      {
+        "name": "createPricingController",
+        "kind": "function",
+        "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": "ProductType",
         "kind": "type",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1240.0",
+  "version": "0.1241.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": "fa100c156434113a7befa8bdb97c6f87ee57d27d3e088aa3b2a9752c"
+  "falconPackageHash": "5e95fe6c20dcd9b9fbc99564f2535787252632211a307e0d5b9908f9"
 }