@wix/himalaya-cli 0.1614.0 → 0.1616.0

package/templates/salon-spa/tier5-src/_shared/hosted-checkout.ts

@@ -0,0 +1,70 @@
+// Hosted checkout. A Branded Lite hosted in a host shell (Spaces) pays as the member the host
+// lent it: Headless `createRedirectSession` does not take a Member instance, so the HOST opens the site's
+// checkout signed in as that member. The worker names only its ecom checkout; the host reads Wix's
+// checkout URL, mints a one-time member session and opens the site's `createSessionCookie` → checkout.
+// The session token never reaches this worker.
+//
+// Classic Wix Events tickets and classic Pricing Plans have no ecom checkout: for those the
+// worker names the page by id (`himi.host.memberSitePage`) and the host opens the site's own event or
+// plans page the same way, signed in — where the member picks and pays on the site. A member's orders
+// are the same (Wix lists them to no member identity), so My orders opens the site's own page too.
+
+import { dispatch } from "@himalaya/dispatch";
+import { hostSiteFromInput } from "./branded-lite-hosted.js";
+
+/** The host verbs (registered by the host shell, never by the app itself). The first prepares the
+ *  checkout and answers a one-time ticket; the second opens it. Two steps so the caller's charge guard
+ *  is re-read after the host's network round trips and right before the checkout opens — the prepared
+ *  URL (which carries the member's session token) stays in the host; only the ticket crosses here. */
+export const HOSTED_CHECKOUT_ACTION = "himi.host.memberCheckout";
+export const HOSTED_CHECKOUT_OPEN_ACTION = "himi.host.memberCheckout.open";
+/** Prepares a site PAGE (not an ecom checkout) the same way; opened with [HOSTED_CHECKOUT_OPEN_ACTION]. */
+export const HOSTED_SITE_PAGE_ACTION = "himi.host.memberSitePage";
+
+/** A site page a hosted worker may ask its host for — ids only, never a URL: the host reads the URL
+ *  from Wix itself and decides whether the member may be signed in there. */
+export type HostedSitePage = { page: "event"; eventId: string } | { page: "plans"; planId?: string } | { page: "orders" };
+
+/** Whether this worker runs inside a host that opened a site for it. */
+export function isHostedWorker(): boolean {
+  return hostSiteFromInput((globalThis as { himalaya?: { input?: unknown } }).himalaya?.input) !== null;
+}
+
+type HostAnswer = { opened?: unknown; ticket?: unknown; payload?: { opened?: unknown; ticket?: unknown } } | null;
+type HostOpener = (stillMayCharge: () => Promise<boolean>) => Promise<boolean | "withdrawn">;
+
+/** Prepare with [action] [params] → re-read the guard → open by ticket. A host without the verbs, or one
+ *  that refused (Wix named no page, an unsafe URL, no account session), → false, never a throw. */
+function hostOpener(action: string, params: Record<string, string>): HostOpener {
+  return async (stillMayCharge) => {
+    try {
+      const prepared = await dispatch(action, params) as HostAnswer;
+      const ticket = prepared?.ticket ?? prepared?.payload?.ticket;
+      if (typeof ticket !== "string" || !ticket) return false;
+      // An unopened ticket simply expires in the host: nothing to cancel.
+      if (!(await stillMayCharge())) return "withdrawn";
+      const result = await dispatch(HOSTED_CHECKOUT_OPEN_ACTION, { ticket }) as HostAnswer;
+      const opened = result?.opened ?? result?.payload?.opened;
+      return opened === true || opened === "true";
+    } catch {
+      return false;
+    }
+  };
+}
+
+/** `payCashierOrder`'s `openCashier` for a hosted app: the host prepares [checkoutId]'s checkout as the
+ *  lent member, the caller's guard is re-read, and only then does the host open it. Resolves whether it
+ *  opened ("withdrawn" when the guard said no); a host without the verbs (or that refused) → false. */
+export function hostedCheckoutOpener(checkoutId: string): HostOpener {
+  return hostOpener(HOSTED_CHECKOUT_ACTION, { checkoutId });
+}
+
+/** The site's own [page] opened by the host, signed in as the lent member where the host deems it safe
+ *  (a visitor otherwise) — the same two steps and answers as [hostedCheckoutOpener]. */
+export function hostedSitePageOpener(page: HostedSitePage): HostOpener {
+  const params: Record<string, string> = page.page === "event"
+    ? { page: "event", eventId: page.eventId }
+    : page.page === "orders" ? { page: "orders" }
+    : { page: "plans", ...(page.planId ? { planId: page.planId } : {}) };
+  return hostOpener(HOSTED_SITE_PAGE_ACTION, params);
+}

package/templates/salon-spa/tier5-src/_shared/iap-attendance-form.ts

@@ -0,0 +1,106 @@
+import { copyParam } from "./himi-copy.js";
+
+export interface AttendanceField {
+  id: string;
+  label: string;
+  kind: string;
+  required: boolean;
+  value: string;
+  selectedIds: string[];
+  options: { id: string; label: string }[];
+  error: string;
+  maxLength?: number;
+  maxSize?: number;
+}
+
+const object = (v: unknown): Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v) ? v as Record<string, unknown> : {};
+const text = (v: unknown): string => typeof v === "string" ? v : "";
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export function createAttendanceForm(prefix: string) {
+  let fields: AttendanceField[] = [];
+  let supported = false;
+  const label = (name: string) => copyParam(`${prefix}.${name}Label`, name === "firstName" ? "First name" : name === "lastName" ? "Last name" : "Email");
+  const field = (scope: string, name: string, input: Record<string, unknown> = {}): AttendanceField => ({
+    id: `${scope}:${name}`, label: text(input.label) || label(name), required: input.mandatory === true,
+    kind: name === "email" ? "email" : input.type === "NUMBER" ? "number" : input.type === "TEXT_ARRAY" ? "multiple" : Array.isArray(input.options) && input.options.length ? "choice" : "text",
+    value: "", selectedIds: [], error: "",
+    options: Array.isArray(input.options) ? input.options.filter((o): o is string => typeof o === "string").map((o) => ({ id: o, label: o })) : [],
+    ...(typeof input.maxLength === "number" ? { maxLength: input.maxLength } : {}),
+    ...(typeof input.maxSize === "number" ? { maxSize: input.maxSize } : {}),
+  });
+  const contact = (scope: string) => ["firstName", "lastName", "email"].map((name) => field(scope, name, { mandatory: true }));
+
+  function event(raw: unknown): void {
+    fields = contact("buyer");
+    const controls = object(raw).controls;
+    supported = Array.isArray(controls) && controls.length > 0;
+    const names = new Set<string>();
+    for (const control of Array.isArray(controls) ? controls : []) {
+      const c = object(control);
+      if (c.deleted === true) continue;
+      if (!Array.isArray(c.inputs) || !c.inputs.length) { supported = false; continue; }
+      for (const rawInput of c.inputs) {
+        const input = object(rawInput);
+        const name = text(input.name);
+        if (!name || names.has(name) || !["TEXT", "NUMBER", "TEXT_ARRAY"].includes(text(input.type)) || (input.type === "TEXT_ARRAY" && (!Array.isArray(input.options) || !input.options.length))) { supported = false; continue; }
+        names.add(name);
+        fields.push(field("guest", name, { ...input, mandatory: input.mandatory === true || ["firstName", "lastName", "email"].includes(name) }));
+      }
+    }
+    if (!["firstName", "lastName", "email"].every((name) => names.has(name))) supported = false;
+  }
+
+  function booking(service: unknown): void {
+    fields = contact("buyer");
+    const id = text(object(object(service).form).id);
+    // Custom intake schemas need their own reader; never silently omit their required fields.
+    supported = id === "00000000-0000-0000-0000-000000000000";
+  }
+
+  function change(arg: unknown): void {
+    const a = object(arg);
+    const f = fields.find((candidate) => candidate.id === a.id);
+    if (!f) return;
+    if (typeof a.option === "string") {
+      if (f.kind === "multiple") f.selectedIds = f.selectedIds.includes(a.option) ? f.selectedIds.filter((v) => v !== a.option) : [...f.selectedIds, a.option];
+      else f.value = a.option;
+      f.error = "";
+      return;
+    }
+    f.value = text(a.value ?? a.text ?? a.selectedId);
+    f.selectedIds = Array.isArray(a.selectedIds) ? a.selectedIds.filter((v): v is string => typeof v === "string") : [];
+    f.error = "";
+  }
+
+  function valid(f: AttendanceField): boolean {
+    const value = f.value.trim();
+    const values = f.kind === "multiple" ? f.selectedIds : value ? [value] : [];
+    if (!values.length) return !f.required;
+    if (f.options.length && values.some((v) => !f.options.some((o) => o.id === v))) return false;
+    if (f.maxSize !== undefined && values.length > f.maxSize) return false;
+    if (f.maxLength !== undefined && values.some((v) => v.length > f.maxLength!)) return false;
+    return f.kind === "email" ? EMAIL.test(value) : f.kind !== "number" || /^-?\d+(?:\.\d+)?$/.test(value);
+  }
+
+  function validate(): boolean {
+    for (const f of fields) f.error = valid(f) ? "" : copyParam(`${prefix}.formInvalidText`, "Check this field.");
+    return supported && fields.every((f) => !f.error);
+  }
+
+  function buyer(): Record<string, string> {
+    return Object.fromEntries(fields.filter((f) => f.id.startsWith("buyer:")).map((f) => [f.id.slice(6), f.value.trim()]));
+  }
+
+  function ticket(definitionId: string) {
+    const inputValues = fields.filter((f) => f.id.startsWith("guest:") && (f.value.trim() || f.selectedIds.length)).map((f) => ({ inputName: f.id.slice(6), ...(f.kind === "multiple" ? { values: f.selectedIds.slice() } : { value: f.value.trim() }) }));
+    return { buyer: buyer(), guests: [{ ticketDefinitionId: definitionId, form: { inputValues } }] };
+  }
+
+  return {
+    event, booking, change, validate, buyer, ticket,
+    supported: () => supported,
+    rows: () => fields.map((f) => ({ ...f, selectedIds: f.selectedIds.slice(), kind: f.kind === "text" && f.required ? "requiredText" : f.kind })),
+    clear: () => { for (const f of fields) { f.value = ""; f.selectedIds = []; f.error = ""; } },
+  };
+}

package/templates/salon-spa/tier5-src/_shared/iap-attendance-purchase.ts

@@ -0,0 +1,211 @@
+import { attendanceCheckoutRoute, availableTicketAttendanceOf, bookingAttendanceOf, classifyForApple, hostSessionFromGlobal, iapPriceFields, type BookingAttendance, type CatalogReference, type IapPollDirective, type TicketAttendance } from "@himalaya/iap";
+import { bookingOrders, createIapCommerce, eventTicketOrders, type IapOrderItem } from "@himalaya/iap-checkout";
+import { copyParam, copyTemplate } from "./himi-copy.js";
+import { createAttendanceForm, type AttendanceField } from "./iap-attendance-form.js";
+import { attendancePlatform } from "./iap-attendance.js";
+import { iapPriceCopy, iapPurchaseCopy } from "./iap-worker.js";
+
+export interface AttendancePurchaseFields {
+  iapBuyHidden: boolean;
+  iapBuyDisabled: boolean;
+  iapBuyLabel: string;
+  iapBusy: boolean;
+  iapPrice: string;
+  iapNote: string;
+  iapRetryHidden: boolean;
+  iapFormHidden: boolean;
+  iapFormError: string;
+  iapSignInHidden: boolean;
+  iapFields: AttendanceField[];
+  _poll?: IapPollDirective;
+}
+
+export const ATTENDANCE_INITIAL: AttendancePurchaseFields = {
+  iapBuyHidden: true, iapBuyDisabled: true, iapBuyLabel: "", iapBusy: false,
+  iapPrice: "", iapNote: "", iapRetryHidden: true, iapFormHidden: true, iapFormError: "", iapSignInHidden: true, iapFields: [],
+};
+export const ATTENDANCE_NOT_HYDRATED = [...Object.keys(ATTENDANCE_INITIAL), "_poll"] as (keyof AttendancePurchaseFields & string)[];
+
+export function createAttendancePurchase(options: { kind: "bookingsService" | "eventsTicket"; prefix: string; pollAction: string; onChange(): void }) {
+  const { prefix } = options;
+  let form = createAttendanceForm(prefix);
+  const submittedForms = new Map<string, ReturnType<typeof createAttendanceForm>>();
+  const session = hostSessionFromGlobal();
+  const commerce = createIapCommerce({ adapters: [options.kind === "bookingsService" ? bookingOrders : eventTicketOrders], onChange: options.onChange });
+  let generation = session.current().generation;
+  let reference: CatalogReference | undefined;
+  let metadata: BookingAttendance | TicketAttendance | undefined;
+  let platform = "unknown";
+  let started = false;
+  let inFlight = false;
+  let formError = "";
+  let sequence = 0;
+  let formRevision = 0;
+  const attempts = new Map<string, string>();
+  session.subscribe(() => { syncSession(); if (reference) options.onChange(); });
+
+  function syncSession(): void {
+    const next = session.current().generation;
+    if (next === generation) return;
+    generation = next;
+    form.clear();
+    submittedForms.clear();
+    formError = "";
+    attempts.clear();
+  }
+
+  async function refresh(): Promise<void> {
+    const next = await attendancePlatform(publishPlatform);
+    if (next !== "unknown" || platform === "unknown") platform = next;
+    await resume();
+  }
+
+  async function resume(): Promise<void> {
+    if (reference) await commerce.loadPrices([{ reference }]);
+    const first = !started;
+    started = true;
+    await (first ? commerce.start() : commerce.reconcile());
+  }
+
+  function publishPlatform(next: string): void {
+    if (next === "unknown" && platform !== "unknown") return;
+    platform = next;
+    void resume().then(options.onChange, options.onChange);
+  }
+
+  function show(): void {
+    void attendancePlatform(publishPlatform).then(publishPlatform, options.onChange);
+  }
+
+  async function booking(id: string, service: unknown): Promise<void> {
+    syncSession();
+    reference = { kind: options.kind, id };
+    metadata = bookingAttendanceOf(service);
+    selectForm(id, (next) => next.booking(service));
+    formRevision++;
+    formError = "";
+    await show();
+  }
+
+  async function ticket(id: string, event: unknown, available: unknown): Promise<void> {
+    syncSession();
+    reference = id ? { kind: options.kind, id } : undefined;
+    metadata = availableTicketAttendanceOf(event, available);
+    selectForm(id, (next) => next.event((event as { form?: unknown } | undefined)?.form));
+    formRevision++;
+    formError = "";
+    await show();
+  }
+
+  function selectForm(id: string, initialize: (next: ReturnType<typeof createAttendanceForm>) => void): void {
+    const key = `${options.kind}:${id}`;
+    const retained = submittedForms.get(key);
+    form = retained ?? createAttendanceForm(prefix);
+    if (!retained) initialize(form);
+  }
+
+  function fields(selected = true, publishPoll = true): AttendancePurchaseFields {
+    syncSession();
+    if (!reference || !metadata) return ATTENDANCE_INITIAL;
+    const currency = metadata.currency ?? "";
+    const classified = classifyForApple(metadata, currency);
+    const candidate = platform === "ios" && classified === "appleIap";
+    const price = iapPriceFields(commerce.pricing.view(reference), iapPriceCopy(prefix));
+    const copy = iapPurchaseCopy(prefix);
+    const purchase = commerce.purchaseFields(reference, copy);
+    const apple = candidate || (platform === "ios" && classified !== "wixPayments" && purchase.appleRoute);
+    const enabled = attendanceCheckoutRoute(metadata, currency, platform) === "appleIap";
+    const poll = publishPoll ? commerce.pollDirective(options.pollAction) : undefined;
+    const state = commerce.state();
+    for (const [target, attempt] of attempts) {
+      const key = `${reference.kind}:${reference.id}#${encodeURIComponent(attempt)}`;
+      if ((state.phase === "accessReady" && state.item === key) || state.payments.some((p) => p.item === key && p.access === "granted")) attempts.delete(target);
+    }
+    const formKey = `${reference.kind}:${reference.id}`;
+    if (![...attempts.keys()].some((target) => target.startsWith(`${formKey}:`))) submittedForms.delete(formKey);
+    const own = state.item?.startsWith(`${reference.kind}:${reference.id}#`);
+    const completed = state.phase === "accessReady" && own;
+    const member = session.current().kind === "member";
+    let note = "";
+    if (apple && !enabled) note = copy.unavailable;
+    else if (apple && !member) note = copy.signInRequired;
+    else if (apple && purchase.buyNote) note = purchase.buyNote;
+    else if (apple && !form.supported()) note = copyParam(`${prefix}.formUnavailableText`, "This registration form is not supported yet.");
+    else if (apple && completed) note = copyParam(`${prefix}.purchaseCompleteText`, options.kind === "bookingsService" ? "Your booking is confirmed." : "Your ticket is confirmed.");
+    else if (apple && own && state.phase === "cancelled") note = copyParam(`${prefix}.purchaseCancelledText`, "Purchase cancelled. Your place is not confirmed.");
+    return {
+      iapBuyHidden: !apple, iapBuyDisabled: !enabled || !selected || !member || !form.supported() || purchase.buyDisabled || inFlight,
+      iapBuyLabel: purchase.buyLabel || copy.buy, iapBusy: purchase.buyBusy || inFlight,
+      iapPrice: apple ? price.priceText : "", iapRetryHidden: !apple || (price.hidePriceRetry && commerce.scopeComplete()),
+      iapNote: note,
+      iapFormHidden: !apple || !selected || !form.supported(), iapFormError: formError,
+      iapSignInHidden: !apple || member || options.kind === "bookingsService",
+      iapFields: form.rows().map((f, index, rows) => ({ ...f,
+        id: `${generation}:${formRevision}:${f.id}`, fieldId: f.id,
+        errorHidden: !f.error,
+        options: f.options.map((o) => ({ ...o, fieldId: f.id, displayLabel: (f.kind === "multiple" ? f.selectedIds.includes(o.id) : f.value === o.id) ? `${o.label} ✓` : o.label })),
+        label: f.required ? `${f.label} *` : f.label,
+        inputLabel: copyTemplate(`${prefix}.fieldAccessibilityLabel`, "{section}: {field}", { section: f.id.startsWith("buyer:") ? copyParam(`${prefix}.buyerDetailsLabel`, "Buyer details") : copyParam(`${prefix}.guestDetailsLabel`, "Ticket holder details"), field: f.label }),
+        sectionLabel: index === 0 ? copyParam(`${prefix}.buyerDetailsLabel`, "Buyer details") : f.id.startsWith("guest:") && rows[index - 1].id.startsWith("buyer:") ? copyParam(`${prefix}.guestDetailsLabel`, "Ticket holder details") : "",
+      })), ...(poll ? { _poll: poll } : {}),
+    };
+  }
+
+  async function buy(selection: { key: string; slot?: Record<string, unknown>; eventId?: string }): Promise<void> {
+    syncSession();
+    if (!reference || !metadata || fields(true, false).iapBuyDisabled || inFlight) return;
+    if (options.kind === "eventsTicket" && reference.id !== selection.key) return;
+    if (!form.validate()) { formError = copyParam(`${prefix}.formRequiredText`, "Complete the required details before purchasing."); return; }
+    if (session.current().kind !== "member") { formError = iapPurchaseCopy(prefix).signInRequired; return; }
+    const currentGeneration = generation;
+    const ref = reference;
+    submittedForms.set(`${ref.kind}:${ref.id}`, form);
+    const target = `${ref.kind}:${ref.id}:${selection.key}`;
+    let attemptId = attempts.get(target);
+    const state = commerce.state();
+    const attemptKey = attemptId ? `${ref.kind}:${ref.id}#${encodeURIComponent(attemptId)}` : "";
+    const completed = attemptId && ((state.phase === "accessReady" && state.item === attemptKey) || state.payments.some((p) => p.item === attemptKey && p.access === "granted"));
+    if (!attemptId || completed) { attemptId = `${Date.now().toString(36)}-${++sequence}-${Math.random().toString(36).slice(2)}`; attempts.set(target, attemptId); }
+    const item: IapOrderItem = { reference: ref, attemptId, quantity: 1, attendance: {
+      amount: metadata.amount!, currency: metadata.currency!,
+      ...(options.kind === "bookingsService" ? { booking: { slot: selection.slot ?? {}, contactDetails: form.buyer() } } : { ticket: { eventId: selection.eventId ?? "", ...form.ticket(ref.id) } }),
+    } };
+    inFlight = true;
+    formError = "";
+    options.onChange();
+    try {
+      await commerce.buy(item);
+      const after = commerce.state();
+      if (after.phase === "accessReady" && after.item === `${ref.kind}:${ref.id}#${encodeURIComponent(attemptId)}`) attempts.delete(target);
+    }
+    finally { inFlight = false; syncSession(); if (generation !== currentGeneration) form.clear(); options.onChange(); }
+  }
+
+  function change(arg: unknown): void {
+    syncSession();
+    const state = commerce.state();
+    if (reference) {
+      for (const [target, attempt] of attempts) {
+        const item = `${reference.kind}:${reference.id}#${encodeURIComponent(attempt)}`;
+        const canCorrect = state.phase === "cancelled" || (state.phase === "refused" && (state.failure === "orderRefused" || state.failure === "productChanged"));
+        if (canCorrect && state.item === item) { attempts.delete(target); submittedForms.delete(`${reference.kind}:${reference.id}`); }
+      }
+      const referencePrefix = `${reference.kind}:${reference.id}:`;
+      if (inFlight || [...attempts.keys()].some((target) => target.startsWith(referencePrefix))) {
+        formError = copyParam(`${prefix}.detailsLockedText`, "Finish the current purchase before changing registration details.");
+        return;
+      }
+    }
+    form.change(arg);
+    formError = "";
+  }
+
+  return {
+    booking, ticket, fields, buy,
+    usesRegularPlatform: () => platform === "android" || platform === "web",
+    invalidate: () => { reference = undefined; metadata = undefined; options.onChange(); },
+    change,
+    refresh,
+    poll: async () => { syncSession(); await commerce.poll(); },
+  };
+}

package/templates/salon-spa/tier5-src/_shared/iap-attendance.ts

@@ -0,0 +1,38 @@
+import { get as appInfo } from "@himalaya/app-info";
+import { attendanceCheckoutRoute, bookingAttendanceOf, ticketAttendanceOf } from "@himalaya/iap";
+
+let knownPlatform: string | undefined;
+
+export function attendancePlatform(onResolved?: (platform: string) => void): Promise<string> {
+  if (knownPlatform) return Promise.resolve(knownPlatform);
+  const info = appInfo().then((value) => value.platform, () => "unknown").then((platform) => {
+    if (platform !== "unknown") knownPlatform = platform;
+    return platform;
+  });
+  const host = globalThis as { setTimeout?: (fn: () => void, ms: number) => unknown; clearTimeout?: (timer: unknown) => void };
+  if (!host.setTimeout) {
+    void info.then((platform) => onResolved?.(platform));
+    return Promise.resolve("unknown");
+  }
+  return new Promise((resolve) => {
+    let timedOut = false;
+    const timer = host.setTimeout!(() => { timedOut = true; resolve("unknown"); }, 1500);
+    void info.then((platform) => { host.clearTimeout?.(timer); resolve(platform); if (timedOut) onResolved?.(platform); });
+  });
+}
+
+export async function mayUseRegularBookingCheckout(service: unknown): Promise<boolean> {
+  const metadata = bookingAttendanceOf(service);
+  if (metadata.priceType === "NO_FEE" || isZero(metadata.amount)) return true;
+  return attendanceCheckoutRoute(metadata, metadata.currency ?? "", await attendancePlatform()) === "regular";
+}
+
+export async function mayUseRegularTicketCheckout(event: unknown, ticket: { free?: boolean; price?: { amount?: string; currency?: string }; saleStatus?: string } | undefined): Promise<boolean> {
+  if (ticket?.free === true || isZero(ticket?.price?.amount)) return true;
+  const metadata = ticketAttendanceOf(event, { hidden: false, saleStatus: ticket?.saleStatus });
+  return attendanceCheckoutRoute(metadata, ticket?.price?.currency ?? "", await attendancePlatform()) === "regular";
+}
+
+function isZero(value: unknown): boolean {
+  return typeof value === "string" && /^0+(?:\.0+)?$/.test(value);
+}

package/templates/salon-spa/tier5-src/_shared/iap-worker.ts

@@ -0,0 +1,125 @@
+// Worker-side glue for the shared IAP layer (`@himalaya/iap` catalog pricing and
+// `@himalaya/iap-checkout` → createIapCommerce), shared by every screen that shows or sells an
+// IAP-backed item. Mapping, Apple prices, payment guards, the host scope and the sale live in the
+// SDK; this only supplies the copy and the hydration reset.
+import { hostSessionFromGlobal, type IapPriceCopy } from "@himalaya/iap";
+import type { IapCommerce, IapPurchaseCopy, IapRestoreResult } from "@himalaya/iap-checkout";
+import { paymentSetupMessage } from "./payment-setup.js";
+import { copyParam, copyTemplate } from "./himi-copy.js";
+
+/** 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."),
+  };
+}
+
+/** App Store purchase labels from the screen's copy pack (`<prefix>.buyCta`, …), for
+ *  `iapPurchaseFields`. Customer copy only: no backend names, ids or diagnostics. */
+export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
+  return {
+    buy: copyParam(`${prefix}.buyCta`, "Buy now"),
+    processing: copyParam(`${prefix}.purchaseProcessingText`, "Processing your purchase…"),
+    awaitingApproval: copyParam(`${prefix}.purchaseAwaitingApprovalText`, "Waiting for approval"),
+    unavailable: copyParam(`${prefix}.purchaseTemporarilyUnavailableText`, "Purchasing is temporarily unavailable."),
+    signInRequired: copyParam(`${prefix}.purchaseSignInText`, "Sign in to buy."),
+    sitePaymentUnavailable: paymentSetupMessage(prefix),
+    retry: copyParam(`${prefix}.purchaseRetryText`, "Something went wrong. Try again."),
+    priceChanged: copyParam(`${prefix}.purchasePriceChangedText`, "The price changed. Check it and try again."),
+    support: copyParam(`${prefix}.purchaseSupportText`, "We couldn't finish this purchase. Contact support."),
+  };
+}
+
+/** The Restore purchases control (App Review 3.1.1) a screen binds. */
+export interface IapRestoreFields {
+  restoreHidden: boolean;
+  restoreLabel: string;
+  restoreDisabled: boolean;
+  restoreMessage: string;
+}
+
+/** Keep these out of hydration: a restore's answer belongs to the run that got it. */
+export const IAP_RESTORE_KEYS = ["restoreHidden", "restoreLabel", "restoreDisabled", "restoreMessage"] as const;
+
+/** The control before the screen knows it sells through Apple. */
+export const NO_IAP_RESTORE: IapRestoreFields = { restoreHidden: true, restoreLabel: "", restoreDisabled: false, restoreMessage: "" };
+
+export interface IapRestoreControl {
+  /** `sellsThroughApple` is the screen's own signal: its item's App Store route, or Account's
+   *  purchase readiness. */
+  fields(sellsThroughApple: boolean): IapRestoreFields;
+  /** Runs the shared `commerce.restore()`, repainting as it starts and when it answers. A tap while
+   *  one runs is ignored. */
+  run(): Promise<void>;
+}
+
+/** Copy from the screen's pack (`<prefix>.restorePurchasesCta`, …). The restore itself, and the access
+ *  re-read after it, are the shared commerce's. */
+export function createIapRestore(
+  commerce: Pick<IapCommerce, "restore">,
+  options: { prefix: string; repaint(): void; /** The session generation; defaults to the host's. */ generation?: () => number },
+): IapRestoreControl {
+  const generation = options.generation ?? (() => hostSessionFromGlobal().current().generation);
+  let running = false;
+  let message = "";
+  let messageGeneration = -1;
+
+  function say(text: string, forGeneration: number): void {
+    message = text;
+    messageGeneration = forGeneration;
+  }
+
+  async function run(): Promise<void> {
+    if (running) return;
+    running = true;
+    const startedFor = generation();
+    say(copyParam(`${options.prefix}.restoringText`, "Restoring…"), startedFor);
+    options.repaint();
+    // Stamped with the session the tap was for: an answer landing after a sign-out is never shown.
+    say(restoreMessage(await restored(commerce), options.prefix), startedFor);
+    running = false;
+    options.repaint();
+  }
+
+  return {
+    fields: (sellsThroughApple) => ({
+      restoreHidden: !sellsThroughApple,
+      restoreLabel: copyParam(`${options.prefix}.restorePurchasesCta`, "Restore purchases"),
+      restoreDisabled: running,
+      // The answer was for the person signed in when it ran; another session never inherits it.
+      restoreMessage: sellsThroughApple && messageGeneration === generation() ? message : "",
+    }),
+    run,
+  };
+}
+
+function restored(commerce: Pick<IapCommerce, "restore">): Promise<IapRestoreResult> {
+  return commerce.restore().catch(() => ({ status: "failed", code: "storeUnavailable" }) as const);
+}
+
+function restoreMessage(result: IapRestoreResult, prefix: string): string {
+  if (result.status === "needsSignIn") return copyParam(`${prefix}.restoreSignInText`, "Sign in to restore your purchases.");
+  if (result.status === "failed") return result.code === "sessionChanged" ? "" : copyParam(`${prefix}.restoreFailedText`, "Couldn't reach the App Store. Try again.");
+  // Every part that happened is said: a recovery never hides a refusal or a purchase still pending.
+  const parts = [
+    result.recovered === 1 ? copyParam(`${prefix}.restoredOneText`, "Restored 1 purchase.") : "",
+    result.recovered > 1 ? copyTemplate(`${prefix}.restoredManyText`, "Restored {count} purchases.", { count: result.recovered }) : "",
+    // Held unfinished because Wix refused it (another member's purchase, say).
+    result.refused > 0 ? copyParam(`${prefix}.restoreRefusedText`, "A purchase on this Apple ID couldn't be added to this account. Contact support.") : "",
+    result.pending > 0 ? copyParam(`${prefix}.restorePendingText`, "A purchase is still being confirmed. Try again in a moment.") : "",
+  ].filter(Boolean);
+  return parts.length ? parts.join(" ") : copyParam(`${prefix}.restoreUpToDateText`, "Your purchases are up to date.");
+}
+
+/** 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/salon-spa/tier5-src/_shared/local-preferences.ts

@@ -0,0 +1,38 @@
+/** Small local preferences only; never entity records or credentials. The host
+ * overwrites these reserved input fields from its authenticated account/site.
+ * Older hosts and visitors deliberately stay session-only. */
+export interface PreferenceStore {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+export interface PreferenceRuntime { input?: Record<string, unknown>; storage?: PreferenceStore; }
+export function localPreferences<T>(name: string, normalize: (value: unknown) => T, runtime?: PreferenceRuntime) {
+  const host = runtime ?? (globalThis as { himalaya?: PreferenceRuntime }).himalaya;
+  const account = host?.input?.__himiPreferenceAccount;
+  const business = host?.input?.__himiPreferenceBusiness;
+  const valid = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(value) && value !== 'default';
+  const key = valid(account) && valid(business) && host?.storage
+    ? `himi.preferences.v1.${account}.${encodeURIComponent(business)}.${name}` : '';
+  let available = !!key;
+  return {
+    get available() { return available; },
+    read(): T {
+      if (!key) return normalize(undefined);
+      try {
+        const raw = host!.storage!.getItem(key);
+        if (!raw || raw.length > 32768) return normalize(undefined);
+        const data = JSON.parse(raw);
+        return normalize(data?.version === 1 ? data.value : undefined);
+      } catch { available = false; return normalize(undefined); }
+    },
+    write(value: T): void {
+      if (!key) return;
+      try {
+        const raw = JSON.stringify({ version: 1, value: normalize(value) });
+        if (raw.length > 32768) { available = false; return; }
+        host!.storage!.setItem(key, raw);
+        available = host!.storage!.getItem(key) === raw;
+      } catch { available = false; }
+    },
+  };
+}

package/templates/salon-spa/tier5-src/_shared/member-access.ts

@@ -0,0 +1,52 @@
+import { dispatch } from "@himalaya/dispatch";
+import { getMyData } from "@himalaya/wix-users";
+
+export interface MemberAccess { email: string; scope: string; }
+export function memberAccessChanged(): Error {
+  const error = new Error("Member access changed"); error.name = "MemberAccessChanged"; return error;
+}
+export async function memberAccess(): Promise<MemberAccess> {
+  let email = "";
+  let identityUnavailable = false;
+  try {
+    const value = await dispatch("himi.wix.memberIdentity") as { email?: unknown; payload?: { email?: unknown } } | null;
+    const raw = value?.email ?? value?.payload?.email;
+    email = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  } catch { identityUnavailable = true; }
+  // Older native hosts predate the memberIdentity action but can still expose
+  // the authenticated profile through wix-users. Only a missing action uses
+  // that rung: an explicit empty current-session response remains a visitor.
+  if (!email && identityUnavailable) {
+    try {
+      const profile = await getMyData();
+      const raw = profile.email ?? profile.contactEmail;
+      email = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+    } catch { /* A visitor or an unavailable legacy profile remains anonymous. */ }
+  }
+  const input = (globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input;
+  const account = input?.__himiPreferenceAccount, business = input?.__himiPreferenceBusiness;
+  const valid = (v: unknown): v is string => typeof v === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(v) && v !== "default";
+  // These fields are overwritten by authenticated hosts. Older binaries stay online-only.
+  return { email, scope: email && valid(account) && valid(business) ? JSON.stringify([account, business, email]) : "" };
+}
+export async function assertMemberAccess(member: MemberAccess): Promise<void> {
+  const current = await memberAccess();
+  if (!member.email || current.email !== member.email || current.scope !== member.scope) throw memberAccessChanged();
+}
+export function memberAccessDenied(error: unknown): boolean {
+  return (error as { name?: string } | null)?.name === "MemberAccessChanged" || /(?:HTTP\s*(?:401|403)|READ_ORDER_FORBIDDEN|permission denied|forbidden)/i.test(String(error));
+}
+
+/** Did this write fail because the member changed (signed out, or another account)? Then
+ *  the screen reloads for whoever is signed in now. A 401/403 for the SAME member is only a
+ *  failed write: the caller keeps what the member typed and says so. */
+export async function memberChanged(member: MemberAccess | undefined, error: unknown): Promise<boolean> {
+  if ((error as { name?: string } | null)?.name === "MemberAccessChanged") return true;
+  if (!member || !memberAccessDenied(error)) return false;
+  try {
+    await assertMemberAccess(member);
+    return false;
+  } catch {
+    return true;
+  }
+}