@wix/himalaya-cli 0.1608.0 → 0.1610.0

package/guides/form-submit.service.ts

@@ -46,12 +46,13 @@ function shape(s: Partial<PostFormState>): PostFormState {
 // Submit stays available after every class: the user retries once they reconnect,
 // sign in, join the site or are granted access — without restarting the form.
 type ErrorKind = "" | "offline" | "server" | "signIn" | "membership" | "permission";
-const SAVE_FAILED: Record<Exclude<ErrorKind, "">, string> = {
+const SAVE_FAILED: Record<Exclude<ErrorKind, ""> | "unconfirmed", string> = {
   offline: "You're offline, so nothing was saved. Try again when you reconnect.",
   server: "Couldn't save your changes. Try again.",
   signIn: "Your session has ended. Sign in, then save again.",
   membership: "Join this site before saving.",
   permission: "You don't have permission to save this.",
+  unconfirmed: "Wix didn't confirm this, so it may or may not have been saved. Check before trying again.",
 };
 
 // The classifier below is `himi docs recipe-four-state`'s, VERBATIM — a test holds
@@ -106,6 +107,23 @@ function classifyError(e: unknown, authState: "signedIn" | "signedOut" | "unknow
 // "unknown": a 401 then reads as a session that ended.
 function currentAuthState(): "signedIn" | "signedOut" | "unknown" { return "unknown"; }
 
+// A failure with no HTTP answer may come after Wix took the write (a reset, a timeout, a bad or
+// truncated response); only one while CONNECTING proves nothing was sent. A 502–504 may have
+// landed too — the owner templates' `writeMayHaveLanded` rule.
+const NO_ANSWER = /NSURLErrorDomain|Error Domain=|\bjava\.(?:net|io)\.\w+|(?:UnknownHost|Connect|SocketTimeout|NoRouteToHost|SSLHandshake)Exception|^Failed to connect|^Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|ETIMEDOUT|EPIPE|Broken pipe|stream was reset|unexpected end of stream|timed out|^timeout$|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+const NEVER_SENT = /NSURLErrorDomain\D*?-10(?:09|04|03|06|20|18)\b|\b(?:UnknownHost|Connect|NoRouteToHost)Exception\b|^Failed to connect to \S|^Unable to resolve host\b|\b(?:Connection refused|Network is unreachable)\b|net::ERR_(?:INTERNET_DISCONNECTED|NAME_NOT_RESOLVED|CONNECTION_REFUSED|ADDRESS_UNREACHABLE|NETWORK_ACCESS_DENIED)\b|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+
+function writeMayHaveLanded(e: unknown): boolean {
+  const code = String((e as { code?: unknown })?.code ?? "");
+  const msg = String((e as Error)?.message ?? e ?? "");
+  if (code === "offline_write_blocked") return false;                  // refused before it left
+  if (code === "offline_write_outcome_unknown" || /"sent"\s*:\s*true/.test(msg)) return true;
+  // The web host's own envelope without "sent": true failed before the request left it.
+  if (/\bwebwix_(?:direct_failed|owner_disabled|bridge_disabled)\b/.test(msg)) return false;
+  if (/\b(?:HTTP|Wix) \d{3}\b/.test(msg)) return /\b(?:HTTP|Wix) (?:502|503|504)\b/.test(msg);
+  return NO_ANSWER.test(msg) && !NEVER_SENT.test(msg);
+}
+
 // Blog draft bodies are rich content — wrap the plain text minimally.
 function toRichContent(text: string): WixRichContent {
   return { nodes: [{ type: "PARAGRAPH", nodes: [{ type: "TEXT", textData: { text, decorations: [] } }] }] };
@@ -143,9 +161,11 @@ const svc = defineService<PostFormState, {
         });
       } catch (e) {
         const kind = classifyError(e, currentAuthState()) || "server";
+        // A failure after the request left may still have created the draft: say so.
+        const outcome = writeMayHaveLanded(e) ? "unconfirmed" : kind;
         // Echo what the user typed back into the prefill, so a failed save loses nothing.
         // Clear the last success line: a failed attempt must not also read "Draft created.".
-        return shape({ ...s, title, body, status: "error", error: SAVE_FAILED[kind], savedMessage: "" });
+        return shape({ ...s, title, body, status: "error", error: SAVE_FAILED[outcome], savedMessage: "" });
       }
     },
   },

package/guides/iap-pricing.md

@@ -50,6 +50,7 @@ when it registers the item with Apple:
 | `onlineProgram` | An Online Programs program | `onlineProgramItem(program, commercePrice)` |
 | `storesProduct` | A Wix Stores product | Build `{ kind: "storesProduct", id }` |
 | `pricingPlan` | A one-time Pricing Plans plan | Build `{ kind: "pricingPlan", id }` |
+| `wixVideo` | A Wix video with a one-time Sale price, in a channel that requires no subscription or plan | `wixVideoItem(channel, video)`; `undefined` for a free, rental-only or subscription-locked video |
 
 ## Add it to a worker
 

package/guides/iap-products.md

@@ -199,8 +199,8 @@ himi store iap draft --site <msid> --purchases-app <registration-id> --catalog-r
 ## Drafting the manifest from your Wix catalog
 
 You don't have to write the manifest by hand. `draft` reads the site's whole catalog —
-every page of Wix Stores (Catalog V3 or V1), Online Programs and Pricing Plans — and writes
-a manifest of everything that can be sold:
+every page of Wix Stores (Catalog V3 or V1), Online Programs, Pricing Plans and Wix Video — and
+writes a manifest of everything that can be sold:
 
 ```bash
 himi store iap draft --site <msid> --purchases-app <registration-id> --catalog-route <assigned-prefix> --apple-app 6450000001 \
@@ -210,8 +210,11 @@ himi store iap draft --site <msid> --purchases-app <registration-id> --catalog-r
 | Wix item | Drafted as |
 |---|---|
 | Digital store product, paid online program, one-time "unlimited" pricing plan | a non-consumable |
+| Wix video with a one-time Sale price above zero | a non-consumable, keyed by the video's 36-character id |
 | Physical product | skipped: physical goods are never sold through in-app purchase |
 | Recurring or time-limited pricing plan | skipped: App Store subscriptions are a separate API |
+| Rental-only video | skipped: a rental gives access for a limited time, which a one-time purchase cannot sell |
+| Video in a channel that requires a subscription or pricing plan | skipped: buying the video would not open it there |
 | Free, hidden (unpublished, archived or not visible) or unclassified item | skipped |
 | Item priced in another currency than the base territory | skipped |
 | Proven paid online group services and online-only event tickets | per-item consumables, with separate `.booking.` / `.ticket.` namespaces |
@@ -222,8 +225,12 @@ and supported forms are implemented, and their Apple sales are on since 2026-11-
 ([activation record](iap-bookings-events.md#activation--2026-11-03)). Provisioning support
 does not establish live checkout or shared-tier mapping support.
 
-- **Product ids come from the Wix id** (`<bundle>.product.<wix-id>`, and `.program.` or
-  `.plan.` for those sources), so drafting the same catalog again gives the same ids.
+- **Product ids come from the Wix id** (`<bundle>.product.<wix-id>`, and `.program.`,
+  `.plan.` or `.video.` for those sources), so drafting the same catalog again gives the same ids.
+- **Wix Video is read through its GraphQL gateway** (`manage.wix.com/_api/vod/public/graphql`;
+  Wix publishes no REST API for it) with the same site credential. A site without Wix Video simply
+  has no channels. When the gateway refuses the read (some credentials, such as an API key, may not
+  reach it), the draft says so in its notes ("no videos were drafted") and drafts the rest.
 - **Prices use the rule `atLeast`:** the lowest Apple price point at or above the Wix
   price. `plan` shows the Apple price each new product will get before anything is written.
 - **Names and descriptions are cut to Apple's limits,** and HTML becomes plain text.
@@ -503,7 +510,9 @@ Status labels `provisioning.priceSource` as `manifest` by default. `--refresh-wi
 authentication and reads the current site catalog without changing the manifest. It reports
 `provisioning.priceDrift: { wix, apple, wouldBe, currency, baseTerritory, source }` when Apple's price
 differs from the resolved target. Normal rounding is not drift. Missing or incomparable data is
-reported as `priceCheckIssue`; a failed catalog read never falls back to the manifest. A live check
+reported as `priceCheckIssue`; a failed catalog read never falls back to the manifest. When the Wix
+Video read fails and the manifest maps videos, `status --refresh-wix` and `draft --merge` fail with
+`wix_catalog_unavailable` instead of reporting those videos as missing. A live check
 does not reprice shared tiers. Drift or unavailable checks make the overall status incomplete.
 
 Only `atLeast` mismatches can plan a price edit. An `exact` mismatch remains a conflict even when
@@ -538,8 +547,10 @@ In order:
    of the provider's state, so a rerun connects it again (the call is safe to repeat), and a dry
    run for an app that is already registered reports this step `unverified` instead of planned.
 4. **One mapping per Wix item → Apple product, through Catalog `listProducts` / `createProduct`.** Online Programs map by program id, Wix Stores
-   digital products by product id, and one-time unlimited Pricing Plans by plan id (the ids the
-   purchase flow looks up), all only as non-consumables. A plan is mapped only when the site reads it
+   digital products by product id, one-time unlimited Pricing Plans by plan id, and Wix videos by
+   video id (the ids the purchase flow looks up), all only as non-consumables. A mapped video gets
+   its App Store price on the Videos screens; buying it is not available yet (prices only,
+   [checkout](iap-wix-checkout.md#wix-video-prices-only)). A plan is mapped only when the site reads it
    as one-time unlimited (one payment, valid until cancelled); a recurring, time-limited or archived
    plan is skipped. When the site's plans cannot be read, each plan is `failed` (`request_failed`,
    `unverified` in the dry-run diff) and not mapped. Other verticals, price tiers and consumable items

package/guides/iap-screen-adoption.md

@@ -21,7 +21,8 @@ and generated templates. Historical receipts retain their recorded amounts.
 | `himi-branded-lite-cart` | Full catalog app/item/options reference and quantity; line `total` | Refreshes the current cart and routes before payment; only verified physical regular carts keep checkout; Apple, mixed, multiple-digital, unknown and unverified digital carts are blocked |
 | `himi-store-cart` | Full catalog reference; line `total` | Consistent shared prices and suppressed Wix subtotal when routes are unsettled or Apple; remains read-only |
 | `himi-branded-lite-order` | Original catalog app/item/options and quantity | Preserves references; checks current routing and catalog facts before re-adding physical items; never reprices the paid receipt |
-| `video-courses-preview` / Atlas | `storeProductId`, plus course-specific member access mirror | Deferred: deployment and usable course access are unverified. Existing native digital-checkout guard remains; this pass does not introduce a Videos adapter |
+| `himi-branded-lite-videos`, `himi-branded-lite-video` (Videos, channel and Video screens) | Wix video ID (`wixVideo`); carousel and row `priceLine`, Video `priceText` / `priceNote` / `purchaseNote` | Shared pricing for videos with a one-time Sale price, in channels that require no subscription or plan. Prices only: no Buy; `wixVideoOrders` refuses while `VIDEOS_APPLE_SALES_ENABLED` is off. Home's video rail stays unpriced |
+| `video-courses-preview` / Atlas | `storeProductId`, plus course-specific member access mirror | Deferred: deployment and usable course access are unverified. Existing native digital-checkout guard remains; Atlas courses are Stores products, not Wix Video, so `wixVideoOrders` does not apply |
 | `wix-spaces-product-detail`, `wix-spaces-shop`, `wix-spaces-saved`, `wix-spaces-cart` | Legacy worker sources | Retired `fixtures/wix-spaces-clone/dev` descriptors still reference these workers; no active app or generated template consumer. Legacy pricing/checkout is not migrated or certified for managed Apple IAP |
 | `hip-shop-product`, `hip-shop-home`, `hip-shop-explore`, `hip-shop-saved`, `hip-shop-cart` | Legacy worker sources | Retired `fixtures/hip-shop/dev` descriptors reference these workers; no active app or generated template consumer. Legacy pricing/checkout is not migrated or certified for managed Apple IAP |
 | `family-cart` (Family Cart and Himi Game) | Demo household/game economy | Not a Wix purchase path; unchanged |

package/guides/qa-builds.md

@@ -199,7 +199,20 @@ by this job, and its temporary files. It preserves the agent's keychain; it does
 certificate or delete the original profile in Apple/Branded. A matching identity already in the
 keychain is refused before import so cleanup cannot delete a pre-existing identity.
 
-Outside that runner mode, Himi creates a temporary keychain and deletes it during cleanup. A
+A job that is killed before its cleanup runs (SIGKILL) leaves the customer's material behind, so
+each job records what it places before placing it: its signing folder (which holds the private key
+until it is imported), the identity it imports into the agent keychain, and every copy of the App
+Store Connect key (`~/.private_keys/AuthKey_<id>.p8`, also when it replaces a file already there,
+and the temporary copy `altool` reads). The records live in `~/.himalaya/customer-secret-claims` in the account home.
+At the start of the next customer build on that Mac, before the pre-existing check, Himi removes
+what a job whose process has ended recorded, and leaves alone what a running job recorded, since a
+Mac may run more than one job at once. A matching identity that a running job owns, or that no
+record names, is still refused. SIGTERM and process exit remove the key copies directly, as they do
+the signing directory.
+
+Outside that runner mode, Himi creates a temporary keychain and deletes it during cleanup. That
+keychain is recorded the same way before it is created, and the next customer build deletes one an
+ended job left (`security delete-keychain`, which also drops it from the search list). A
 missing password or keychain in agent-keychain mode fails the build instead of silently switching
 modes. Private key material does not enter job parameters or the public job record. The runner
 source SHA must advertise support for this protocol and be reachable from the pool before BYO

package/guides/recipe-dynamic-list.md

@@ -72,6 +72,22 @@ interface State {
 }
 ```
 
+Four-state's `shape()` spreads `...s`, so the cursors keep their values between
+transitions. Add the paging keys to its return, with defaults so they stay strings
+(the strict Tier-5 typecheck rejects an optional key), and an unbound
+`hideLoadMoreError` would show the row on iOS:
+
+```ts
+  nextCursor: s.nextCursor ?? "",
+  failedCursor: s.failedCursor ?? "",
+  hideLoadMoreError: !s.failedCursor,
+```
+
+Reset both cursors to `""` whenever the rows start over: a page-1 load (first
+load, pull-to-refresh, retry) takes `nextCursor` from its response, and a
+sign-in, membership or permission failure clears them with the rows — or a
+load-more row and its retry outlive the list they belonged to.
+
 `load()` fetches through a typed `@himalaya/wix-<domain>` client, normalizes, and
 recomputes the display strings. For Stores, start with V3
 `queryStoreProducts` / `getStoreProduct`; do not hand-call `/stores/v1/…`, which

package/guides/recipe-form-submit.md

@@ -112,7 +112,9 @@ const svc = defineService<FormState, {
         // Keep what the user typed (echo it back into the prefill), and say what
         // happened in their words — never e.message.
         const kind = classifyError(e, currentAuthState()); // from himi docs recipe-four-state
-        return { ...s, title, body, status: "error", error: SAVE_FAILED[kind], savedMessage: "" };
+        // A failure after the request left may still have created the draft: say so.
+        const outcome = writeMayHaveLanded(e) ? "unconfirmed" : kind;
+        return { ...s, title, body, status: "error", error: SAVE_FAILED[outcome], savedMessage: "" };
       }
     },
   },
@@ -126,7 +128,25 @@ const SAVE_FAILED: Record<string, string> = {
   signIn: "Your session has ended. Sign in, then save again.",
   membership: "Join this site before saving.",
   permission: "You don't have permission to save this.",
+  unconfirmed: "Wix didn't confirm this, so it may or may not have been saved. Check before trying again.",
 };
+
+// A failure with no HTTP answer may come after Wix took the write (a reset, a timeout, a bad or
+// truncated response); only one while CONNECTING proves nothing was sent. A 502–504 may have
+// landed too — the owner templates' `writeMayHaveLanded` rule.
+const NO_ANSWER = /NSURLErrorDomain|Error Domain=|\bjava\.(?:net|io)\.\w+|(?:UnknownHost|Connect|SocketTimeout|NoRouteToHost|SSLHandshake)Exception|^Failed to connect|^Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|ETIMEDOUT|EPIPE|Broken pipe|stream was reset|unexpected end of stream|timed out|^timeout$|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+const NEVER_SENT = /NSURLErrorDomain\D*?-10(?:09|04|03|06|20|18)\b|\b(?:UnknownHost|Connect|NoRouteToHost)Exception\b|^Failed to connect to \S|^Unable to resolve host\b|\b(?:Connection refused|Network is unreachable)\b|net::ERR_(?:INTERNET_DISCONNECTED|NAME_NOT_RESOLVED|CONNECTION_REFUSED|ADDRESS_UNREACHABLE|NETWORK_ACCESS_DENIED)\b|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+
+function writeMayHaveLanded(e: unknown): boolean {
+  const code = String((e as { code?: unknown })?.code ?? "");
+  const msg = String((e as Error)?.message ?? e ?? "");
+  if (code === "offline_write_blocked") return false;                  // refused before it left
+  if (code === "offline_write_outcome_unknown" || /"sent"\s*:\s*true/.test(msg)) return true;
+  // The web host's own envelope without "sent": true failed before the request left it.
+  if (/\bwebwix_(?:direct_failed|owner_disabled|bridge_disabled)\b/.test(msg)) return false;
+  if (/\b(?:HTTP|Wix) \d{3}\b/.test(msg)) return /\b(?:HTTP|Wix) (?:502|503|504)\b/.test(msg);
+  return NO_ANSWER.test(msg) && !NEVER_SENT.test(msg);
+}
 ```
 
 - **Field rules stay on the fields.** Required and format checks belong in the
@@ -164,7 +184,17 @@ reports on:
 For "open what I just created", expose the target from the worker
 (`savedScreenId` + a `hideSavedLink` boolean) and gate a button with the
 `hiddenWhen` modifier bound to it — see `apps/himi-owner-lite`'s
-`open_saved` button, and the four-state recipe for the gating idiom.
+`open_saved` button, and the four-state recipe for the gating idiom. Add both
+keys to `FormState`, set them on every outcome (`hideSavedLink: true` on a
+failure), and list them in the opt-out too, so a cold boot never links the last
+run's post — the runnable example does exactly this:
+
+```ts
+  savedScreenId: string;                    // in FormState
+  hideSavedLink: boolean;
+  // …
+  notHydrated: ["status", "error", "savedMessage", "savedScreenId", "hideSavedLink"],
+```
 
 ## Edit mode (prefill + same submit)
 

package/guides/recipe-four-state.md

@@ -50,6 +50,7 @@ function shape(s: Partial<State>): State {
   const errorKind: ErrorKind = status === "error" ? (s.errorKind || "server") : "";
   const blank = items.length === 0;   // nothing on screen to keep
   return {
+    ...s,   // the screen's own keys ride along: a list's nextCursor / failedCursor, a query
     status, items, errorKind,
     hideLoading: !(status === "loading" && blank),
     notEmpty: !(status === "ready" && blank),
@@ -116,7 +117,7 @@ function currentAuthState(): "signedIn" | "signedOut" | "unknown" { return "unkn
 async function load(s: State): Promise<State> {
   try {
     const items = (await fetchRows()).map(normalize);
-    return shape({ status: "ready", items });
+    return shape({ status: "ready", items });   // a fresh load starts over
   } catch (e) {
     const errorKind = classifyError(e, currentAuthState()); // use host/session state when available
     // Keep the rows: a refresh that fails must not blank a screen that had content —

package/guides/sdk-reference.json

@@ -2281,7 +2281,7 @@
         "name": "IAP_CATALOG_KINDS",
         "kind": "const",
         "jsdoc": "/** The Wix entity types `himi store iap` writes into its Wix→Apple mapping, so a mapping\n *  backend can serve that export without translating kinds. */",
-        "decl": "export const IAP_CATALOG_KINDS = [\"onlineProgram\", \"storesProduct\", \"pricingPlan\", \"bookingsService\", \"eventsTicket\"] as const;"
+        "decl": "export const IAP_CATALOG_KINDS = [\"onlineProgram\", \"storesProduct\", \"pricingPlan\", \"bookingsService\", \"eventsTicket\", \"wixVideo\"] as const;"
       },
       {
         "name": "IapCatalogKind",
@@ -2379,6 +2379,12 @@
         "jsdoc": "/** An Online Programs program as a shared IAP catalog item. A program without a Wix ID cannot be\n *  mapped (a title fallback is not an identity), so it has no item and its screen shows no price. */",
         "decl": "export function onlineProgramItem(program: { id?: string | null }, commerceDisplayPrice?: string): IapCatalogItem | undefined;"
       },
+      {
+        "name": "wixVideoItem",
+        "kind": "function",
+        "jsdoc": "/**\n * A Wix video as a shared IAP catalog item, only when the App Store may sell it: an enabled one-time\n * `SALE` price above zero, in a channel whose pricing was read and that requires neither a subscription\n * nor a pricing plan (a bought video stays locked there). Rental and subscription access are never sold.\n */",
+        "decl": "export function wixVideoItem(\n  channel: { pricing?: VideoPricingOption[] | null },\n  video: { id?: string | null; pricing?: VideoPricingOption[] | null },\n  commerceDisplayPrice?: string,\n): IapCatalogItem | undefined;"
+      },
       {
         "name": "PurchasesAppBinding",
         "kind": "interface",
@@ -2451,11 +2457,17 @@
         "jsdoc": "/** One-time unlimited plans sell through the App Store. Proven live in Sandbox on 2026-10-19: a member's\n *  online plan order is charged with one cashier item whose id is the plan id, so StartPayment maps it to the\n *  plan's Apple product, and the order reads ACTIVE and PAID. Recurring and time-limited plans stay outside\n *  this rule; their Billing lifecycle is unfinished. */",
         "decl": "export const PRICING_PLAN_APPLE_SALES_ENABLED = true;"
       },
+      {
+        "name": "VIDEOS_APPLE_SALES_ENABLED",
+        "kind": "const",
+        "jsdoc": "/**\n * Whether Wix Video videos sell through the App Store. OFF: prices only. A video with a one-time Sale\n * price above zero is mapped under its video id as a one-time unlock (`wixVideoItem`), and screens show\n * its App Store price, but no purchase path exists yet: Wix Video has no public order API, and the\n * Videos order adapter refuses every sale until this is on.\n */",
+        "decl": "export const VIDEOS_APPLE_SALES_ENABLED = false;"
+      },
       {
         "name": "AppleSaleOptions",
         "kind": "interface",
         "jsdoc": "/**\n * The one definition `himi store iap connect` writes mappings by and the mapping source reads them by,\n * keyed by catalog kind. wix-iap StartPayment maps the cashier order's single item id, and Online\n * Programs builds that order with the program id as the item id; programs are one-time unlocks.\n * Wix Stores and one-time unlimited Pricing Plans join only with their independent switches.\n */",
-        "decl": "export interface AppleSaleOptions {\n  storesAppleSalesEnabled?: boolean;\n  storesItemPaymentEnabled?: boolean;\n  pricingPlanAppleSalesEnabled?: boolean;\n  bookingsAppleSalesEnabled?: boolean;\n  eventsAppleSalesEnabled?: boolean;\n}"
+        "decl": "export interface AppleSaleOptions {\n  storesAppleSalesEnabled?: boolean;\n  storesItemPaymentEnabled?: boolean;\n  pricingPlanAppleSalesEnabled?: boolean;\n  bookingsAppleSalesEnabled?: boolean;\n  eventsAppleSalesEnabled?: boolean;\n  videosAppleSalesEnabled?: boolean;\n}"
       },
       {
         "name": "appleSaleRules",
@@ -2473,7 +2485,13 @@
         "name": "APPLE_PROVISIONING_RULES",
         "kind": "const",
         "jsdoc": "/** Catalog setup may precede activation; purchases still require the independent sales switches. */",
-        "decl": "export const APPLE_PROVISIONING_RULES: Readonly<Record<string, AppleSaleRule>> = {\n  ...APPLE_SALE_RULES, bookingsService: ATTENDANCE_SALE_RULE, eventsTicket: ATTENDANCE_SALE_RULE,\n};"
+        "decl": "export const APPLE_PROVISIONING_RULES: Readonly<Record<string, AppleSaleRule>> = {\n  ...APPLE_SALE_RULES, bookingsService: ATTENDANCE_SALE_RULE, eventsTicket: ATTENDANCE_SALE_RULE, wixVideo: VIDEO_SALE_RULE,\n};"
+      },
+      {
+        "name": "APPLE_PRICING_RULES",
+        "kind": "const",
+        "jsdoc": "/** What the mapping source prices by: every sale rule, plus the verticals whose App Store prices show\n *  before their purchase is on (Wix Video). A priced item with no sale rule has no checkout adapter. */",
+        "decl": "export const APPLE_PRICING_RULES: Readonly<Record<string, AppleSaleRule>> = { ...APPLE_SALE_RULES, wixVideo: VIDEO_SALE_RULE };"
       },
       {
         "name": "HostCallExpectation",
@@ -2873,7 +2891,7 @@
         "name": "\"./iap-verticals/index.js\"",
         "kind": "reexport",
         "jsdoc": "",
-        "decl": "export { onlineProgramOrders, pricingPlanOrders, storesProductOrders, bookingOrders, eventTicketOrders, classifyCart } from \"./iap-verticals/index.js\";"
+        "decl": "export { onlineProgramOrders, pricingPlanOrders, storesProductOrders, bookingOrders, eventTicketOrders, wixVideoOrders, classifyCart } from \"./iap-verticals/index.js\";"
       },
       {
         "name": "\"./order-refs.js\"",
@@ -5845,6 +5863,18 @@
         "jsdoc": "/** Capability version, for bundles that gate on min binary version. */",
         "decl": "export const version = 2;"
       },
+      {
+        "name": "\"./user-props.js\"",
+        "kind": "reexport",
+        "jsdoc": "",
+        "decl": "export { USER_PROPS_MAX_BYTES, type UserPropsErrorCode } from \"./user-props.js\";"
+      },
+      {
+        "name": "userProps",
+        "kind": "const",
+        "jsdoc": "/** The signed-in Wix user's small server-side per-app preference records. Enable with\n *  `wixPlatform: { userProps: { app: \"<name>\" } }` in `config.ts`. Rejects with `err.code`:\n *  `not_signed_in` (no Wix user — a member or visitor session counts as none), `not_configured`,\n *  `too_large`, `invalid_patch`, `request_failed`, or `unavailable` (web). */",
+        "decl": "export const userProps = {\n  /** The signed-in Wix user's props for the app named by `wixPlatform.userProps.app`. */\n  get(): Promise<Record<string, unknown>> {\n    return userPropsGet();\n  },\n  /** Deep-merge `patch` into a FRESH server read and write the result back; resolves with it.\n   *  The patch wins, objects merge recursively, arrays are replaced. Writes are serialized per\n   *  process natively, so concurrent writers (two workers, or an app service and a screen) never\n   *  lose each other's keys. Values must be JSON; a result over 64 KB rejects `too_large`. */\n  set(patch: Record<string, unknown>): Promise<Record<string, unknown>> {\n    return userPropsSet(patch);\n  },\n};"
+      },
       {
         "name": "\"./offline.js\"",
         "kind": "reexport",
@@ -24698,6 +24728,12 @@
         "http": "POST /online-programs/v3/participants/stats",
         "scope": "visitor"
       },
+      {
+        "name": "WixJoinApplicationPaymentStatus",
+        "kind": "type",
+        "jsdoc": "/** `JoinApplication.paymentStatus` (Join Applications v3). */",
+        "decl": "export type WixJoinApplicationPaymentStatus =\n  | \"NO_PAYMENT_REQUIRED\"\n  | \"PAYMENT_PENDING\"\n  | \"PAYMENT_IN_PROGRESS\"\n  | \"PENDING_OWNER_APPROVAL\"\n  | \"PAYMENT_SUCCESSFUL\"\n  | \"PAYMENT_FAILED\"\n  | \"PAYMENT_CANCELED\"\n  | string;"
+      },
       {
         "name": "WixJoinApplicationStatus",
         "kind": "type",
@@ -24708,7 +24744,7 @@
         "name": "WixJoinApplication",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface WixJoinApplication {\n  id?: string;\n  programId?: string;\n  memberId?: string;\n  status?: WixJoinApplicationStatus;\n  paymentStatus?: string;\n  /** Set once the application became a participant. */\n  participantId?: string;\n  createdDate?: string;\n  updatedDate?: string;\n}"
+        "decl": "export interface WixJoinApplication {\n  id?: string;\n  revision?: string;\n  programId?: string;\n  memberId?: string;\n  status?: WixJoinApplicationStatus;\n  paymentStatus?: WixJoinApplicationPaymentStatus;\n  /** Wix Payments / Pricing Plans data behind `paymentStatus` (order, offline transaction, plan ids, coupon). */\n  paymentInfo?: { paymentOrderId?: string; offlineTransactionId?: string; paidPlanIds?: string[]; couponId?: string };\n  /** Set once the application became a participant. */\n  participantId?: string;\n  createdDate?: string;\n  updatedDate?: string;\n}"
       },
       {
         "name": "WixGetCurrentJoinApplicationResponse",
@@ -24743,6 +24779,104 @@
         "decl": "export function listProgramCategories(): Promise<WixListProgramCategoriesResponse>;",
         "http": "GET /_api/program-categories-service/v3/categories",
         "scope": "member"
+      },
+      {
+        "name": "WixEnrollmentStatus",
+        "kind": "type",
+        "jsdoc": "/** Participant `enrollmentStatus` (Participants v3). */",
+        "decl": "export type WixEnrollmentStatus =\n  | \"JOINED\"\n  | \"SUSPENDED\"\n  | \"AUTO_REMOVED\"\n  | \"REMOVED\"\n  | \"LEFT\"\n  | string;"
+      },
+      {
+        "name": "WixProgressStatus",
+        "kind": "type",
+        "jsdoc": "/** Participant `progressStatus` (Participants v3). */",
+        "decl": "export type WixProgressStatus =\n  | \"NOT_STARTED\"\n  | \"IN_PROGRESS\"\n  | \"COMPLETED\"\n  | \"FAILED\"\n  | \"NOT_APPLICABLE\"\n  | string;"
+      },
+      {
+        "name": "listMyParticipations",
+        "kind": "function",
+        "jsdoc": "/**\n * Every page of `queryMemberParticipants`, concatenated — the member's whole membership snapshot,\n * which `participationsByProgram` then matches to the programs on screen. Bounded by `maxPages`\n * (default 10; at the upstream page cap of 100 that is at most 1,000 rows) so a runaway cursor\n * can never spin a worker forever. The server filter of `queryMemberParticipants` already leaves\n * out enrollments the member left or was removed from, so a program the member left and never\n * re-joined simply has no row here; this walk adds no filter of its own.\n *\n * @scope member — requires the signed-in site member; `memberId` must be that member's own id.\n */",
+        "decl": "export async function listMyParticipations(memberId: string, opts: { maxPages?: number } = {}): Promise<WixParticipant[]>;",
+        "scope": "member"
+      },
+      {
+        "name": "participationsByProgram",
+        "kind": "function",
+        "jsdoc": "/**\n * The participation to show per program when a member has several rows for one program: the\n * NEWEST by `createdDate` wins — the One App member-list rule. Participants without a `programId`\n * are skipped. Defensive, for a caller that feeds a BROADER read than `listMyParticipations`\n * (whose server filter already omits them): a withdrawn enrollment (LEFT / REMOVED / AUTO_REMOVED)\n * is dropped only AFTER the newest row is chosen, so a newer withdrawal can never resurrect an\n * older joined row, and a re-join after a leave is the standing.\n */",
+        "decl": "export function participationsByProgram(participants: readonly WixParticipant[]): Map<string, WixParticipant>;"
+      },
+      {
+        "name": "WixQueryJoinApplicationsResponse",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixQueryJoinApplicationsResponse {\n  joinApplications?: WixJoinApplication[];\n  pagingMetadata?: { count?: number; total?: number; hasNext?: boolean; cursors?: { next?: string | null; prev?: string | null } };\n}"
+      },
+      {
+        "name": "PENDING_JOIN_APPLICATION_STATUSES",
+        "kind": "const",
+        "jsdoc": "/** `JoinApplication.status` values that describe a member BEFORE they are a participant — the ones a\n *  card shows. Payment is NOT a status: an approved-but-unpaid application stays `APPROVED` with\n *  `paymentStatus` PAYMENT_PENDING (what `joinProgram` above reads), so `APPROVED` covers it and the\n *  caller reads `paymentStatus` to tell \"pay to join\" from \"joined, participant pending\". An\n *  application that already became a participant keeps its status and carries `participantId`:\n *  callers prefer the participation and ignore such rows. */",
+        "decl": "export const PENDING_JOIN_APPLICATION_STATUSES: readonly WixJoinApplicationStatus[] = Object.freeze([\n  \"INVITED\",\n  \"APPROVAL_PENDING\",\n  \"APPROVED\",\n  \"SUSPENDED\",\n]);"
+      },
+      {
+        "name": "JoinApplicationsQuery",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface JoinApplicationsQuery {\n  memberId: string;\n  /** Programs to look at; omitted reads the member's open applications across every program. An empty list makes no call. */\n  programIds?: readonly string[];\n  /** Defaults to the pre-participant statuses (`PENDING_JOIN_APPLICATION_STATUSES`). */\n  statuses?: readonly WixJoinApplicationStatus[];\n  /** Page size, 1..100; defaults to the cap (100). A member can hold several applications to one program\n   *  (an old approved one that became a participant, a new pending re-application), so the page is never\n   *  sized to the program count. */\n  limit?: number;\n  /** `pagingMetadata.cursors.next` of the previous page. A cursor page carries NO filter, per the API. */\n  cursor?: string;\n}"
+      },
+      {
+        "name": "queryJoinApplications",
+        "kind": "function",
+        "jsdoc": "/**\n * The member's open join applications for a set of programs in ONE call — what says \"pending\n * request\", \"request approved, pay to join\" or \"invited\" before any participant exists. The\n * per-program `getCurrentJoinApplication` above answers one program; this answers a page.\n *\n * `POST /online-programs/participants/v3/join-applications/query`.\n *\n * @scope member — requires the signed-in site member; the reference states a member may read their own applications.\n */",
+        "decl": "export function queryJoinApplications(query: JoinApplicationsQuery): Promise<WixQueryJoinApplicationsResponse>;",
+        "http": "POST /online-programs/participants/v3/join-applications/query",
+        "scope": "member"
+      },
+      {
+        "name": "listJoinApplications",
+        "kind": "function",
+        "jsdoc": "/**\n * Every page of `queryJoinApplications`, concatenated, bounded by `maxPages` (default 5 → at most\n * 500 applications). What a page of program cards reads when the member's applications may exceed\n * one page; the single-page call is enough for one program.\n *\n * @scope member — requires the signed-in site member; reads that member's own applications.\n */",
+        "decl": "export async function listJoinApplications(query: Omit<JoinApplicationsQuery, \"cursor\">, opts: { maxPages?: number } = {}): Promise<WixJoinApplication[]>;",
+        "scope": "member"
+      },
+      {
+        "name": "WixCancelJoinApplicationResponse",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixCancelJoinApplicationResponse { joinApplication?: WixJoinApplication }"
+      },
+      {
+        "name": "cancelJoinApplication",
+        "kind": "function",
+        "jsdoc": "/**\n * Withdraw the member's own pending request — the \"Cancel request\" action on a card whose\n * application is `APPROVAL_PENDING`. This is request withdrawal ONLY: an invitation (`INVITED`)\n * is answered with the separate `…/{id}/decline` operation, which this SDK does not bind, and\n * the cancel route rejects it with an invalid-status error. The application moves to `CANCELLED`\n * and is removed asynchronously, so a list read right after may still show it — re-read, do not\n * assume.\n *\n * `POST /online-programs/participants/v3/join-applications/{id}/cancel`.\n *\n * @scope member — requires the signed-in site member withdrawing their own application.\n */",
+        "decl": "export function cancelJoinApplication(joinApplicationId: string): Promise<WixCancelJoinApplicationResponse>;",
+        "http": "POST /online-programs/participants/v3/join-applications/{…}/cancel",
+        "scope": "member"
+      },
+      {
+        "name": "participantsShownByProgram",
+        "kind": "function",
+        "jsdoc": "/** `participantsCount + autoRemovedCount` per program — the number the One App card prints as \"N participants\". */",
+        "decl": "export function participantsShownByProgram(response: WixGetParticipationStatsResponse): Map<string, number>;"
+      },
+      {
+        "name": "WixGetPremiumStatsResponse",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixGetPremiumStatsResponse {\n  premiumEnabled?: boolean;\n  activeParticipantsCount?: number;\n  activeParticipantsLimit?: number;\n}"
+      },
+      {
+        "name": "getPremiumStats",
+        "kind": "function",
+        "jsdoc": "/**\n * Whether the site's Online Programs are over the free-tier participant cap — the One App hides a\n * joined card's progress and price while this holds.\n * `GET /online-programs/participants/v3/stats/premium`.\n *\n * @scope member — exercised with a signed-in member session; the reference lists only the Manage scope (see the section note).\n */",
+        "decl": "export function getPremiumStats(): Promise<WixGetPremiumStatsResponse>;",
+        "http": "GET /online-programs/participants/v3/stats/premium",
+        "scope": "member"
+      },
+      {
+        "name": "isParticipationBlocked",
+        "kind": "function",
+        "jsdoc": "/** True when participation is blocked by the free-tier cap (no premium, count over limit). */",
+        "decl": "export function isParticipationBlocked(stats: WixGetPremiumStatsResponse | undefined): boolean;"
       }
     ]
   },
@@ -27201,8 +27335,8 @@
       {
         "name": "CHANNEL_FIELDS",
         "kind": "const",
-        "jsdoc": "/** The channel fields a list or card needs. */",
-        "decl": "export const CHANNEL_FIELDS = \"id title description source featuredVideoId hasPaidVideos cover { selected } videos { total }\";"
+        "jsdoc": "/** The channel fields a list or card needs, including the viewer's subscription (`canWatchVideo`). */",
+        "decl": "export const CHANNEL_FIELDS = \"id title description source featuredVideoId hasPaidVideos cover { selected } pricing { type enabled required } purchase(filter: {type: SUBSCRIPTION}) { status expiresAt } videos { total }\";"
       },
       {
         "name": "CHANNEL_ACCESS_FIELDS",
@@ -27213,14 +27347,14 @@
       {
         "name": "VIDEO_CARD_FIELDS",
         "kind": "const",
-        "jsdoc": "/** The video fields a card needs: title, images, length and processing state. */",
-        "decl": "export const VIDEO_CARD_FIELDS = \"id title source status cover { selected } poster { selected } content { status duration thumbnailUrl externalUrl externalId } pricing { type enabled }\";"
+        "jsdoc": "/** The video fields a card needs: title, images, length, processing state, and the pricing and the\n *  viewer's purchases an access decision needs (`canWatchVideo`). */",
+        "decl": "export const VIDEO_CARD_FIELDS = \"id title source status cover { selected } poster { selected } content { status duration thumbnailUrl externalUrl externalId } pricing { type enabled price currency } purchase(filter: {type: SALE}) { status } rent_purchase: purchase(filter: {type: RENT}) { status }\";"
       },
       {
         "name": "VIDEO_FIELDS",
         "kind": "const",
         "jsdoc": "/** The video fields playback and an access decision need. */",
-        "decl": "export const VIDEO_FIELDS = \"id title description source status cover { selected } poster { selected } content { status duration thumbnailUrl externalUrl externalId } pricing { type enabled } purchase(filter: {type: SALE}) { status } rent_purchase: purchase(filter: {type: RENT}) { status }\";"
+        "decl": "export const VIDEO_FIELDS = \"id title description source status cover { selected } poster { selected } content { status duration thumbnailUrl externalUrl externalId } pricing { type enabled price currency } purchase(filter: {type: SALE}) { status } rent_purchase: purchase(filter: {type: RENT}) { status }\";"
       },
       {
         "name": "ListChannelsOptions",

package/guides/web-page-sdk-reference.md

@@ -57,4 +57,4 @@ the SDK sources, so it matches the shipped SDKs.
 - [`ui`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fui?format=md) — Imperative popup capability. 2 methods · not in Brandy.
 - [`wix_cashier`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_cashier?format=md) — Native cashier. 2 methods.
 - [`wix_chat`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_chat?format=md) — Host-owned realtime Chat event subscriptions. 2 methods.
-- [`wix_platform`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_platform?format=md) — Wix Platform SDK, worker-facing bindings. 27 methods · not in Brandy.
+- [`wix_platform`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_platform?format=md) — Wix Platform SDK, worker-facing bindings. 29 methods · not in Brandy.

package/guides/wix-platform-usage.md

@@ -58,6 +58,7 @@ await monitoring.captureError("thing failed", { code: "E1" });
 | `session` | `headers()`, `signedInstanceStatus()` |
 | `auth` | `getIdentity()`, `isAuthenticated()`, `getAccessToken()`, `signIn()`, `signOut()`, `signedInstance(businessId, type?)` |
 | `monitoring` | `captureError(msg, extra?)`, `captureException(class, msg, extra?)`, `setUser(id, traits?)`, `setTag(k, v)`, `addBreadcrumb(msg)` |
+| `userProps` | `get()`, `set(patch)` — the signed-in Wix user's server-side per-app preferences ([below](#userprops--server-side-per-user-preferences)) |
 | `version` | the SDK surface version constant |
 
 ## Real vs dev seam — and best-effort
@@ -116,6 +117,43 @@ sign-in from a successful one, so a correct four-state screen still showed a dea
 web member path itself is a login bridge that only a local dev host serves; a hosted preview
 is visitor-only. See [wix-login-integration](wix-login-integration.md) for that whole picture.
 
+## `userProps` — server-side per-user preferences
+
+Small per-user, per-app records kept on Wix's servers, so they survive a reinstall and follow
+the user across devices (e.g. "the user already saw the publish prompt"). Enable it with the app
+name the records live under:
+
+```ts
+// apps/<app>/config.ts
+wixPlatform: { userProps: { app: "my-app" } },
+```
+
+```js
+import { userProps } from "@himalaya/wix-platform";
+
+const props = await userProps.get();                       // Record<string, unknown>
+const merged = await userProps.set({ prompts: { publish: true } });
+```
+
+- `set(patch)` deep-merges `patch` into a **fresh** server read and writes the result back:
+  the patch wins, objects merge recursively, arrays are replaced. The server write replaces the
+  whole record, so the read-merge-write runs natively and is **serialized per process** — two
+  workers (or an app service and a screen) writing at once never lose each other's keys.
+- Values are JSON; a result over 64 KB rejects `too_large`. `platform` is reserved as a
+  top-level key (it is the server namespace the props live under), so a patch that sets it
+  rejects `invalid_patch`; nested `platform` keys are ordinary data.
+- Like `auth.signIn()`, it **rejects** with an `err.code`: `not_signed_in` (no Wix user — a site
+  member or visitor session counts as none, since these records belong to a Wix account),
+  `not_configured` (no `wixPlatform.userProps.app`), `request_failed`, `invalid_patch`, and
+  `unavailable` on web, where the host has no transport for the write. Handle the rejection;
+  for data that need not follow the user, local storage is the simpler choice.
+- iOS, macOS (shares the iOS runtime) and Android read `GET apps.wix.com/_api/app-state/v1/user/<app>/state`
+  and write `PUT apps.wix.com/_api/mobile-client-storage/v1/user-preferences` through the app's
+  account-level owner Wix transport, the one the shell's own `HimalayaWixCache.wrap` binds. A
+  per-site chain never replaces it, and a Himi Player tenant does not bind it yet, so there it
+  answers `not_signed_in`. A user-state response the runtime cannot read rejects
+  `request_failed` and writes nothing, because the write replaces the whole record.
+
 ## Testing a worker that uses the SDK
 
 Fake the SDK's dispatch (the members call `dispatch("capability.wix_platform.<method>")`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1608.0",
+  "version": "0.1610.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": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "1bec846ad5466a0b26a35a61f3e2e514b5c39c2f5376641b9ae23195"
+  "falconPackageHash": "fd34bb941dc2b1092069d5876a747cc0048164fc1b1ce148a32257b2"
 }