@wix/himalaya-cli 0.1367.0 → 0.1369.0

package/guides/sdk-reference.json

@@ -1958,11 +1958,23 @@
         "jsdoc": "/** How the App Store sells one vertical's Wix item: the purchases catalog's `appProductId` for it, and\n *  the only product type the purchase flow sells it as. */",
         "decl": "export interface AppleSaleRule {\n  appProductId(entityId: string): string;\n  productType: \"NON_CONSUMABLE\";\n}"
       },
+      {
+        "name": "STORES_ITEM_PAYMENT_ENABLED",
+        "kind": "const",
+        "jsdoc": "/**\n * Whether Wix Stores items sell through the App Store, through wix-iap StartItemPayment\n * (catalyst-server #24496), which places the member's eCom order for one catalog item. OFF: that RPC\n * is not deployed, the member's identity across Serve → wix-iap → eCom is unproven, and a paid Stores\n * order is not yet proven to deliver the download. The one switch: it adds the Stores rule to\n * `APPLE_SALE_RULES`, which the mapping source and `himi store iap connect` read, and turns on the\n * checkout's path (`itemPaymentEnabled` in @himalaya/iap-checkout).\n */",
+        "decl": "export const STORES_ITEM_PAYMENT_ENABLED = false;"
+      },
+      {
+        "name": "STORES_PRODUCT_SALE_RULE",
+        "kind": "const",
+        "jsdoc": "/** StartItemPayment's CatalogReference: the purchases catalog sells a Stores product under its product\n *  id (eCom's `catalogItemId`). One-time unlocks only, whatever the backend also accepts. */",
+        "decl": "export const STORES_PRODUCT_SALE_RULE: AppleSaleRule = { appProductId: (id) => id, productType: \"NON_CONSUMABLE\" };"
+      },
       {
         "name": "APPLE_SALE_RULES",
         "kind": "const",
-        "jsdoc": "/**\n * The one definition `himi store iap connect` writes mappings by and the mapping source reads them by,\n * keyed by catalog kind. wix-iap StartPayment maps the cashier order's single item id, and Online\n * Programs builds that order with the program id as the item id; programs are one-time unlocks.\n * Other verticals' order item ids are not established yet, so their items keep their own commerce.\n */",
-        "decl": "export const APPLE_SALE_RULES: Readonly<Record<string, AppleSaleRule>> = {\n  onlineProgram: { appProductId: (id) => id, productType: \"NON_CONSUMABLE\" },\n};"
+        "jsdoc": "/**\n * The one definition `himi store iap connect` writes mappings by and the mapping source reads them by,\n * keyed by catalog kind. wix-iap StartPayment maps the cashier order's single item id, and Online\n * Programs builds that order with the program id as the item id; programs are one-time unlocks.\n * Wix Stores joins only with `STORES_ITEM_PAYMENT_ENABLED`. Other verticals' order item ids are not\n * established yet, so their items keep their own commerce.\n */",
+        "decl": "export const APPLE_SALE_RULES: Readonly<Record<string, AppleSaleRule>> = STORES_ITEM_PAYMENT_ENABLED\n  ? { onlineProgram: ONLINE_PROGRAM_SALE_RULE, storesProduct: STORES_PRODUCT_SALE_RULE }\n  : { onlineProgram: ONLINE_PROGRAM_SALE_RULE };"
       },
       {
         "name": "HostCallExpectation",
@@ -1998,7 +2010,7 @@
         "name": "WixIapOperation",
         "kind": "type",
         "jsdoc": "",
-        "decl": "export type WixIapOperation = \"startPayment\" | \"completePayment\" | \"getPayment\";"
+        "decl": "export type WixIapOperation = \"startPayment\" | \"startItemPayment\" | \"completePayment\" | \"getPayment\";"
       },
       {
         "name": "StartPaymentErrorCode",
@@ -2006,6 +2018,12 @@
         "jsdoc": "",
         "decl": "export type StartPaymentErrorCode = \"NOT_PENDING\" | \"WRONG_PAYMENT_METHOD\" | \"NOT_ORDER_BUYER\" | \"UNSUPPORTED_ORDER\"\n  | \"PRODUCT_NOT_AVAILABLE\" | \"ALREADY_OWNED\";"
       },
+      {
+        "name": "StartItemPaymentErrorCode",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type StartItemPaymentErrorCode = \"PRODUCT_NOT_AVAILABLE\" | \"ALREADY_OWNED\" | \"ITEM_NOT_AVAILABLE\"\n  | \"SITE_NOT_ACCEPTING_PAYMENTS\" | \"UNSUPPORTED_ORDER\";"
+      },
       {
         "name": "CompletePaymentErrorCode",
         "kind": "type",
@@ -2036,6 +2054,24 @@
         "jsdoc": "/** `appAccountToken` goes to StoreKit with the purchase. It is minted for this one payment (a\n *  purchase intent, D61), not the member: StartPayment for the same Wix transaction again returns\n *  the same payment and the same token. Keep it out of screen state. */",
         "decl": "export type StartPaymentResult =\n  | { status: \"started\"; payment: WixIapPayment; storeProductId: string; appAccountToken: string }\n  | WixIapFailure<StartPaymentErrorCode>;"
       },
+      {
+        "name": "EcomCatalogReference",
+        "kind": "interface",
+        "jsdoc": "/** One item a Wix catalog sells through eCom, as eCom's `catalogReference` names it: for Wix Stores,\n *  the product id and the Stores app id. The purchases catalog sells it under `catalogItemId` as its\n *  `appProductId`. Variants and options are not supported, and the quantity is always 1. */",
+        "decl": "export interface EcomCatalogReference {\n  catalogItemId: string;\n  catalogAppId: string;\n}"
+      },
+      {
+        "name": "StartItemPaymentOutcomeUnknown",
+        "kind": "interface",
+        "jsdoc": "/** StartItemPayment was handed to the transport and gave no answer this client can act on: an\n *  outage, a lost or late answer, or a 2xx it could not decode. The service may have placed an\n *  eCom order and started a Payment for it, and it has no idempotency key, so resending places\n *  another order. No token came back, so nothing can be sold against it either. */",
+        "decl": "export interface StartItemPaymentOutcomeUnknown {\n  status: \"outcomeUnknown\";\n  operation: \"startItemPayment\";\n  kind: WixIapFailureKind;\n  httpStatus?: number;\n}"
+      },
+      {
+        "name": "StartItemPaymentResult",
+        "kind": "type",
+        "jsdoc": "/** StartItemPayment places the member's eCom order for one catalog item, charges it with\n *  `appleIAP` and starts its Payment, all server-side. Four different ids come back: the eCom\n *  order (`ecomOrderId`), the Wix Payments charge (`payment.wixTransactionId`), the wix-iap\n *  Payment (`payment.paymentId`) and the StoreKit `appAccountToken`. Keep them out of screen state. */",
+        "decl": "export type StartItemPaymentResult =\n  | { status: \"started\"; payment: WixIapPayment; storeProductId: string; appAccountToken: string; ecomOrderId: string }\n  | WixIapFailure<StartItemPaymentErrorCode>\n  | StartItemPaymentOutcomeUnknown;"
+      },
       {
         "name": "CompletePaymentResult",
         "kind": "type",
@@ -2059,13 +2095,13 @@
         "name": "WixIapClient",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface WixIapClient {\n  /** StartPayment for a pending `appleIAP` Wix Payments transaction the member placed. Returns the\n   *  store product to sell and this payment's `appAccountToken` to pass to StoreKit. */\n  startPayment(input: { wixTransactionId: string }): Promise<StartPaymentResult>;\n  /** CompletePayment with held Apple proof, sent unchanged: the service pays the payment whose\n   *  token the transaction carries. Success can still be `approving`. */\n  completePayment(transaction: AppleTransaction): Promise<CompletePaymentResult>;\n  /** GetPayment: one of the member's own Payments. */\n  getPayment(input: { paymentId: string }): Promise<GetPaymentResult>;\n}",
+        "decl": "export interface WixIapClient {\n  /** StartPayment for a pending `appleIAP` Wix Payments transaction the member placed. Returns the\n   *  store product to sell and this payment's `appAccountToken` to pass to StoreKit. */\n  startPayment(input: { wixTransactionId: string }): Promise<StartPaymentResult>;\n  /** StartItemPayment for one catalog item: the service places the member's eCom order, charges it\n   *  and starts its Payment. Every call places a new order, so `outcomeUnknown` must never be\n   *  resent as if nothing happened. Returns the store product, the token and the eCom order. */\n  startItemPayment(input: { item: EcomCatalogReference }): Promise<StartItemPaymentResult>;\n  /** CompletePayment with held Apple proof, sent unchanged: the service pays the payment whose\n   *  token the transaction carries. Success can still be `approving`. */\n  completePayment(transaction: AppleTransaction): Promise<CompletePaymentResult>;\n  /** GetPayment: one of the member's own Payments. */\n  getPayment(input: { paymentId: string }): Promise<GetPaymentResult>;\n}",
         "verified": false
       },
       {
         "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 * 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 */",
+        "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`), StartItemPayment (`POST …/payments/start-item`, not yet\n * deployed), CompletePayment (`POST …/payments/complete`) 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
       },
@@ -2298,6 +2334,12 @@
         "jsdoc": "",
         "decl": "export { createWorkerOrderRefStore } from \"./order-refs.js\";"
       },
+      {
+        "name": "\"./checkout-source.js\"",
+        "kind": "reexport",
+        "jsdoc": "",
+        "decl": "export { itemPaymentEnabled } from \"./checkout-source.js\";"
+      },
       {
         "name": "\"./apple-iap-contract.js\"",
         "kind": "reexport",
@@ -2334,6 +2376,12 @@
         "jsdoc": "/** Persists unfinished orders per app and member, using the host KV unless storage is supplied. */",
         "decl": "export function createWorkerOrderRefStore(storage?: KeyValueStorage): OrderRefStore;"
       },
+      {
+        "name": "itemPaymentEnabled",
+        "kind": "function",
+        "jsdoc": "/**\n * Whether an item whose adapter names it in eCom's catalog (a Wix Stores product) is paid through\n * wix-iap StartItemPayment, which places the member's eCom order server-side. The same switch as\n * the Stores sale rule (`STORES_ITEM_PAYMENT_ENABLED`, @himalaya/iap), so Stores items reach an App\n * Store route only when this path sells them. Turning it off again stops only new attempts: stored\n * ones are still held, completed and tracked ().\n */",
+        "decl": "export function itemPaymentEnabled(): boolean;"
+      },
       {
         "name": "WixBridge",
         "kind": "interface",
@@ -2398,7 +2446,7 @@
         "name": "IapOrderAdapter",
         "kind": "interface",
         "jsdoc": "/** The only per-vertical code. Every call goes through the session-bound bridge it is given. */",
-        "decl": "export interface IapOrderAdapter {\n  /** The catalog kind it sells (`onlineProgram`, `pricingPlan`, `storesProduct`, or a custom one). */\n  readonly kind: string;\n  /** Structural check before any call: one item, quantity 1, a supported shape. */\n  eligibility(item: IapOrderItem): IapEligibility;\n  /** Opens, or reuses the vertical's own open, order for the signed-in member. */\n  openOrder(item: IapOrderItem, bridge: SessionBoundBridge): Promise<OrderAttempt>;\n  /** Re-reads an order opened earlier; `open` only while it can still be paid. */\n  reopenOrder(order: { cashierOrderId: string; verticalRef: VerticalRef }, bridge: SessionBoundBridge): Promise<OrderAttempt>;\n  /** The vertical's authoritative answer for the order's item and the signed-in member. */\n  readAccess(verticalRef: VerticalRef, bridge: SessionBoundBridge): Promise<AccessRead>;\n  /** The member's access to an item before any order exists (bought through Wix, say). Read-only:\n   *  never opens or prepares an order. An adapter without it shows Get access until a sale says otherwise. */\n  currentAccess?(item: IapOrderItem, bridge: SessionBoundBridge): Promise<AccessRead>;\n}"
+        "decl": "export interface IapOrderAdapter {\n  /** The catalog kind it sells (`onlineProgram`, `pricingPlan`, `storesProduct`, or a custom one). */\n  readonly kind: string;\n  /** Structural check before any call: one item, quantity 1, a supported shape. */\n  eligibility(item: IapOrderItem): IapEligibility;\n  /** Opens, or reuses the vertical's own open, order for the signed-in member. */\n  openOrder(item: IapOrderItem, bridge: SessionBoundBridge): Promise<OrderAttempt>;\n  /** Re-reads an order opened earlier; `open` only while it can still be paid. */\n  reopenOrder(order: { cashierOrderId: string; verticalRef: VerticalRef }, bridge: SessionBoundBridge): Promise<OrderAttempt>;\n  /** The vertical's authoritative answer for the order's item and the signed-in member. */\n  readAccess(verticalRef: VerticalRef, bridge: SessionBoundBridge): Promise<AccessRead>;\n  /** The member's access to an item before any order exists (bought through Wix, say). Read-only:\n   *  never opens or prepares an order. An adapter without it shows Get access until a sale says otherwise. */\n  currentAccess?(item: IapOrderItem, bridge: SessionBoundBridge): Promise<AccessRead>;\n  /** When the platform enables StartItemPayment, an eligible item whose order wix-iap places itself\n   *  instead of `openOrder`. Null for an item outside that shape, which keeps `openOrder`. */\n  itemPayment?(item: IapOrderItem): ItemPayment | null;\n}"
       },
       {
         "name": "OrderPartitionKey",
@@ -2409,8 +2457,8 @@
       {
         "name": "OrderRefStage",
         "kind": "type",
-        "jsdoc": "/** `held`: Apple charged, and CompletePayment refused the proof without recording it, so the\n *  transaction stays unfinished and is retried. `needsSupport`: recorded and refused for good. */",
-        "decl": "export type OrderRefStage = \"ordered\" | \"charged\" | \"started\" | \"submitted\" | \"held\" | \"needsSupport\";"
+        "jsdoc": "/** `startingItem`: a StartItemPayment was or is about to be sent and its answer is not stored, so\n *  the service may have placed an order this device knows nothing of; nothing else is sold for the\n *  item until it expires. `held`: Apple charged, and CompletePayment refused the proof without\n *  recording it, so the transaction stays unfinished and is retried. `needsSupport`: recorded and\n *  refused for good. */",
+        "decl": "export type OrderRefStage = \"startingItem\" | \"ordered\" | \"charged\" | \"started\" | \"submitted\" | \"held\" | \"needsSupport\";"
       },
       {
         "name": "OrderRef",
@@ -2434,7 +2482,7 @@
         "name": "OrderFailureCode",
         "kind": "type",
         "jsdoc": "",
-        "decl": "export type OrderFailureCode =\n  | \"notEnabled\" | \"notConfigured\" | \"signInRequired\" | \"unsupportedItem\" | \"notAppleRoute\"\n  | \"storageUnavailable\" | \"approvalRequired\" | \"orderClosed\" | \"orderRefused\" | \"chargeFailed\"\n  | \"paymentRefused\" | \"paymentHeld\" | \"alreadyOwned\" | \"paymentInProgress\" | \"productChanged\"\n  | \"invalidAssociation\" | \"needsSupport\" | \"unavailable\" | \"sessionChanged\";"
+        "decl": "export type OrderFailureCode =\n  | \"notEnabled\" | \"notConfigured\" | \"signInRequired\" | \"unsupportedItem\" | \"notAppleRoute\"\n  | \"storageUnavailable\" | \"approvalRequired\" | \"orderClosed\" | \"orderRefused\" | \"chargeFailed\"\n  | \"paymentRefused\" | \"paymentHeld\" | \"alreadyOwned\" | \"paymentInProgress\" | \"productChanged\"\n  | \"invalidAssociation\" | \"needsSupport\" | \"unavailable\" | \"sessionChanged\" | \"outcomeUnknown\";"
       },
       {
         "name": "PaymentAccess",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1367.0",
+  "version": "0.1369.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": "f0bd979c3332da32c4c59ee213e5f02fad1f6edd492c8ab44ee4947b"
+  "falconPackageHash": "fd3751d6f6d280437ca5e65dad0bcfc33119ae43eff7ee5ad3523d30"
 }

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

@@ -26717,7 +26717,55 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
               "modifiers": {
                 "cornerRadius": 8,
                 "pressFeedback": "scale",
-                "haptic": "medium"
+                "haptic": "medium",
+                "hiddenPath": "$service:himiStoreProduct.cartHidden"
+              }
+            },
+            {
+              "id": "himi_product.buy",
+              "body": {
+                "package": "himalaya",
+                "type": "Button",
+                "props": {
+                  "title": "$service:himiStoreProduct.buyLabel",
+                  "style": "primary",
+                  "fullWidth": true,
+                  "disabledPath": "$service:himiStoreProduct.buyDisabled",
+                  "action": {
+                    "actionId": "tier5.himiStoreProduct.buy"
+                  }
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiStoreProduct.buyHidden"
+              }
+            },
+            {
+              "id": "himi_product.buy_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiStoreProduct.buyNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiStoreProduct.buyHidden"
+              }
+            },
+            {
+              "id": "himi_product.purchased",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiStoreProduct.purchasedNote",
+                  "style": "footnote",
+                  "collapseWhenEmpty": true
+                }
               }
             },
             {

package/templates/beauty-salon/tier5-src/_shared/iap-presentation.ts

@@ -1,11 +1,13 @@
 import { defineService, type ServiceDefinition } from "@himalaya/state";
-import { createIapCommerce, type IapCommerce } from "@himalaya/iap-checkout";
+import { createIapCommerce, type IapCommerce, type IapOrderAdapter } from "@himalaya/iap-checkout";
 import { iapPriceFields, type IapCatalogItem } from "@himalaya/iap";
 import { iapPriceCopy, resetUnhydratedKeysOnOlderRuntime } from "./iap-worker.js";
 
 // Presentation only. Checkout, mapping, cache, session and refresh policy stay in the shared flow.
 export function withIapPresentation<S extends object>(options: {
   register?: typeof defineService;
+  /** The verticals this screen sells; none for a screen that only shows prices. */
+  adapters?: readonly IapOrderAdapter[];
   onCreate?(commerce: IapCommerce): void;
   onContent?(state: S): void;
   items(state: S): IapCatalogItem[];
@@ -15,7 +17,7 @@ export function withIapPresentation<S extends object>(options: {
   prefix: string;
 }): typeof defineService {
   return ((name: string, definition: ServiceDefinition<S>) => {
-    const commerce = createIapCommerce({ onChange: () => { void service.iapPublish(); } });
+    const commerce = createIapCommerce({ adapters: options.adapters, onChange: () => { void service.iapPublish(); } });
     options.onCreate?.(commerce);
     let items: IapCatalogItem[] = [];
     let contentVersion = 0;

package/templates/beauty-salon/tier5-src/himi-store-product/index.ts

@@ -1,7 +1,7 @@
 // Tier-5 bundle: himi-store — product detail.
 import { withIapPresentation } from "../_shared/iap-presentation.js";
-import { type IapCommerce } from "@himalaya/iap-checkout";
-import { iapPriceCopy } from "../_shared/iap-worker.js";
+import { itemPaymentEnabled, storesProductOrders, type IapCommerce, type IapPurchaseFields } from "@himalaya/iap-checkout";
+import { iapPriceCopy, iapPurchaseCopy } from "../_shared/iap-worker.js";
 import { share as shareSheet } from "@himalaya/share";
 import { addToCurrentCart, getCurrentCart } from "@himalaya/wix-ecom";
 import { get, upsert, enqueue, type DbEntity } from "@himalaya/local-db";
@@ -202,6 +202,14 @@ interface S {
   opt1Label: string; opt1Chips: OptionChip[]; opt1Selected: string[]; noOpt1: boolean;
   opt2Label: string; opt2Chips: OptionChip[]; opt2Selected: string[]; noOpt2: boolean;
   opt3Label: string; opt3Chips: OptionChip[]; opt3Selected: string[]; noOpt3: boolean;
+  /** The App Store action (`commerce.purchaseFields`), in place of Add to cart while it shows. */
+  cartHidden: boolean;
+  buyHidden: boolean;
+  buyLabel: string;
+  buyDisabled: boolean;
+  buyNote: string;
+  /** Shown once the eCom order reads paid, never on the payment's approval alone. */
+  purchasedNote: string;
 }
 
 function inputId(): string {
@@ -309,14 +317,53 @@ function derive(s: S): S {
 // read answering late — must not replace the badge the add set (#3468 review).
 let cartBadgeEpoch = 0;
 
+// A digital product with no options sells through the App Store once the platform pays for Wix
+// Stores items with wix-iap StartItemPayment (`itemPaymentEnabled`). Until then, and for any other
+// product, an App Store route only blocks the regular checkout, as before.
+const SELLS_THROUGH_APPLE = itemPaymentEnabled();
+const WIX_STORES_APP = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+const NOT_APPLE: IapPurchaseFields = { appleRoute: false, accessReady: false, buyLabel: "", buyDisabled: true, buyBusy: false, buyNote: "" };
+
 let productPricing: IapCommerce;
+let checkoutEntered = false;
 const defineService = withIapPresentation<S>({
-  onCreate: commerce => { productPricing = commerce; }, prefix: "product", transientKeys: ["price", "optionsIncomplete"], contentActions: ["load", "paintCached"],
+  adapters: SELLS_THROUGH_APPLE ? [storesProductOrders] : [],
+  onCreate: commerce => { productPricing = commerce; }, prefix: "product",
+  transientKeys: ["price", "optionsIncomplete", "cartHint", "cartHidden", "buyHidden", "buyLabel", "buyDisabled", "buyNote", "purchasedNote"], contentActions: ["load", "paintCached"],
   items: state => inputId() ? [{ reference: { kind: "storesProduct", id: inputId() }, commerceDisplayPrice: state.price }] : [],
-  present: (state, price, allowed) => ({ ...state, price: price(inputId()), optionsIncomplete: derive(state).optionsIncomplete || !allowed(inputId()) || lastProduct?.productType?.toLowerCase() === "digital",
-    cartHint: lastProduct?.productType?.toLowerCase() === "digital" || (!state.optionsUnknown && !allowed(inputId())) ? iapPriceCopy("product").purchaseUnavailable : state.cartHint === iapPriceCopy("product").purchaseUnavailable ? "" : state.cartHint }),
+  present: (state, price, allowed) => {
+    const purchase = applePurchase(state);
+    const unavailable = iapPriceCopy("product").purchaseUnavailable;
+    const blocked = lastProduct?.productType?.toLowerCase() === "digital" || (!state.optionsUnknown && !allowed(inputId()));
+    return {
+      ...state, price: price(inputId()), optionsIncomplete: derive(state).optionsIncomplete || !allowed(inputId()) || lastProduct?.productType?.toLowerCase() === "digital",
+      cartHint: !purchase.appleRoute && blocked ? unavailable : state.cartHint === unavailable ? "" : state.cartHint,
+      cartHidden: purchase.appleRoute,
+      buyHidden: !purchase.appleRoute || purchase.accessReady, buyLabel: purchase.buyLabel, buyDisabled: purchase.buyDisabled, buyNote: purchase.buyNote,
+      purchasedNote: purchase.accessReady ? copyParam("product.purchasedText", "Purchased") : "",
+    };
+  },
 });
 
+/** The App Store action, only for the one shape it sells: digital, with no options to choose, read
+ *  from the product loaded for the id on screen (as Add to cart is). A cached product whose
+ *  options were never read is not known to have none. */
+function applePurchase(state: S): IapPurchaseFields {
+  const id = inputId();
+  const loaded = !!id && lastLoadedId === id;
+  const sellable = SELLS_THROUGH_APPLE && loaded && lastProduct?.productType?.toLowerCase() === "digital" && !state.optionsUnknown && state.optionGroups.length === 0;
+  const copy = { ...iapPurchaseCopy("product"), buy: copyParam("product.buyCta", "Buy") };
+  const fields = sellable ? productPricing.purchaseFields({ kind: "storesProduct", id }, copy) : NOT_APPLE;
+  return fields.appleRoute ? fields : NOT_APPLE;
+}
+
+/** On every entry: the first starts the checkout (recovering held purchases), later ones reconcile. */
+function enterCheckout(): void {
+  if (!SELLS_THROUGH_APPLE) return;
+  void (checkoutEntered ? productPricing.reconcile() : productPricing.start());
+  checkoutEntered = true;
+}
+
 const svc = defineService<S, {
   load: (s: S, arg?: unknown) => Promise<S>;
   setQuantity: (s: S, arg?: unknown) => S;
@@ -329,6 +376,8 @@ const svc = defineService<S, {
   toggleSave: (s: S) => S;
   /** [rico] #3372 — RichContent's on_link: `{ url }` of the tapped link. */
   openLink: (s: S, arg?: unknown) => Promise<S>;
+  /** The App Store Buy: through the shared checkout, for the product on screen. */
+  buy: (s: S) => Promise<S>;
 }>("himiStoreProduct", {
   state: derive({
     status: "loading",
@@ -375,10 +424,17 @@ const svc = defineService<S, {
     opt1Label: "", opt1Chips: [], opt1Selected: [], noOpt1: true,
     opt2Label: "", opt2Chips: [], opt2Selected: [], noOpt2: true,
     opt3Label: "", opt3Chips: [], opt3Selected: [], noOpt3: true,
+    cartHidden: false,
+    buyHidden: true,
+    buyLabel: "",
+    buyDisabled: true,
+    buyNote: "",
+    purchasedNote: "",
   }),
   actions: {
     load: async (s, arg): Promise<S> => {
       stashCopy(arg);
+      enterCheckout();
       const sequence = ++productLoadSequence;
       lastProduct = undefined;
       const id = inputId();
@@ -657,6 +713,13 @@ const svc = defineService<S, {
     openLink: async (s, arg) => ((await openRichLink(arg))
       ? s
       : derive({ ...s, added: false, cartHint: copyParam("product.linkOpenFailed", "This link could not be opened.") })),
+    buy: async (s): Promise<S> => {
+      const id = inputId();
+      const purchase = applePurchase(s);
+      if (!purchase.appleRoute || purchase.buyDisabled) return s;
+      await productPricing.buy({ reference: { kind: "storesProduct", id }, catalogReference: { appId: WIX_STORES_APP, catalogItemId: id }, quantity: 1 });
+      return svc.getState() as S;
+    },
   },
 });
 

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

@@ -82885,7 +82885,55 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
               "modifiers": {
                 "cornerRadius": 8,
                 "pressFeedback": "scale",
-                "haptic": "medium"
+                "haptic": "medium",
+                "hiddenPath": "$service:himiStoreProduct.cartHidden"
+              }
+            },
+            {
+              "id": "himi_product.buy",
+              "body": {
+                "package": "himalaya",
+                "type": "Button",
+                "props": {
+                  "title": "$service:himiStoreProduct.buyLabel",
+                  "style": "primary",
+                  "fullWidth": true,
+                  "disabledPath": "$service:himiStoreProduct.buyDisabled",
+                  "action": {
+                    "actionId": "tier5.himiStoreProduct.buy"
+                  }
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiStoreProduct.buyHidden"
+              }
+            },
+            {
+              "id": "himi_product.buy_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiStoreProduct.buyNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiStoreProduct.buyHidden"
+              }
+            },
+            {
+              "id": "himi_product.purchased",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiStoreProduct.purchasedNote",
+                  "style": "footnote",
+                  "collapseWhenEmpty": true
+                }
               }
             },
             {

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

@@ -1,11 +1,13 @@
 import { defineService, type ServiceDefinition } from "@himalaya/state";
-import { createIapCommerce, type IapCommerce } from "@himalaya/iap-checkout";
+import { createIapCommerce, type IapCommerce, type IapOrderAdapter } from "@himalaya/iap-checkout";
 import { iapPriceFields, type IapCatalogItem } from "@himalaya/iap";
 import { iapPriceCopy, resetUnhydratedKeysOnOlderRuntime } from "./iap-worker.js";
 
 // Presentation only. Checkout, mapping, cache, session and refresh policy stay in the shared flow.
 export function withIapPresentation<S extends object>(options: {
   register?: typeof defineService;
+  /** The verticals this screen sells; none for a screen that only shows prices. */
+  adapters?: readonly IapOrderAdapter[];
   onCreate?(commerce: IapCommerce): void;
   onContent?(state: S): void;
   items(state: S): IapCatalogItem[];
@@ -15,7 +17,7 @@ export function withIapPresentation<S extends object>(options: {
   prefix: string;
 }): typeof defineService {
   return ((name: string, definition: ServiceDefinition<S>) => {
-    const commerce = createIapCommerce({ onChange: () => { void service.iapPublish(); } });
+    const commerce = createIapCommerce({ adapters: options.adapters, onChange: () => { void service.iapPublish(); } });
     options.onCreate?.(commerce);
     let items: IapCatalogItem[] = [];
     let contentVersion = 0;

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

@@ -1,7 +1,7 @@
 // Tier-5 bundle: himi-store — product detail.
 import { withIapPresentation } from "../_shared/iap-presentation.js";
-import { type IapCommerce } from "@himalaya/iap-checkout";
-import { iapPriceCopy } from "../_shared/iap-worker.js";
+import { itemPaymentEnabled, storesProductOrders, type IapCommerce, type IapPurchaseFields } from "@himalaya/iap-checkout";
+import { iapPriceCopy, iapPurchaseCopy } from "../_shared/iap-worker.js";
 import { share as shareSheet } from "@himalaya/share";
 import { addToCurrentCart, getCurrentCart } from "@himalaya/wix-ecom";
 import { get, upsert, enqueue, type DbEntity } from "@himalaya/local-db";
@@ -202,6 +202,14 @@ interface S {
   opt1Label: string; opt1Chips: OptionChip[]; opt1Selected: string[]; noOpt1: boolean;
   opt2Label: string; opt2Chips: OptionChip[]; opt2Selected: string[]; noOpt2: boolean;
   opt3Label: string; opt3Chips: OptionChip[]; opt3Selected: string[]; noOpt3: boolean;
+  /** The App Store action (`commerce.purchaseFields`), in place of Add to cart while it shows. */
+  cartHidden: boolean;
+  buyHidden: boolean;
+  buyLabel: string;
+  buyDisabled: boolean;
+  buyNote: string;
+  /** Shown once the eCom order reads paid, never on the payment's approval alone. */
+  purchasedNote: string;
 }
 
 function inputId(): string {
@@ -309,14 +317,53 @@ function derive(s: S): S {
 // read answering late — must not replace the badge the add set (#3468 review).
 let cartBadgeEpoch = 0;
 
+// A digital product with no options sells through the App Store once the platform pays for Wix
+// Stores items with wix-iap StartItemPayment (`itemPaymentEnabled`). Until then, and for any other
+// product, an App Store route only blocks the regular checkout, as before.
+const SELLS_THROUGH_APPLE = itemPaymentEnabled();
+const WIX_STORES_APP = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+const NOT_APPLE: IapPurchaseFields = { appleRoute: false, accessReady: false, buyLabel: "", buyDisabled: true, buyBusy: false, buyNote: "" };
+
 let productPricing: IapCommerce;
+let checkoutEntered = false;
 const defineService = withIapPresentation<S>({
-  onCreate: commerce => { productPricing = commerce; }, prefix: "product", transientKeys: ["price", "optionsIncomplete"], contentActions: ["load", "paintCached"],
+  adapters: SELLS_THROUGH_APPLE ? [storesProductOrders] : [],
+  onCreate: commerce => { productPricing = commerce; }, prefix: "product",
+  transientKeys: ["price", "optionsIncomplete", "cartHint", "cartHidden", "buyHidden", "buyLabel", "buyDisabled", "buyNote", "purchasedNote"], contentActions: ["load", "paintCached"],
   items: state => inputId() ? [{ reference: { kind: "storesProduct", id: inputId() }, commerceDisplayPrice: state.price }] : [],
-  present: (state, price, allowed) => ({ ...state, price: price(inputId()), optionsIncomplete: derive(state).optionsIncomplete || !allowed(inputId()) || lastProduct?.productType?.toLowerCase() === "digital",
-    cartHint: lastProduct?.productType?.toLowerCase() === "digital" || (!state.optionsUnknown && !allowed(inputId())) ? iapPriceCopy("product").purchaseUnavailable : state.cartHint === iapPriceCopy("product").purchaseUnavailable ? "" : state.cartHint }),
+  present: (state, price, allowed) => {
+    const purchase = applePurchase(state);
+    const unavailable = iapPriceCopy("product").purchaseUnavailable;
+    const blocked = lastProduct?.productType?.toLowerCase() === "digital" || (!state.optionsUnknown && !allowed(inputId()));
+    return {
+      ...state, price: price(inputId()), optionsIncomplete: derive(state).optionsIncomplete || !allowed(inputId()) || lastProduct?.productType?.toLowerCase() === "digital",
+      cartHint: !purchase.appleRoute && blocked ? unavailable : state.cartHint === unavailable ? "" : state.cartHint,
+      cartHidden: purchase.appleRoute,
+      buyHidden: !purchase.appleRoute || purchase.accessReady, buyLabel: purchase.buyLabel, buyDisabled: purchase.buyDisabled, buyNote: purchase.buyNote,
+      purchasedNote: purchase.accessReady ? copyParam("product.purchasedText", "Purchased") : "",
+    };
+  },
 });
 
+/** The App Store action, only for the one shape it sells: digital, with no options to choose, read
+ *  from the product loaded for the id on screen (as Add to cart is). A cached product whose
+ *  options were never read is not known to have none. */
+function applePurchase(state: S): IapPurchaseFields {
+  const id = inputId();
+  const loaded = !!id && lastLoadedId === id;
+  const sellable = SELLS_THROUGH_APPLE && loaded && lastProduct?.productType?.toLowerCase() === "digital" && !state.optionsUnknown && state.optionGroups.length === 0;
+  const copy = { ...iapPurchaseCopy("product"), buy: copyParam("product.buyCta", "Buy") };
+  const fields = sellable ? productPricing.purchaseFields({ kind: "storesProduct", id }, copy) : NOT_APPLE;
+  return fields.appleRoute ? fields : NOT_APPLE;
+}
+
+/** On every entry: the first starts the checkout (recovering held purchases), later ones reconcile. */
+function enterCheckout(): void {
+  if (!SELLS_THROUGH_APPLE) return;
+  void (checkoutEntered ? productPricing.reconcile() : productPricing.start());
+  checkoutEntered = true;
+}
+
 const svc = defineService<S, {
   load: (s: S, arg?: unknown) => Promise<S>;
   setQuantity: (s: S, arg?: unknown) => S;
@@ -329,6 +376,8 @@ const svc = defineService<S, {
   toggleSave: (s: S) => S;
   /** [rico] #3372 — RichContent's on_link: `{ url }` of the tapped link. */
   openLink: (s: S, arg?: unknown) => Promise<S>;
+  /** The App Store Buy: through the shared checkout, for the product on screen. */
+  buy: (s: S) => Promise<S>;
 }>("himiStoreProduct", {
   state: derive({
     status: "loading",
@@ -375,10 +424,17 @@ const svc = defineService<S, {
     opt1Label: "", opt1Chips: [], opt1Selected: [], noOpt1: true,
     opt2Label: "", opt2Chips: [], opt2Selected: [], noOpt2: true,
     opt3Label: "", opt3Chips: [], opt3Selected: [], noOpt3: true,
+    cartHidden: false,
+    buyHidden: true,
+    buyLabel: "",
+    buyDisabled: true,
+    buyNote: "",
+    purchasedNote: "",
   }),
   actions: {
     load: async (s, arg): Promise<S> => {
       stashCopy(arg);
+      enterCheckout();
       const sequence = ++productLoadSequence;
       lastProduct = undefined;
       const id = inputId();
@@ -657,6 +713,13 @@ const svc = defineService<S, {
     openLink: async (s, arg) => ((await openRichLink(arg))
       ? s
       : derive({ ...s, added: false, cartHint: copyParam("product.linkOpenFailed", "This link could not be opened.") })),
+    buy: async (s): Promise<S> => {
+      const id = inputId();
+      const purchase = applePurchase(s);
+      if (!purchase.appleRoute || purchase.buyDisabled) return s;
+      await productPricing.buy({ reference: { kind: "storesProduct", id }, catalogReference: { appId: WIX_STORES_APP, catalogItemId: id }, quantity: 1 });
+      return svc.getState() as S;
+    },
   },
 });
 

package/templates/community-club/tier5-src/_shared/iap-presentation.ts

@@ -1,11 +1,13 @@
 import { defineService, type ServiceDefinition } from "@himalaya/state";
-import { createIapCommerce, type IapCommerce } from "@himalaya/iap-checkout";
+import { createIapCommerce, type IapCommerce, type IapOrderAdapter } from "@himalaya/iap-checkout";
 import { iapPriceFields, type IapCatalogItem } from "@himalaya/iap";
 import { iapPriceCopy, resetUnhydratedKeysOnOlderRuntime } from "./iap-worker.js";
 
 // Presentation only. Checkout, mapping, cache, session and refresh policy stay in the shared flow.
 export function withIapPresentation<S extends object>(options: {
   register?: typeof defineService;
+  /** The verticals this screen sells; none for a screen that only shows prices. */
+  adapters?: readonly IapOrderAdapter[];
   onCreate?(commerce: IapCommerce): void;
   onContent?(state: S): void;
   items(state: S): IapCatalogItem[];
@@ -15,7 +17,7 @@ export function withIapPresentation<S extends object>(options: {
   prefix: string;
 }): typeof defineService {
   return ((name: string, definition: ServiceDefinition<S>) => {
-    const commerce = createIapCommerce({ onChange: () => { void service.iapPublish(); } });
+    const commerce = createIapCommerce({ adapters: options.adapters, onChange: () => { void service.iapPublish(); } });
     options.onCreate?.(commerce);
     let items: IapCatalogItem[] = [];
     let contentVersion = 0;

package/templates/events-meetups/tier5-src/_shared/iap-presentation.ts

@@ -1,11 +1,13 @@
 import { defineService, type ServiceDefinition } from "@himalaya/state";
-import { createIapCommerce, type IapCommerce } from "@himalaya/iap-checkout";
+import { createIapCommerce, type IapCommerce, type IapOrderAdapter } from "@himalaya/iap-checkout";
 import { iapPriceFields, type IapCatalogItem } from "@himalaya/iap";
 import { iapPriceCopy, resetUnhydratedKeysOnOlderRuntime } from "./iap-worker.js";
 
 // Presentation only. Checkout, mapping, cache, session and refresh policy stay in the shared flow.
 export function withIapPresentation<S extends object>(options: {
   register?: typeof defineService;
+  /** The verticals this screen sells; none for a screen that only shows prices. */
+  adapters?: readonly IapOrderAdapter[];
   onCreate?(commerce: IapCommerce): void;
   onContent?(state: S): void;
   items(state: S): IapCatalogItem[];
@@ -15,7 +17,7 @@ export function withIapPresentation<S extends object>(options: {
   prefix: string;
 }): typeof defineService {
   return ((name: string, definition: ServiceDefinition<S>) => {
-    const commerce = createIapCommerce({ onChange: () => { void service.iapPublish(); } });
+    const commerce = createIapCommerce({ adapters: options.adapters, onChange: () => { void service.iapPublish(); } });
     options.onCreate?.(commerce);
     let items: IapCatalogItem[] = [];
     let contentVersion = 0;