@wix/himalaya-cli 0.1242.0 → 0.1244.0

package/guides/wix-api-usage.md

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1242.0",
+  "version": "0.1244.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": "b728c51ecb462034dd49f5a7e49e7f41069407835c052e156ff4d7ea"
+  "falconPackageHash": "724b558d0195cae181956a174fc05420e13df2e99fb9a25e2f69b016"
 }

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

@@ -22173,6 +22173,65 @@ const SCREENS = runtimeSetting({
                 "hiddenPath": "$service:himiBrandedPrograms.notErrored"
               }
             },
+            {
+              "id": "himi_programs.price_retry_card",
+              "body": {
+                "package": "himalaya",
+                "type": "VStack",
+                "props": {
+                  "spacing": 8,
+                  "alignment": "leading",
+                  "children": [
+                    {
+                      "id": "himi_programs.price_retry_text",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "$service:himiBrandedPrograms.priceRetryText",
+                          "style": "footnote",
+                          "color": "textSecondary",
+                          "collapseWhenEmpty": true
+                        }
+                      }
+                    },
+                    {
+                      "id": "himi_programs.price_retry",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Button",
+                        "props": {
+                          "title": "Try again",
+                          "style": "secondary",
+                          "action": {
+                            "actionId": "tier5.himiBrandedPrograms.pricingRefresh"
+                          }
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "modifiers": {
+                "background": {
+                  "token": "surfaceElevated"
+                },
+                "border": {
+                  "width": 1,
+                  "color": {
+                    "token": "border"
+                  }
+                },
+                "cornerRadius": 16,
+                "padding": {
+                  "leading": 16,
+                  "trailing": 16,
+                  "top": 16,
+                  "bottom": 16
+                },
+                "hiddenPath": "$service:himiBrandedPrograms.hidePriceRetry"
+              }
+            },
             {
               "id": "himi_programs.rows.collection.toolbar",
               "body": {
@@ -24525,7 +24584,9 @@ const SCREENS = runtimeSetting({
       "integrity": "",
       "contentType": "application/javascript+ts-bundle",
       "declaredCapabilities": [
-        "wix_api"
+        "wix_api",
+        "iap",
+        "app_info"
       ],
       "minBinaryVersion": "0.1.0",
       "bundleVersion": "0.0.1"
@@ -84141,7 +84202,7 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                       }
                     },
                     {
-                      "id": "",
+                      "id": "himi_program.price",
                       "body": {
                         "package": "himalaya",
                         "type": "Text",
@@ -84153,6 +84214,36 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                         }
                       }
                     },
+                    {
+                      "id": "himi_program.price_note",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "$service:himiBrandedProgram.priceNote",
+                          "style": "caption",
+                          "color": "textSecondary",
+                          "collapseWhenEmpty": true
+                        }
+                      }
+                    },
+                    {
+                      "id": "himi_program.price_retry",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Button",
+                        "props": {
+                          "title": "Try again",
+                          "style": "secondary",
+                          "action": {
+                            "actionId": "tier5.himiBrandedProgram.pricingRefresh"
+                          }
+                        }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiBrandedProgram.hidePriceRetry"
+                      }
+                    },
                     {
                       "id": "",
                       "body": {
@@ -84207,12 +84298,26 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                           "title": "Enrol",
                           "style": "primary",
                           "fullWidth": true,
+                          "disabledPath": "$service:himiBrandedProgram.enrollDisabled",
                           "action": {
                             "actionId": "tier5.himiBrandedProgram.enroll"
                           }
                         }
                       }
                     },
+                    {
+                      "id": "himi_program.enrol_note",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "$service:himiBrandedProgram.enrollNote",
+                          "style": "footnote",
+                          "color": "textSecondary",
+                          "collapseWhenEmpty": true
+                        }
+                      }
+                    },
                     {
                       "id": "himi_program.action_message",
                       "body": {
@@ -84352,7 +84457,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
         "wix_api",
         "wix_cashier",
         "open_url",
-        "wix_platform"
+        "wix_platform",
+        "iap",
+        "app_info"
       ],
       "minBinaryVersion": "0.1.0",
       "bundleVersion": "0.0.1"

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

@@ -0,0 +1,65 @@
+// 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";
+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 {
+    loading: copyParam(`${prefix}.priceLoadingText`, "Loading price…"),
+    unavailable: copyParam(`${prefix}.priceUnavailableText`, "Price unavailable"),
+    oneTimePurchase: copyParam(`${prefix}.oneTimePurchaseLabel`, "One-time purchase"),
+    purchaseUnavailable: copyParam(`${prefix}.purchaseUnavailableText`, "Purchasing is not available yet."),
+  };
+}
+
+/** 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. */
+export function resetUnhydratedKeysOnOlderRuntime<S extends object>(svc: { getState(): S }, declared: S, keys: readonly (keyof S & string)[]): void {
+  if ((globalThis as { himalaya?: { hydrationOptOut?: unknown } }).himalaya?.hydrationOptOut === true) return;
+  const booted = svc.getState();
+  if (!booted || typeof booted !== "object") return;
+  for (const key of keys) booted[key] = declared[key];
+}

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

@@ -13,6 +13,9 @@
 // PAYMENT_PENDING and settles on the shared in-app pay rail, and a private one comes
 // 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.
 import { defineService } from "@himalaya/state";
 import {
   getProgram,
@@ -28,6 +31,8 @@ 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";
 
 /** Wix Online Programs appDefId — the vertical a participant's cashier order is
  *  paid under (mirrors AppDefId.CHALLENGES in Wix's RN apps). */
@@ -55,6 +60,13 @@ interface State {
   hasImage: boolean;
   noImage: boolean;
   hideContent: boolean;
+  /** "One-time purchase" beside an App Store price. */
+  priceNote: string;
+  hidePriceRetry: boolean;
+  /** Bound to the Enrol CTA's `disabledPath`; `enroll` re-checks the route itself regardless. */
+  enrollDisabled: boolean;
+  enrollNote: string;
+  _poll?: IapPollDirective;
 }
 
 function inputId(): string {
@@ -149,45 +161,65 @@ function ready(state: State, p: WixProgram | undefined): State {
   });
 }
 
+/** §8.10 drift discipline: getProgram is the primary read; when the GET path 404s/errors the
+ *  programs QUERY is the fallback (client-side find keeps it correct even when the gateway ignores
+ *  the filter shape). Throws only when both fail. */
+async function fetchProgram(id: string): Promise<WixProgram | undefined> {
+  if (!id) return undefined;
+  try {
+    return (await getProgram(id)).program;
+  } catch {
+    const response = await queryPrograms({ cursorPaging: { limit: 50 } });
+    return (response.programs ?? []).find((candidate) => candidate.id === id);
+  }
+}
+
 async function load(state: State, arg?: unknown): Promise<State> {
   stashCopy(arg);
-  const id = inputId();
-  if (!id) return ready(state, undefined);
   try {
-    const response = await getProgram(id);
-    return ready(state, response.program);
+    return ready(state, await fetchProgram(inputId()));
   } catch {
-    // Drifted GET path / transient failure → the query fallback. Client-side
-    // find keeps this correct even when the gateway ignores the filter shape.
-    try {
-      const response = await queryPrograms({ cursorPaging: { limit: 50 } });
-      return ready(state, (response.programs ?? []).find((candidate) => candidate.id === id));
-    } catch {
-      return derive({ ...state, status: "error" });
-    }
+    return derive({ ...state, status: "error" });
   }
 }
 
-async function enroll(state: State): Promise<State> {
-  const id = inputId();
-  if (!id) return state;
+/** 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 {
+  mayStart(): boolean;
+  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();
   try {
-    const joined = await joinProgram(id);
+    const joined = await joinProgram(inputId());
     const participant = joined.participant;
     const programState = (participant?.state ?? "").toUpperCase();
     if (programState === "APPROVAL_PENDING") {
-      return derive({ ...state, actionMessage: copyParam("program.approvalPendingMessage", "Request sent — the host will approve your place.") });
+      return copyParam("program.approvalPendingMessage", "Request sent — the host will approve your place.");
     }
     const payable = payableIdOf(participant);
     if (!payable) {
       // Free / open program (or one already settled) ⇒ nothing to charge.
-      return derive({ ...state, actionMessage: copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name: state.name }) });
+      return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     }
     const msid = await wixPlatformSession.signedInstanceStatus().then((s) => s.msid ?? "").catch(() => "");
+    // Re-read before each step that commits money: a route that settles meanwhile wins.
+    let withdrawn = false;
+    const stillAllowed = () => {
+      if (!guards.mayContinue()) withdrawn = true;
+      return !withdrawn;
+    };
+    if (!stillAllowed()) return blocked();
     const pay = await payCashierOrder({
       appId: WIX_PROGRAMS_APP_ID,
       snapshotId: payable,
       msid,
+      mayCharge: stillAllowed,
       // Wallet-less apps need a rail too. Without this thunk a paid program was
       // unpayable on any app with no provisioned wallet — `payCashierOrder`
       // returned `failed` and the CTA fell through to the site-directing message,
@@ -201,6 +233,7 @@ async function enroll(state: State): Promise<State> {
       // message as before, and nothing regresses — but when it is right, a
       // wallet-less site can actually sell the program IN-APP.
       cashierUrl: async () => {
+        if (!stillAllowed()) return undefined;
         const redirect = await createRedirectSession({
           ecomOrderPaymentRequest: { paymentRequestId: payable },
           callbacks: { postFlowUrl: "himalaya-himi-branded-lite://screen/himi_programs" },
@@ -208,43 +241,137 @@ async function enroll(state: State): Promise<State> {
         return redirect.redirectSession?.fullUrl;
       },
     });
-    if (pay.kind === "paid") {
-      return derive({ ...state, actionMessage: copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name: state.name }) });
-    }
-    if (pay.kind === "handoff") return derive({ ...state, actionMessage: "" });
-    if (pay.kind === "cancelled") {
-      return derive({ ...state, actionMessage: copyParam("program.joinCancelledMessage", "Payment cancelled — you haven't enrolled.") });
-    }
+    if (withdrawn) return blocked();
+    if (pay.kind === "paid") return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
+    if (pay.kind === "handoff") return "";
+    if (pay.kind === "cancelled") return copyParam("program.joinCancelledMessage", "Payment cancelled — you haven't enrolled.");
   } catch {
     // fall through to the site-directing message
   }
-  return derive({ ...state, actionMessage: copyTemplate("program.joinOnSiteMessage", "Enrolment happens on the website — visit the site to join {name}.", { name: state.name }) });
-}
-
-const svc = defineService<State, {
-  load: (state: State, arg?: unknown) => Promise<State>;
-  enroll: (state: State) => Promise<State>;
-}>("himiBrandedProgram", {
-  state: derive({
-    status: "loading",
-    actionMessage: "",
-    name: "",
-    description: "",
-    meta: "",
-    priceLine: "",
-    image: "",
-    initial: "",
-    emptyText: copyParam("program.emptyText", "This program is no longer available."),
-    isLoading: true,
-    notLoading: false,
-    isErrored: false,
-    notErrored: true,
-    noEmpty: true,
-    hasImage: false,
-    noImage: true,
-    hideContent: true,
-  }),
-  actions: { load, enroll },
+  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) ─────
+//
+// 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.
+
+const pricing = createIapCatalogPricing({ onChange: () => { void svc.pricingPublish(); } });
+const PRICING_NOT_HYDRATED = ["priceLine", "priceNote", "hidePriceRetry", "enrollDisabled", "enrollNote"] 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: "" };
+let content: Content;
+let pricedItem: IapCatalogItem | undefined;
+let scopeIncomplete = false;
+let actionMessage = "";
+let loadSeq = 0;
+
+function contentOf(state: State): Content {
+  return Object.fromEntries(CONTENT_KEYS.map((key) => [key, state[key]])) as Content;
+}
+
+const programReference = () => onlineProgramItem({ id: inputId() })?.reference;
+
+async function loadPriced(state: State, arg?: unknown): Promise<undefined> {
+  stashCopy(arg);
+  const seq = ++loadSeq;
+  const found = await fetchProgram(inputId()).then((program) => ({ program }), () => undefined);
+  if (seq !== loadSeq) return undefined;
+  content = found ? contentOf(ready(state, found.program)) : { ...content, status: "error" };
+  pricedItem = found?.program ? onlineProgramItem({ id: inputId() }, priceOf(found.program)) : pricedItem;
+  void svc.pricingPublish();
+  if (found?.program) void priceProgram();
+  return undefined;
+}
+
+/** 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] });
+}
+
+async function enrollPriced(): 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
+  // App Store, and the screen already reads "Loading price…" with Enrol disabled.
+  actionMessage = pricing.checkoutGuard(reference).route === "resolving" ? "" : await enrollmentMessage(content.name, {
+    mayStart: () => pricing.checkoutGuard(reference).allowed,
+    mayContinue: () => pricing.continueCheckoutGuard(reference).allowed,
+  });
+  void svc.pricingPublish();
+  return undefined;
+}
+
+function pricedState(state: State): State {
+  const reference = programReference();
+  const price = reference ? iapPriceFields(pricing.view(reference), iapPriceCopy("program")) : NO_PRICE;
+  return derive({
+    ...state, ...content, actionMessage,
+    priceLine: price.priceText, priceNote: price.priceNote, hidePriceRetry: price.hidePriceRetry && !scopeIncomplete,
+    enrollDisabled: price.actionDisabled, enrollNote: price.actionNote,
+  });
+}
+
+const INITIAL_STATE: State = derive({
+  status: "loading",
+  actionMessage: "",
+  name: "",
+  description: "",
+  meta: "",
+  priceLine: "",
+  image: "",
+  initial: "",
+  emptyText: copyParam("program.emptyText", "This program is no longer available."),
+  isLoading: true,
+  notLoading: false,
+  isErrored: false,
+  notErrored: true,
+  noEmpty: true,
+  hasImage: false,
+  noImage: true,
+  hideContent: true,
+  priceNote: "",
+  hidePriceRetry: true,
+  enrollDisabled: pricing.enabled,
+  enrollNote: "",
 });
 
+type Actions = {
+  load: (state: State, arg?: unknown) => Promise<State | undefined>;
+  enroll: (state: State) => Promise<State | undefined>;
+  pricingPublish: (state: State) => State;
+  pricingStart: (state: State) => State;
+  pricingRefresh: (state: State) => Promise<undefined>;
+};
+
+const svc = defineService<State, Actions>("himiBrandedProgram", {
+  state: INITIAL_STATE,
+  ...(pricing.enabled ? { notHydrated: [...PRICING_NOT_HYDRATED] } : {}),
+  actions: {
+    load: pricing.enabled ? loadPriced : load,
+    enroll: pricing.enabled ? enrollPriced : enroll,
+    pricingPublish: pricedState,
+    pricingStart: (state) => ({ ...pricedState(state), _poll: pricing.pollDirective("himiBrandedProgram.pricingRefresh") }),
+    pricingRefresh: async () => { await priceProgram(); return undefined; },
+  },
+});
+
+content = contentOf(svc.getState());
+if (pricing.enabled) {
+  resetUnhydratedKeysOnOlderRuntime(svc, INITIAL_STATE, PRICING_NOT_HYDRATED);
+  void svc.pricingStart();
+}
+
 export { svc };