@wix/himalaya-cli 0.1388.0 → 0.1390.0

package/templates/podcast-creator-owner/tier5-src/himi-owner-lite-wrist/index.ts

@@ -0,0 +1,350 @@
+// Tier-5 bundle: __HIMI_APP_NAME__ — WRIST. The worker behind the paired Apple Watch's two
+// screens, run headlessly ON THE PHONE by the app's watch brain (companion mode): the watch
+// never holds a Wix session and never runs JS, it renders the literal descriptor the phone
+// resolves from this state.
+//
+// Two owner moments, nothing else: "who's next and when" (nextUp + the rest of today) and
+// "accept or decline a booking request" (requests, one at a time). Confirm / decline call
+// the same @himalaya/wix-bookings writes the Wix Owner booking screen uses, but per request:
+// that worker's actions read a screen-param id and a single screen revision, and the wrist
+// holds a QUEUE of requests, each with its own revision.
+//
+// Every write carries the siteId the watch rendered: a site switched on the phone between
+// render and tap must never confirm another business's booking.
+
+import { defineService } from "@himalaya/state";
+import { queryBookings, confirmBooking, declineBooking } from "@himalaya/wix-bookings";
+import { isBridgeUnavailable } from "../_shared/owner-load-error.js";
+import { readSelectedSite, selectedSiteName } from "../_shared/owner-selected-site.js";
+
+type Rec = Record<string, unknown>;
+
+export interface WristRow {
+  bookingId: string;
+  name: string;      // client first name (or "Client")
+  service: string;   // booked service title
+  startIso: string;
+  endIso: string;
+  timeLabel: string; // "10:30"
+  rangeLabel: string; // "10:30 – 11:30"
+  countdown: string;  // "in 21 min" / "in 1 h 5 min" / "now" — relative to the last load
+  whenLabel: string;  // "Today" / "Tomorrow" / "Thu 16 Oct" — the day it falls on
+}
+
+export interface WristRequest extends WristRow {
+  revision: string;
+  durationMin: number;
+  dayLabel: string;  // "Thu 14:00"
+}
+
+export interface WristState {
+  status: "loading" | "ready" | "error" | "signedOut" | "noBookings";
+  siteId: string;
+  siteName: string;
+  /** Always an object — an absent one is EMPTY_ROW behind `hasNextUp` — so every binding
+   *  path resolves on every state (a null parent left them unresolved). */
+  nextUp: WristRow;
+  hasNextUp: boolean;
+  later: WristRow[];
+  requests: WristRequest[];
+  requestCount: number;
+  requestBadge: string;   // "2 requests" / "1 request" / ""
+  hasRequests: boolean;
+  noRequests: boolean;
+  /** Hide "No requests waiting": there are requests, or the screen is a degrade state. */
+  hideNoRequests: boolean;
+  requestIndex: number;
+  requestPosition: string; // "Request 1 of 2"
+  current: WristRequest;
+  doneToday: boolean;
+  tomorrowFirst: WristRow;
+  hasTomorrowFirst: boolean;
+  /** Hide the "next booking" block: there is a next-up today, or nothing upcoming at all. */
+  hideTomorrow: boolean;
+  inFlight: boolean;
+  /** Decline is two taps: `askDecline` reveals the confirm row, `decline` writes. */
+  confirmingDecline: boolean;
+  notConfirmingDecline: boolean;
+  actionError: string;
+  message: string;         // Home's one-line state copy (incl. "You're done for today")
+  /** Only the copy for a state the owner must act on (signed out, no Bookings, error) — the
+   *  request screen's line, where "done for today" would be wrong. */
+  statusMessage: string;
+}
+
+export const COPY = {
+  signedOut: "Sign in on your iPhone",
+  noBookings: "Bookings isn't set up on this site",
+  doneToday: "You're done for today",
+  noRequests: "No requests waiting",
+  changed: "This request changed — check it on your iPhone",
+  error: "Open Owner on your iPhone",
+  writeFailed: "Couldn't update it — check it on your iPhone",
+} as const;
+
+const PENDING = new Set(["PENDING", "PENDING_APPROVAL", "WAITING_LIST"]);
+const LIMIT = 50;
+
+function str(r: Rec | undefined, ...paths: string[]): string {
+  for (const path of paths) {
+    let v: unknown = r;
+    for (const k of path.split(".")) v = v && typeof v === "object" ? (v as Rec)[k] : undefined;
+    if (typeof v === "string" && v) return v;
+    if (typeof v === "number") return String(v);
+  }
+  return "";
+}
+
+function hhmm(d: Date): string {
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+function sameLocalDay(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+
+/** "in 21 min" / "in 1 h 5 min" / "now". The phone reloads while the watch is visible, so a
+ *  minute-granularity label stays honest without an OS-ticked timer on the wrist. */
+export function countdown(startMs: number, nowMs: number): string {
+  const minutes = Math.round((startMs - nowMs) / 60000);
+  if (minutes <= 0) return "now";
+  if (minutes < 60) return `in ${minutes} min`;
+  const h = Math.floor(minutes / 60), m = minutes % 60;
+  return m ? `in ${h} h ${m} min` : `in ${h} h`;
+}
+
+function row(b: Rec, nowMs = Date.now()): WristRow {
+  const startIso = str(b, "startDate", "bookedEntity.slot.startDate");
+  const endIso = str(b, "endDate", "bookedEntity.slot.endDate");
+  const start = new Date(startIso);
+  const end = endIso ? new Date(endIso) : null;
+  return {
+    bookingId: str(b, "id"),
+    name: str(b, "contactDetails.firstName") || "Client",
+    service: str(b, "bookedEntity.title", "bookedEntity.slot.serviceName") || "Appointment",
+    startIso,
+    endIso,
+    timeLabel: hhmm(start),
+    rangeLabel: end ? `${hhmm(start)} – ${hhmm(end)}` : hhmm(start),
+    countdown: countdown(start.getTime(), nowMs),
+    whenLabel: whenLabel(start, new Date(nowMs)),
+  };
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** The day a booking falls on, named as an owner would say it. */
+export function whenLabel(start: Date, now: Date): string {
+  if (sameLocalDay(start, now)) return "Today";
+  const tomorrow = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1);
+  if (sameLocalDay(start, tomorrow)) return "Tomorrow";
+  return `${WEEKDAYS[start.getDay()]} ${start.getDate()} ${MONTHS[start.getMonth()]}`;
+}
+
+function request(b: Rec): WristRequest {
+  const r = row(b);
+  const start = new Date(r.startIso);
+  const durationMin = r.endIso ? Math.max(0, Math.round((Date.parse(r.endIso) - start.getTime()) / 60000)) : 0;
+  return { ...r, revision: str(b, "revision"), durationMin, dayLabel: `${WEEKDAYS[start.getDay()]} ${hhmm(start)}` };
+}
+
+const EMPTY_ROW: WristRow = { bookingId: "", name: "", service: "", startIso: "", endIso: "", timeLabel: "", rangeLabel: "", countdown: "", whenLabel: "" };
+const EMPTY_REQUEST: WristRequest = { ...EMPTY_ROW, revision: "", durationMin: 0, dayLabel: "" };
+
+/** Pure: shape a bookings page into the wrist state. `now` is injectable for tests. */
+export function shape(bookings: Rec[], now: Date, site: { id: string; name: string }, requestIndex = 0): WristState {
+  const upcoming = bookings
+    .filter((b) => str(b, "id") && Date.parse(str(b, "startDate", "bookedEntity.slot.startDate")) >= now.getTime())
+    .sort((a, b) => Date.parse(str(a, "startDate")) - Date.parse(str(b, "startDate")));
+  const confirmed = upcoming.filter((b) => str(b, "status") === "CONFIRMED");
+  const today = confirmed.filter((b) => sameLocalDay(new Date(str(b, "startDate")), now)).map((b) => row(b, now.getTime()));
+  // A request this worker just confirmed/declined can still come back PENDING at the same
+  // revision from a read that lagged the write; it is not waiting on the owner any more.
+  const requests = upcoming
+    .filter((b) => PENDING.has(str(b, "status")) && handled.get(str(b, "id")) !== str(b, "revision"))
+    .map(request);
+  const next = today[0];
+  const after = next ? undefined : confirmed.map((b) => row(b, now.getTime()))[0];
+  const index = requests.length ? Math.min(Math.max(0, requestIndex), requests.length - 1) : 0;
+  const current = requests[index];
+  return {
+    status: "ready",
+    siteId: site.id,
+    siteName: site.name,
+    nextUp: next ?? EMPTY_ROW,
+    hasNextUp: !!next,
+    later: today.slice(1),
+    requests,
+    requestCount: requests.length,
+    requestBadge: requests.length === 0 ? "" : `${requests.length} ${requests.length === 1 ? "request" : "requests"}`,
+    hasRequests: requests.length > 0,
+    noRequests: requests.length === 0,
+    hideNoRequests: requests.length > 0,
+    requestIndex: index,
+    requestPosition: current ? `Request ${index + 1} of ${requests.length}` : "",
+    current: current ?? EMPTY_REQUEST,
+    doneToday: !next,
+    tomorrowFirst: after ?? EMPTY_ROW,
+    hasTomorrowFirst: !!after,
+    hideTomorrow: !!next || !after,
+    inFlight: false,
+    confirmingDecline: false,
+    notConfirmingDecline: true,
+    actionError: "",
+    message: next ? "" : COPY.doneToday,
+    statusMessage: "",
+  };
+}
+
+type Host = typeof globalThis & { himalaya?: { input?: Record<string, unknown> } };
+
+/** The business this worker's Wix bridge is scoped to. The phone's watch brain passes it as
+ *  `ownerWristSite` — the same value it checks every Accept/Decline against — so the two can
+ *  never disagree (the picker's KV entry is written only by the Sites list, not by a push or
+ *  deep link that also switches business). The bridge-injected business and the picker entry
+ *  are fallbacks for a host that does not pass it. */
+function site(): { id: string; name: string } {
+  const input = (globalThis as Host).himalaya?.input ?? {};
+  const pick = (v: unknown) => (typeof v === "string" && v !== "default" ? v.trim() : "");
+  const picked = readSelectedSite();
+  const id = pick(input.ownerWristSite) || pick(input.__himiPreferenceBusiness) || picked?.id || "";
+  return { id, name: picked && picked.id === id ? selectedSiteName("") : "" };
+}
+
+function initial(): WristState {
+  return { ...shape([], new Date(), site()), status: "loading", message: "" };
+}
+
+/** A failed read shows NOTHING of the last one: after a sign-out or a site switch those rows
+ *  are someone else's clients. Only the site header survives. */
+/** No usable owner session behind the bridge. On a phone that reads as the bridge refusing
+ *  ("wixApi not enabled — …") or a 401/403; the web preview's 501 bridge shape counts too. A
+ *  transient 5xx from Wix is NOT a sign-out — it is an ordinary error. */
+export function isSignedOut(e: unknown): boolean {
+  const text = String((e as Error)?.message ?? e);
+  if (/wixApi not enabled|session unavailable|not signed in|\bHTTP 40[13]\b|webwix_bridge/i.test(text)) return true;
+  return isBridgeUnavailable(e) && /\bHTTP 501\b/.test(text);
+}
+
+function failure(s: WristState, e: unknown): WristState {
+  // A degrade screen is ONE line: no "Next up" card, no "No requests waiting" under it.
+  const empty = { ...shape([], new Date(), { id: s.siteId, name: s.siteName }), message: "", hideNoRequests: true, hideTomorrow: true };
+  if (isSignedOut(e)) return { ...empty, status: "signedOut", message: COPY.signedOut, statusMessage: COPY.signedOut };
+  const text = String((e as Error)?.message ?? e);
+  // The Bookings app is not installed on the site: its API answers 428 (or 404 for the route).
+  if (/\b428\b|\b404\b|not installed|FAILED_PRECONDITION/i.test(text)) {
+    return { ...empty, status: "noBookings", message: COPY.noBookings, statusMessage: COPY.noBookings };
+  }
+  return { ...empty, status: "error", message: COPY.error, statusMessage: COPY.error };
+}
+
+async function fetchInto(s: WristState): Promise<WristState> {
+  const nowIso = new Date().toISOString();
+  const sort = [{ fieldName: "startDate", order: "ASC" }];
+  // TWO reads: the day's schedule, and the pending requests on their own. One page of every
+  // status would fill with a busy week's confirmed bookings and hide next week's request.
+  const [schedule, pending] = await Promise.all([
+    queryBookings({ query: { filter: { startDate: { $gte: nowIso }, status: { $nin: ["CANCELED", "DECLINED"] } }, sort, paging: { limit: LIMIT, offset: 0 } } }),
+    queryBookings({ query: { filter: { startDate: { $gte: nowIso }, status: { $in: [...PENDING] } }, sort, paging: { limit: LIMIT, offset: 0 } } }),
+  ]);
+  const byId = new Map<string, Rec>();
+  for (const b of [...(schedule.bookings ?? []), ...(pending.bookings ?? [])] as unknown as Rec[]) {
+    const id = str(b, "id");
+    if (id) byId.set(id, b);
+  }
+  return shape([...byId.values()], new Date(), site(), s.requestIndex);
+}
+
+function isStale(e: unknown): boolean {
+  return /revision|\b409\b|ABORTED|conflict/i.test(String((e as Error)?.message ?? e));
+}
+
+type Write = (bookingId: string, revision: string) => Promise<unknown>;
+
+async function respond(s: WristState, params: unknown, write: Write): Promise<WristState> {
+  if (s.inFlight) return s;
+  const p = (params && typeof params === "object" ? params : {}) as Rec;
+  const bookingId = str(p, "bookingId");
+  const siteId = str(p, "siteId");
+  // A press rendered for another business, or for a request that is no longer pending.
+  if (siteId !== site().id) return { ...s, actionError: COPY.changed };
+  const target = s.requests.find((r) => r.bookingId === bookingId);
+  if (!target) return { ...s, actionError: COPY.changed };
+  inFlightNow = true;
+  writeGeneration += 1;
+  try {
+    await write(target.bookingId, target.revision);
+    handled.set(target.bookingId, target.revision);
+  } catch (e) {
+    inFlightNow = false;
+    if (isStale(e)) {
+      try { return (lastWrite = { ...(await fetchInto(s)), actionError: COPY.changed }); }
+      catch { return (lastWrite = { ...s, actionError: COPY.changed }); }
+    }
+    // Not written. A lost session is a sign-out; anything else keeps the request on screen
+    // with an error under its buttons, rather than emptying the queue as if it had worked.
+    return (lastWrite = isSignedOut(e) ? failure(s, e) : { ...s, actionError: COPY.writeFailed });
+  }
+  try {
+    return (lastWrite = await fetchInto(s));
+  } catch (e) {
+    return (lastWrite = failure(s, e));
+  } finally {
+    inFlightNow = false;
+  }
+}
+
+/** Requests this worker wrote, with the revision it wrote against (see `shape`). */
+const handled = new Map<string, string>();
+
+// The runtime commits whichever overlapping action finishes LAST, with the state each was
+// dispatched with. A refresh that started before a confirm and lands after it would put the
+// accepted request back on the wrist, so a refresh overtaken by a write returns that write's
+// result instead of its own.
+let writeGeneration = 0;
+let lastWrite: WristState | null = null;
+
+async function read(s: WristState): Promise<WristState> {
+  const generation = writeGeneration;
+  try {
+    const next = await fetchInto(s);
+    return generation !== writeGeneration || inFlightNow ? (lastWrite ?? s) : next;
+  } catch (e) {
+    return generation !== writeGeneration || inFlightNow ? (lastWrite ?? s) : failure(s, e);
+  }
+}
+
+// The state a concurrent action sees is the one it was dispatched with, so a double tap
+// would read `inFlight: false` twice; this module flag is the guard that actually holds.
+let inFlightNow = false;
+
+const svc = defineService<WristState, {
+  load: (s: WristState) => Promise<WristState>;
+  refresh: (s: WristState) => Promise<WristState>;
+  confirm: (s: WristState, params?: unknown) => Promise<WristState>;
+  decline: (s: WristState, params?: unknown) => Promise<WristState>;
+  nextRequest: (s: WristState) => Promise<WristState>;
+  askDecline: (s: WristState) => Promise<WristState>;
+  cancelDecline: (s: WristState) => Promise<WristState>;
+}>("ownerWrist", {
+  state: initial(),
+  actions: {
+    load: async (s) => read(s),
+    refresh: async (s) => read(s),
+    confirm: async (s, params) => (inFlightNow ? s : respond(s, params, (id, rev) => confirmBooking(id, rev))),
+    decline: async (s, params) => (inFlightNow ? s : respond(s, params, (id, rev) => declineBooking(id, rev))),
+    askDecline: async (s) => (s.current.bookingId ? { ...s, confirmingDecline: true, notConfirmingDecline: false, actionError: "" } : s),
+    cancelDecline: async (s) => ({ ...s, confirmingDecline: false, notConfirmingDecline: true }),
+    nextRequest: async (s) => {
+      if (!s.requests.length) return s;
+      const index = (s.requestIndex + 1) % s.requests.length;
+      const current = s.requests[index];
+      return { ...s, requestIndex: index, current, requestPosition: `Request ${index + 1} of ${s.requests.length}`, actionError: "" };
+    },
+  },
+});
+
+svc.load();
+export { svc };

package/templates/portfolio-creative/dev/index.ts

@@ -2762,6 +2762,93 @@ const SCREENS = runtimeSetting({
                         "accessibilityLabel": "Saved posts"
                       }
                     },
+                    {
+                      "id": "himi_account.restore",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "HStack",
+                        "props": {
+                          "spacing": 12,
+                          "children": [
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Icon",
+                                "props": {
+                                  "name": "refresh",
+                                  "size": 18,
+                                  "tint": "accentPrimary"
+                                }
+                              },
+                              "modifiers": {
+                                "accessibilityRole": "decorative"
+                              }
+                            },
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "$service:himiStoreAccount.restoreLabel",
+                                  "style": "bodyEmphasis"
+                                }
+                              }
+                            },
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Spacer",
+                                "props": {}
+                              }
+                            }
+                          ]
+                        }
+                      },
+                      "modifiers": {
+                        "background": {
+                          "token": "surfaceElevated"
+                        },
+                        "border": {
+                          "width": 1,
+                          "color": {
+                            "token": "border"
+                          }
+                        },
+                        "cornerRadius": 8,
+                        "padding": {
+                          "leading": 14,
+                          "trailing": 14,
+                          "top": 13,
+                          "bottom": 13
+                        },
+                        "onTap": {
+                          "actionId": "tier5.himiStoreAccount.iapRestore"
+                        },
+                        "pressFeedback": "scale",
+                        "haptic": "light",
+                        "accessibilityLabel": "$service:himiStoreAccount.restoreLabel",
+                        "hiddenPath": "$service:himiStoreAccount.restoreHidden"
+                      }
+                    },
+                    {
+                      "id": "himi_account.restore_message",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "$service:himiStoreAccount.restoreMessage",
+                          "style": "footnote",
+                          "color": "textSecondary",
+                          "collapseWhenEmpty": true
+                        }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiStoreAccount.restoreHidden"
+                      }
+                    },
                     {
                       "id": "himi_account.addresses",
                       "body": {
@@ -3102,6 +3189,109 @@ const SCREENS = runtimeSetting({
                 "hiddenPath": "$service:himiStoreAccount.notMember"
               }
             },
+            {
+              "id": "",
+              "body": {
+                "package": "himalaya",
+                "type": "VStack",
+                "props": {
+                  "spacing": 8,
+                  "alignment": "leading",
+                  "children": [
+                    {
+                      "id": "himi_account.restore_guest",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "HStack",
+                        "props": {
+                          "spacing": 12,
+                          "children": [
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Icon",
+                                "props": {
+                                  "name": "refresh",
+                                  "size": 18,
+                                  "tint": "accentPrimary"
+                                }
+                              },
+                              "modifiers": {
+                                "accessibilityRole": "decorative"
+                              }
+                            },
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "$service:himiStoreAccount.restoreLabel",
+                                  "style": "bodyEmphasis"
+                                }
+                              }
+                            },
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Spacer",
+                                "props": {}
+                              }
+                            }
+                          ]
+                        }
+                      },
+                      "modifiers": {
+                        "background": {
+                          "token": "surfaceElevated"
+                        },
+                        "border": {
+                          "width": 1,
+                          "color": {
+                            "token": "border"
+                          }
+                        },
+                        "cornerRadius": 8,
+                        "padding": {
+                          "leading": 14,
+                          "trailing": 14,
+                          "top": 13,
+                          "bottom": 13
+                        },
+                        "onTap": {
+                          "actionId": "tier5.himiStoreAccount.iapRestore"
+                        },
+                        "pressFeedback": "scale",
+                        "haptic": "light",
+                        "accessibilityLabel": "$service:himiStoreAccount.restoreLabel",
+                        "hiddenPath": "$service:himiStoreAccount.restoreHidden"
+                      }
+                    },
+                    {
+                      "id": "himi_account.restore_guest_message",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "Text",
+                        "props": {
+                          "text": "$service:himiStoreAccount.restoreMessage",
+                          "style": "footnote",
+                          "color": "textSecondary",
+                          "collapseWhenEmpty": true
+                        }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiStoreAccount.restoreHidden"
+                      }
+                    }
+                  ]
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiStoreAccount.isMember"
+              }
+            },
             {
               "id": "himi_account.language",
               "body": {
@@ -3471,6 +3661,7 @@ const SCREENS = runtimeSetting({
           "actionId": "tier5.himiStoreAccount.refresh",
           "params": {
             "memberAccountLinks": "1",
+            "restorePurchases": "1",
             "copy": "{\"account.subtitle\":\"Orders, RSVPs and saved content in one place.\",\"storeAccount.authBody\":\"Sign in to continue — cart and RSVPs stay with you.\",\"storeAccount.authBodyRegister\":\"Create a member account to continue — cart and RSVPs stay with you.\"}"
           }
         }
@@ -3482,7 +3673,8 @@ const SCREENS = runtimeSetting({
       "contentType": "application/javascript+ts-bundle",
       "declaredCapabilities": [
         "wix_api",
-        "app_info"
+        "app_info",
+        "iap"
       ],
       "minBinaryVersion": "0.2.0",
       "bundleVersion": "0.0.1"

package/templates/portfolio-creative/tier5-src/_shared/iap-worker.ts

@@ -2,9 +2,9 @@
 // `@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 type { IapPriceCopy } from "@himalaya/iap";
-import type { IapPurchaseCopy } from "@himalaya/iap-checkout";
-import { copyParam } from "./himi-copy.js";
+import { hostSessionFromGlobal, type IapPriceCopy } from "@himalaya/iap";
+import type { IapCommerce, IapPurchaseCopy, IapRestoreResult } from "@himalaya/iap-checkout";
+import { copyParam, copyTemplate } from "./himi-copy.js";
 
 /** Price labels from the screen's copy pack (`<prefix>.priceLoadingText`, …). */
 export function iapPriceCopy(prefix: string): IapPriceCopy {
@@ -31,6 +31,87 @@ export function iapPurchaseCopy(prefix: string): IapPurchaseCopy {
   };
 }
 
+/** 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. */