@wix/himalaya-cli 0.1243.0 → 0.1244.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/iap/src/catalog-adapters/online-programs.d.ts

@@ -0,0 +1,6 @@
+import type { IapCatalogItem } from "../catalog-pricing-contract.js";
+/** An Online Programs program as a shared IAP catalog item. A program without a Wix ID cannot be
+ *  mapped (a title fallback is not an identity), so it has no item and its screen shows no price. */
+export declare function onlineProgramItem(program: {
+    id?: string | null;
+}, commerceDisplayPrice?: string): IapCatalogItem | undefined;

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

@@ -0,0 +1,4 @@
+import type { IapItemView, IapPriceCopy, IapPriceFields } from "./catalog-pricing-contract.js";
+/** Bindable display state for one item. A screen spreads these into its own state and binds
+ *  them; the labels stay in the screen's copy pack. */
+export declare function iapPriceFields(view: IapItemView, copy: IapPriceCopy): IapPriceFields;

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

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

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

@@ -0,0 +1,10 @@
+import type { Product } from "./index.js";
+import type { IapCatalogPricing, IapMappingSource } from "./catalog-pricing-contract.js";
+/** The catalog layer with its dependencies explicit. Internal: the public factory supplies the
+ *  connected mapping source, so a screen cannot pass its own. Tests use it directly. */
+export interface IapCatalogPricingDependencies {
+    source: IapMappingSource | undefined;
+    getProducts(productIds: string[]): Promise<Product[]>;
+    onChange?(): void;
+}
+export declare function createIapCatalogPricingWith(deps: IapCatalogPricingDependencies): IapCatalogPricing;

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

@@ -0,0 +1,6 @@
+import type { IapCatalogPricing } from "./catalog-pricing-contract.js";
+/** One screen worker's catalog pricing. Activation comes only from the connected mapping
+ *  source, so a screen cannot turn Apple prices on by supplying its own mapping. */
+export declare function createIapCatalogPricing(options?: {
+    onChange?(): void;
+}): IapCatalogPricing;

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

@@ -3,6 +3,10 @@ export * from "./delivery-contract.js";
 export * from "./delivery.js";
 export * from "./pricing-contract.js";
 export * from "./pricing.js";
+export * from "./catalog-pricing-contract.js";
+export * from "./catalog-pricing.js";
+export * from "./catalog-price-fields.js";
+export * from "./catalog-adapters/online-programs.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/mapping-source.d.ts

@@ -0,0 +1,5 @@
+import type { IapMappingSource } from "./catalog-pricing-contract.js";
+/** The single activation switch for catalog pricing. No Wix→Apple mapping backend is deployed,
+ *  so every screen stays on its existing commerce flow. Only automated tests substitute this module
+ *  (at bundle-build time); the backend adapter replaces it when it exists. */
+export declare function iapMappingSource(): IapMappingSource | undefined;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/flows/checkout/src/index.d.ts

@@ -66,6 +66,9 @@ export interface PayRequest {
     currency?: string;
     /** Mints the in-app cashier URL. Called ONLY when the wallet rail cannot settle. */
     cashierUrl?: () => Promise<string | undefined>;
+    /** Re-read immediately before money moves (the wallet charge, the cashier opening). The caller's
+     *  own route can change while a rail is being chosen; false stops the flow with nothing charged. */
+    mayCharge?: () => boolean;
 }
 /**
  * Collect payment through the two sanctioned rails, in order.

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

@@ -122,12 +122,14 @@ async function entitlement() {
 async function isEntitled() {
   return (await entitlement()).entitled;
 }
+var WITHDRAWN = { kind: "failed", reason: "the caller withdrew the charge" };
 async function payOrder(req) {
   if (!req.snapshotId && !req.cashierUrl) {
     return { kind: "failed", reason: "no order to settle" };
   }
   const availability = await isAvailable().catch(() => "unavailable");
   if (availability === "full" && req.snapshotId) {
+    if (req.mayCharge?.() === false) return WITHDRAWN;
     const r = await proceedToPayment({
       appId: req.appId,
       snapshotId: req.snapshotId,
@@ -148,6 +150,7 @@ async function payOrder(req) {
   if (req.cashierUrl) {
     const url = await req.cashierUrl().catch(() => void 0);
     if (url) {
+      if (req.mayCharge?.() === false) return WITHDRAWN;
       const opened = await open(url, "in_app_browser").catch(() => ({ opened: false }));
       if (opened.opened) return { kind: "handoff" };
     }

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

@@ -648,6 +648,194 @@ var isObject2 = (value) => value !== null && typeof value === "object" && !Array
 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/catalog-pricing-contract.ts
+var IAP_CATALOG_KINDS = ["onlineProgram", "storesProduct", "pricingPlan"];
+
+// ../../core/sdk/iap/src/mapping-source.ts
+function iapMappingSource() {
+  return void 0;
+}
+
+// ../../core/sdk/iap/src/catalog-pricing-core.ts
+var POLL_ID = "iapCatalogPricing";
+var POLL_INTERVAL_MS = 6e4;
+function createIapCatalogPricingWith(deps) {
+  return deps.source ? enabledPricing(deps.source, deps) : disabledPricing();
+}
+function disabledPricing() {
+  return {
+    enabled: false,
+    load: () => Promise.resolve(),
+    refresh: () => Promise.resolve(),
+    view: disabledView,
+    checkoutGuard: (reference) => decisionOf(disabledView(reference)),
+    continueCheckoutGuard: (reference) => decisionOf(disabledView(reference)),
+    pollDirective: () => void 0,
+    dispose: () => {
+    }
+  };
+}
+function enabledPricing(source, deps) {
+  let controller;
+  let disposed = false;
+  const settled = /* @__PURE__ */ new Map();
+  let settledScope = "";
+  const rememberSettled = (state) => {
+    const scopeKey = JSON.stringify(state.scope);
+    if (scopeKey !== settledScope) {
+      settled.clear();
+      settledScope = scopeKey;
+    }
+    for (const item of state.items) {
+      const answered = viewOf(item.reference, item);
+      if (!unanswered(answered)) settled.set(referenceKey(item.reference), answered);
+    }
+  };
+  let lookupRevision = 0;
+  let answeredRoutes;
+  const mapping = {
+    resolve: async (request) => {
+      const asked = lookupRevision;
+      const answer = await source.mapping.resolve(request);
+      if (asked === lookupRevision) answeredRoutes = routesAnswered(answer);
+      return answer;
+    }
+  };
+  const trackLookup = (state) => {
+    if (state.revision !== lookupRevision) {
+      lookupRevision = state.revision;
+      answeredRoutes = void 0;
+    }
+  };
+  const ensureController = () => controller ?? (controller = createPricingController({
+    mapping,
+    getProducts: deps.getProducts,
+    onState: (state) => {
+      trackLookup(state);
+      rememberSettled(state);
+      deps.onChange?.();
+    }
+  }));
+  const view = (reference) => disposed ? blockedView(reference, "unavailable") : viewOf(reference, controller && itemFor(controller.getState().items, reference));
+  const continueCheckoutGuard = (reference) => {
+    const current = view(reference);
+    if (!unanswered(current)) return decisionOf(current);
+    if (answeredRoutes) return routeDecision(answeredRoutes.get(referenceKey(reference)) ?? "unavailable");
+    return decisionOf(settled.get(referenceKey(reference)) ?? current);
+  };
+  return {
+    enabled: true,
+    load: (input) => disposed ? Promise.resolve() : ensureController().load(pricingInput(input, source)),
+    refresh: () => controller?.refresh() ?? Promise.resolve(),
+    view,
+    checkoutGuard: (reference) => decisionOf(view(reference)),
+    continueCheckoutGuard,
+    pollDirective: (action) => ({ id: POLL_ID, action, intervalMs: POLL_INTERVAL_MS, immediate: true }),
+    dispose: () => {
+      disposed = true;
+      settled.clear();
+      controller?.dispose();
+    }
+  };
+}
+function pricingInput(input, source) {
+  return { scope: pricingScope(input.scope, source.siteId), platform: input.platform, items: input.items };
+}
+function pricingScope(scope, boundSiteId) {
+  return {
+    appId: scope.appId,
+    bundleId: scope.bundleId,
+    siteId: siteIdFor(scope.siteId, boundSiteId),
+    ...scope.contextRevision === void 0 ? {} : { contextRevision: scope.contextRevision }
+  };
+}
+function siteIdFor(callerSiteId, boundSiteId) {
+  if (callerSiteId && boundSiteId && callerSiteId !== boundSiteId) return "";
+  return callerSiteId || boundSiteId || "";
+}
+var referenceKey = (reference) => JSON.stringify([reference.kind, reference.id]);
+function routesAnswered(answer) {
+  const routes = /* @__PURE__ */ new Map();
+  for (const entry of Array.isArray(answer) ? answer : []) {
+    const reference = entry?.reference;
+    if (typeof reference?.kind !== "string" || typeof reference.id !== "string") continue;
+    const key = referenceKey(reference);
+    const route = entry.route;
+    routes.set(key, routes.has(key) ? "unavailable" : route === "regular" || route === "appleIap" ? route : "unavailable");
+  }
+  return routes;
+}
+function routeDecision(route) {
+  return { allowed: route === "regular", route };
+}
+function unanswered(view) {
+  return view.route === "resolving" || view.reason === "mappingUnavailable";
+}
+function itemFor(items, reference) {
+  return items.find((item) => item.reference.kind === reference.kind && item.reference.id === reference.id);
+}
+function viewOf(reference, item) {
+  if (!item || item.status === "loading") return blockedView(reference, "resolving");
+  if (item.status === "ready") return readyView(reference, item);
+  return unavailableView(reference, item);
+}
+function readyView(reference, item) {
+  return item.source === "appleIap" ? { ...blockedView(reference, "appleIap"), displayPrice: item.displayPrice } : { ...regularView(reference), displayPrice: item.displayPrice };
+}
+function unavailableView(reference, item) {
+  if (item.reason === "commercePriceUnavailable") return regularView(reference);
+  return { ...blockedView(reference, "unavailable"), reason: item.reason, retryable: item.retryable };
+}
+function blockedView(reference, route) {
+  return { reference: { kind: reference.kind, id: reference.id }, route, displayPrice: "", retryable: false, canStartRegularCheckout: false, purchasable: false };
+}
+function regularView(reference) {
+  return { ...blockedView(reference, "regular"), canStartRegularCheckout: true };
+}
+function disabledView(reference) {
+  return { ...blockedView(reference, "disabled"), canStartRegularCheckout: true };
+}
+function decisionOf(view) {
+  return { allowed: view.canStartRegularCheckout, route: view.route };
+}
+
+// ../../core/sdk/iap/src/catalog-pricing.ts
+function createIapCatalogPricing(options = {}) {
+  return createIapCatalogPricingWith({ source: iapMappingSource(), getProducts, onChange: options.onChange });
+}
+
+// ../../core/sdk/iap/src/catalog-price-fields.ts
+function iapPriceFields(view, copy) {
+  const fields = {
+    priceText: "",
+    priceNote: "",
+    priceLoading: false,
+    hidePriceRetry: true,
+    actionDisabled: !view.canStartRegularCheckout,
+    actionNote: ""
+  };
+  switch (view.route) {
+    case "resolving":
+      return { ...fields, priceText: copy.loading, priceLoading: true };
+    case "appleIap":
+      return { ...fields, priceText: view.displayPrice, priceNote: copy.oneTimePurchase, actionNote: copy.purchaseUnavailable };
+    case "unavailable":
+      return { ...fields, priceText: copy.unavailable, hidePriceRetry: !view.retryable };
+    case "regular":
+      return { ...fields, priceText: view.displayPrice };
+    case "disabled":
+      return fields;
+  }
+}
+
+// ../../core/sdk/iap/src/catalog-adapters/online-programs.ts
+var ONLINE_PROGRAM = "onlineProgram";
+function onlineProgramItem(program, commerceDisplayPrice) {
+  const id = program.id;
+  if (typeof id !== "string" || !id.trim()) return void 0;
+  return { reference: { kind: ONLINE_PROGRAM, id }, ...commerceDisplayPrice ? { commerceDisplayPrice } : {} };
+}
+
 // ../../core/sdk/iap/src/index.ts
 async function getPaywallConfig() {
   const r = await dispatch("capability.iap.getPaywallConfig");
@@ -742,10 +930,12 @@ function decodeTransaction(value) {
   return { store, signedTransaction, transactionId, originalTransactionId, productId, appAccountToken, environment };
 }
 export {
+  IAP_CATALOG_KINDS,
   MAX_AUTOMATIC_ATTEMPTS,
   MAX_RETRY_DELAY_MS,
   appleManagedStore,
   consume,
+  createIapCatalogPricing,
   createPricingController,
   createPurchaseCoordinator,
   entitlements,
@@ -753,6 +943,8 @@ export {
   getPaywallConfig,
   getProducts,
   getUnfinishedTransactions,
+  iapPriceFields,
+  onlineProgramItem,
   purchase,
   purchaseForVerification,
   restore,

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

@@ -220,12 +220,14 @@ async function entitlement() {
     return { entitled: false, planName: "", planId: "" };
   }
 }
+var WITHDRAWN = { kind: "failed", reason: "the caller withdrew the charge" };
 async function payOrder(req) {
   if (!req.snapshotId && !req.cashierUrl) {
     return { kind: "failed", reason: "no order to settle" };
   }
   const availability = await isAvailable().catch(() => "unavailable");
   if (availability === "full" && req.snapshotId) {
+    if (req.mayCharge?.() === false) return WITHDRAWN;
     const r = await proceedToPayment({
       appId: req.appId,
       snapshotId: req.snapshotId,
@@ -246,6 +248,7 @@ async function payOrder(req) {
   if (req.cashierUrl) {
     const url = await req.cashierUrl().catch(() => void 0);
     if (url) {
+      if (req.mayCharge?.() === false) return WITHDRAWN;
       const opened = await open(url, "in_app_browser").catch(() => ({ opened: false }));
       if (opened.opened) return { kind: "handoff" };
     }

package/dist/cli.mjs

@@ -25748,6 +25748,7 @@ function shouldRevealError(args) {
 var EMAIL_RE, URL_HOST_RE, INTEGER_RE, NUMBER_RE;
 var init_validation = __esm({
   "../../core/ts/src/validation.ts"() {
+    "use strict";
     EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
     URL_HOST_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$/;
     INTEGER_RE = /^[+-]?[0-9]+$/;
@@ -26407,6 +26408,7 @@ function validateWorkerSubtree(raw, slotId, policy, actionCatalog) {
 var WORKER_SUBTREE_CEILINGS, ID_PART, ACTION_ID;
 var init_worker_subtree = __esm({
   "../../core/ts/src/worker-subtree.ts"() {
+    "use strict";
     init_worker_subtree_safe_types_generated();
     WORKER_SUBTREE_CEILINGS = Object.freeze({
       maxEncodedBytes: 65536,

package/guides/getting-started.md

@@ -218,6 +218,12 @@ mapper writes the site's light colour into the dark arm too, so dark mode is whe
 To create/publish/invoke the site's Velo HTTP functions, `himi docs wix-site-http-functions`
 and `himi site function` (not analyze, and not `himi functions`).
 
+**Selling digital items** (programs, products, plans the owner registered with `himi store iap`)?
+Any screen that shows such an item's price — a template screen or one you write — gets its App
+Store price and payment route from the shared `createIapCatalogPricing` in `@himalaya/iap`:
+read `himi docs iap-pricing` before writing the worker. Starting from a template does not cover
+your own screens; each screen opts in explicitly.
+
 After `himi init … --template branded-lite` (or a vertical overlay), **point the app at your
 Wix site** before expecting live catalog data:
 

package/guides/himi-skill.md

@@ -247,6 +247,12 @@ mapper writes the site's light colour into the dark arm too, so dark mode is whe
 To create/publish/invoke the site's Velo HTTP functions, `himi docs wix-site-http-functions`
 and `himi site function` (not analyze, and not `himi functions`).
 
+**Selling digital items** (programs, products, plans the owner registered with `himi store iap`)?
+Any screen that shows such an item's price — a template screen or one you write — gets its App
+Store price and payment route from the shared `createIapCatalogPricing` in `@himalaya/iap`:
+read `himi docs iap-pricing` before writing the worker. Starting from a template does not cover
+your own screens; each screen opts in explicitly.
+
 After `himi init … --template branded-lite` (or a vertical overlay), **point the app at your
 Wix site** before expecting live catalog data: