@wix/himalaya-cli 0.1386.0 → 0.1388.0

package/guides/branded-lite-site-binding.md

@@ -16,13 +16,20 @@ on conflict: [`apps/himi-branded-lite/config.ts`](../apps/himi-branded-lite/conf
 
 If you scaffolded from the `branded-lite` template with the standalone CLI
 (`himi init my-app --template branded-lite`) and have **no monorepo checkout**, the whole
-site binding is **two values**, and nothing on this page below this section applies to you:
+site binding is **three values**, and nothing on this page below this section applies to you:
 
 ```sh
 export WIX_CLIENT_ID="<your-headless-oauth-client-id>"
 export WIX_SITE_URL="https://your-site.wixsite.com/…"
+export WIX_SITE_ID="<metasite-id>"
 ```
 
+`WIX_SITE_ID` is the site that client belongs to. Reads need only the client, but a native
+build matches its member sign-up CAPTCHA key, push registration and IAP binding against the
+site: without it, sign-up on a CAPTCHA-protected site is refused. The member login takes it
+from the environment while `WIX_CLIENT_ID` is the client the config uses
+([member-captcha-native.md](member-captcha-native.md)).
+
 Don't have the client id? You no longer have to go and copy it out of the dashboard —
 `himi site client ensure --site <msid> --yes` resolves the site's Headless client (reusing
 one that already carries your redirect, or minting one with it registered) and prints the
@@ -39,9 +46,9 @@ failing at redirect-session with "no auth code". `himi site list` shows the site
 already have.
 
 — or hardcode them directly in your app's [`config.ts`](../apps/himi-branded-lite/config.ts)
-(`WixConsumerAuthProvider({ clientId: "…", siteUrl: "…" })`). The Headless **`clientId` is the
-binding**; `metaSiteId` follows from the visitor token that client mints. That's it — the app now
-reads that site's real catalog. (Leaving the shipped `YOUR_WIX_CLIENT_ID` placeholder in place makes
+(`WixConsumerAuthProvider({ clientId: "…", siteUrl: "…", siteId: "…" })`). The Headless
+**`clientId` binds the data**; reads take the `metaSiteId` from the visitor token that client mints,
+so the app now reads that site's real catalog. The native features above still need `siteId`. (Leaving the shipped `YOUR_WIX_CLIENT_ID` placeholder in place makes
 the app boot and read nothing; `himi validate` now warns when it's unreplaced.)
 
 Binding is **step 1 of integrating the app with the website**. To duplicate the site's
@@ -119,7 +126,7 @@ himalaya-dev app open himi-branded-lite device
 1. Set the env vars in the environment that runs the **dev-server / gen / Xcode / Gradle** process.
 2. Rebuild or re-run gen so `auth.json` picks up the new values if you are not relying on a live env override at boot.
 
-Off-repo (`himi init --template branded-lite`): set `WIX_CLIENT_ID` and `WIX_SITE_URL` the same way — the generated `config.ts` reads those names.
+Off-repo (`himi init --template branded-lite`): set `WIX_CLIENT_ID`, `WIX_SITE_URL` and `WIX_SITE_ID` the same way — the generated `config.ts` reads the first two, and the member login pairs `WIX_SITE_ID` with `WIX_CLIENT_ID`.
 
 ### Where does MSID fit?
 

package/guides/himi-json-output.md

@@ -92,13 +92,23 @@ statuses are preserved: incomplete status is exit 1; a failed live Wix catalog r
 
 Item-level unavailable checks take precedence over drift in the top-level code. Detailed
 `priceSource`, `priceDrift` and `priceCheckIssue` fields live in each item's `provisioning` report.
-Manifest parsing failures retain their legacy envelopes; this is not a whole-command migration.
+An invalid manifest, including a `reviewScreenshot` file that is missing or not a PNG or JPEG,
+fails with `manifest_invalid`, and `problems` lists every reason. This is not a whole-command migration.
 
 IAP provisioning refusals from `plan`, `apply` and `status` also expose their existing typed
 `reason` as a top-level `code`: `target` (wrong app, bundle, team or territory), `access`
 (Apple authentication/authorization), `plan` (invalid reviewed plan), `account` (changed
 credential profile or key), and `drift` (Apple changed since planning). Existing `reason` and
-exit statuses remain intact. Manifest parsing failures still use their legacy envelope.
+exit statuses remain intact. An invalid manifest carries `manifest_invalid` alongside its
+existing `problems` list.
+
+## `himi store iap screenshots` codes
+
+| Code | Meaning |
+|---|---|
+| `screenshots_incomplete` | At least one selected item has no screenshot. Each one in `items` carries a `skipped` reason: no purchase screen, no Apple price yet, an existing screenshot kept without `--force`, a screen that did not show the Apple price, or a failed read of the item. The screenshots that were made are saved and named in the manifest. Exit 1. |
+
+An invalid manifest fails with `manifest_invalid`, like the other `store iap` commands.
 
 ## `himi store iap connect` codes
 

package/guides/iap-products.md

@@ -112,7 +112,8 @@ and nothing is crawled from a Wix catalog.
         { "locale": "en-US", "name": "Nutrition Program", "description": "Lifetime access to the nutrition plan." }
       ],
       "price": { "baseTerritory": "USA", "currency": "USD", "amount": "0.99" },
-      "territories": ["USA", "CAN"]
+      "territories": ["USA", "CAN"],
+      "reviewScreenshot": "screens/nutrition-program.png"
     }
   ]
 }
@@ -138,6 +139,13 @@ Rules, all checked locally before any request:
   reference name at most 64, product id at most 100, review note at most 4,000.
 - **`territories`** is an explicit list that includes the base territory. Availability
   never extends to future territories automatically.
+- **`reviewScreenshot`** (optional) is a PNG or JPEG of the purchase as it appears in your
+  app, for Apple's reviewer only; customers never see it. The path is relative to the
+  manifest's folder (or absolute). Without a screenshot, a product stays `MISSING_METADATA`
+  and can't be submitted. Every named file must exist and be a PNG or JPEG before `plan`
+  sends a request. Apple accepts any App Store screenshot size your app supports, so a
+  full-size iPhone screenshot is safest. `plan` warns about a size it doesn't recognize,
+  and Apple decides.
 - **Duplicates are refused:** a product id, Wix entity, entitlement or reference name
   used twice, including a Wix entity mapped both directly and through a tier.
 - **Unknown keys are refused, at every level.** So is any string that looks like a key or a token.
@@ -149,6 +157,7 @@ himi store iap draft  --site <msid> --profile fit-club-owner --apple-app 6450000
 himi store iap plan   --manifest ./iap-products.json --profile fit-club-owner --out ./iap-plan.json
 himi store iap apply  --plan ./iap-plan.json --profile fit-club-owner --out ./iap-result.json
 himi store iap status --manifest ./iap-products.json --profile fit-club-owner --json
+himi store iap screenshots --manifest ./iap-products.json --content . --profile fit-club-owner
 himi store iap connect --manifest ./iap-products.json --profile fit-club-owner \
   --iap-key ~/keys/SubscriptionKey_ABCD123456.p8 --iap-key-id ABCD123456 --content . --dry-run
 ```
@@ -172,7 +181,7 @@ A **conflict** is any of:
 
 - the same product id with another type;
 - the reference name already used by another product id;
-- a live product whose metadata or availability differs, or an in-review product needing changes;
+- a live product whose metadata, availability or review screenshot differs, or an in-review product needing changes;
 - an existing `exact` price or availability that differs;
 - a price change with a different base territory, ambiguous price, custom territory prices, or a future/temporary schedule;
 - no Apple point satisfying the requested price rule, or an unknown product/review state needing changes.
@@ -200,12 +209,78 @@ created. The plan marks this in the item's `notes`.
    - If anything changed that the plan did not list (**drift**), it stops before the first
      write. Planned work that already happened is accepted as done.
 4. For each product, it creates the product, then a draft version, then its
-   localizations. Then it sets the exact initial price and the explicit territories. Then
-   it reads everything back. A `changePrice` instead writes an immediate base-territory price
+   localizations. Then it sets the exact initial price and the explicit territories, and
+   uploads the review screenshot. Then it reads everything back. A `changePrice` instead writes an immediate base-territory price
    through the same price-schedule API; Apple equalizes the other territories. A changed source
    price, schedule, review state or resolved target stops apply before the first write.
 5. Writes the result file, even when the run is partial.
 
+**The review screenshot** is uploaded the way App Store Connect expects. Apply reserves it,
+PUTs each part to the upload URLs Apple returns, and commits the file's MD5. Apple's storage
+hosts only ever get the file's bytes, never the API key's token.
+
+- **Identified by checksum.** Apple keeps the MD5 as `sourceFileChecksum`. A screenshot with
+  the same checksum is reused. A different file, an unfinished upload, or an image Apple
+  refused is planned as `replaceReviewScreenshot`.
+- **Never deleted while valid.** Apple keeps one screenshot per product, and documents it as
+  "can be updated but not removed". A replacement asks Apple for a new upload over the old one;
+  if Apple refuses a second one, the step fails and says to replace it in App Store Connect. Only
+  what an interrupted or refused upload left behind (no finished image) is cleared first.
+- **Locked once live.** The screenshot of a live or in-review product is never changed. A
+  different file there is a conflict.
+- **Bytes fixed at plan time.** The plan records each file's checksum, and apply re-reads
+  the file. A file edited after `plan` stops apply as drift before any write.
+- **Read back.** Apple processes the image after the commit, and apply waits briefly for
+  the result. A refused image (`FAILED`) fails the step with Apple's reason. An image still
+  processing (`UPLOAD_COMPLETE`) counts as uploaded.
+
+### Making the review screenshots: `screenshots`
+
+`himi store iap screenshots --manifest <file> --content <app dir> [--profile <name>]` makes each
+product's review screenshot from the app's own purchase screen, so nobody has to take them on a phone:
+
+1. **It renders the screen.** For each item it opens that Wix item's detail screen: `himi_product_<id>`,
+   `himi_program_<id>` or `himi_plan_<id>`, or the plain screen given the `id` when the app has no such
+   route. For a plan it falls back to the plans list (`himi_plans`), where older apps sell plans. The
+   screen loads with live Wix data.
+2. **It renders as the device would.** The render answers what a bound iPhone answers for a signed-in member of the site:
+   - the app's purchases binding;
+   - the item's App Store mapping;
+   - Apple's price;
+   - the member session. The stand-in member is new, so its own plan orders read as none.
+
+   The screen's own pricing and checkout code then paints the Apple price and an enabled buy button,
+   as the member sees them. Nothing is sent to wix-iap or Apple, and no member is signed in anywhere.
+3. **It checks the result.** A picture is kept only when three things hold:
+   - the screen shows Apple's price;
+   - its own state offers the purchase, meaning an enabled buy action, or an enabled join on a plan row;
+   - its read of the item succeeded.
+
+   A screen that fell back to "not available", showed no buy action, or failed to load the item is
+   reported, never saved.
+4. **It saves.** It writes `review-screenshots/<productId>.png` next to the manifest, at 1290×2796
+   (the largest-iPhone App Store size). It then sets each item's `reviewScreenshot` to that file,
+   leaving the rest of the manifest as it was.
+
+**Apple's price** comes from App Store Connect when you pass `--profile`, a read-only call. Otherwise it is
+the manifest's `exact` amount. An `atLeast` item that Apple has no price for yet is skipped: run `apply`
+first. A price tier has no single purchase screen and is skipped too.
+
+**Other options:**
+- With `--profile`, a product that is live or in review keeps its screenshot: changing it there is a
+  conflict anyway.
+- An item that already names a screenshot is kept unless you pass `--force`.
+- `--only <productId,…>` limits the run; an id the manifest doesn't have is reported.
+- `--dry-run` lists what would be rendered.
+- `--out-dir` puts the files elsewhere.
+
+The render reads Wix with a visitor token. A screen whose item a visitor cannot read is reported with
+the failing read; take that screenshot on a phone, or fix the screen. A plan detail screen that reads
+`GET /pricing-plans/v2/plans/<id>` gets a 403 as a visitor, while the public plans list works. The
+templates read the public list since #4256.
+
+Then run `plan` and `apply` as usual: they upload the screenshots.
+
 **Large catalogs.** App Store Connect allows about 3,600 API requests an hour per key.
 Registering a new product takes about ten, and each run also lists the app's products once.
 
@@ -225,8 +300,9 @@ Apple again before doing anything else:
 - A write is repeated **at most once**, and only after that read proves it didn't land.
 - An outcome that is still unknown stops that product as `partial`.
 
-So rerunning the same plan never creates a second product, version, locale or price
-schedule, even without the local journal. Nothing is ever deleted or rolled back.
+So rerunning the same plan never creates a second product, version, locale, price
+schedule or screenshot, even without the local journal. Nothing is rolled back, and the only
+thing ever deleted is an unfinished or refused screenshot upload, never a finished screenshot.
 
 **`status` is read-only.** It reports what Apple has for each product. Add `--out <file>`
 to save it in the same shape as the result file.
@@ -333,6 +409,8 @@ Each item has two parts:
   - per-step states and any conflicts
   - `unmet` — where Apple still differs from the manifest
   - the requested and observed price, availability and locales
+  - `reviewScreenshot` — for an item that names one, the requested file name and the file
+    name and processing state Apple holds
   - the draft version and Apple's review state
   - `remainingRequirements`
   - `lastReadAt`
@@ -354,12 +432,14 @@ future importer must authenticate ownership and re-read Apple before activating
 
 ## What is still yours to do
 
-- **Finish the product in App Store Connect.** Upload the App Review screenshot and add
-  anything else App Store Connect lists as missing. `remainingRequirements` names what
-  Apple reports.
+- **Finish the product in App Store Connect.** Add anything App Store Connect still lists
+  as missing. `remainingRequirements` names what Apple reports, including a missing review
+  screenshot when the item names none.
 - **Handle the business side.** Paid Apps agreement, banking and tax information go
   through the owner's App Store Connect account.
-- **Submit for review.** Submit the product with an app version. This command never
+- **Submit for review.** Your first in-app purchases must be submitted together with an
+  app version: attach them to the version in App Store Connect before you submit it (see
+  `/submit-ios-app`). Later ones can be submitted on their own. This command never
   submits, and never makes a product available for sale.
 - **Allow for Sandbox delay.** Product changes can take a while to appear in Sandbox
   purchase testing. Sandbox is for purchases, not a separate product catalogue:
@@ -368,7 +448,7 @@ future importer must authenticate ownership and re-read Apple before activating
 Not in this version:
 
 - subscriptions
-- review screenshot upload and submission
+- submitting products for review
 - changing a live price
 - Google Play
 - the build-time binding bake and the screens' checkout (the companion PR)

package/guides/importable-sdks.md

@@ -129,4 +129,5 @@ direction the platform is heading — recommended, not required). Usage is unifo
 - `@himalaya/wix-stores-collections` — Stores — product collections
 - `@himalaya/wix-table-reservations` — Restaurant table reservations
 - `@himalaya/wix-users` — Current Wix user / account profile
+- `@himalaya/wix-video` — Wix Video — channels, videos, covers, durations, playback (native apps; the web bridges refuse its gateway)
 - `@himalaya/wix-workflows` — Wix workflows — typed REST client

package/guides/sdk-reference.json

@@ -24613,6 +24613,259 @@
       }
     ]
   },
+  {
+    "name": "@himalaya/wix-video",
+    "source": "stdlib/wix-sdk/video/src/index.ts",
+    "description": "Wix Video — channels, videos, covers, durations, playback (native apps; the web bridges refuse its gateway)",
+    "api": [
+      {
+        "name": "isHostedVideo",
+        "kind": "function",
+        "jsdoc": "/** True for a video whose file Wix hosts (it plays through `getVideoStreamUrl`). */",
+        "decl": "export function isHostedVideo(video: WixVideo): boolean;"
+      },
+      {
+        "name": "isVideoReady",
+        "kind": "function",
+        "jsdoc": "/** True when the video is published AND its media is ready to play. */",
+        "decl": "export function isVideoReady(video: WixVideo): boolean;"
+      },
+      {
+        "name": "isVideoProcessing",
+        "kind": "function",
+        "jsdoc": "/** True while an upload is still being processed (try again later). */",
+        "decl": "export function isVideoProcessing(video: WixVideo): boolean;"
+      },
+      {
+        "name": "youtubeVideoId",
+        "kind": "function",
+        "jsdoc": "/** The 11-character YouTube id of a linked YouTube video, or \"\". The embed URL is\n *  treated as data: only the id is taken, never the URL itself. */",
+        "decl": "export function youtubeVideoId(video: WixVideo): string;"
+      },
+      {
+        "name": "videoCoverUrl",
+        "kind": "function",
+        "jsdoc": "/**\n * The video's card image, sized for display: the owner's cover, then the poster, then\n * the media thumbnail, then (for a YouTube video) YouTube's own thumbnail. \"\" when there\n * is none, so a card can show its placeholder.\n *\n * Wix media goes through `wixMediaUrl`: a stored cover is the untouched upload.\n */",
+        "decl": "export function videoCoverUrl(video: WixVideo, size: WixImageSize | null = WIX_LIST_IMAGE): string;"
+      },
+      {
+        "name": "channelCoverUrl",
+        "kind": "function",
+        "jsdoc": "/** The channel's cover image, sized for display, or \"\". */",
+        "decl": "export function channelCoverUrl(channel: WixVideoChannel, size: WixImageSize | null = WIX_LIST_IMAGE): string;"
+      },
+      {
+        "name": "videoDurationSec",
+        "kind": "function",
+        "jsdoc": "/** The video's length in whole seconds, or undefined when the gateway gives none. */",
+        "decl": "export function videoDurationSec(video: WixVideo): number | undefined;"
+      },
+      {
+        "name": "formatVideoDuration",
+        "kind": "function",
+        "jsdoc": "/** \"0:23\", \"4:05\", \"1:02:03\". \"\" for an unknown length. */",
+        "decl": "export function formatVideoDuration(seconds: number | undefined): string;"
+      },
+      {
+        "name": "isPaidVideo",
+        "kind": "function",
+        "jsdoc": "/** True when the video has an enabled SALE or RENT price. */",
+        "decl": "export function isPaidVideo(video: WixVideo): boolean;"
+      },
+      {
+        "name": "canWatchVideo",
+        "kind": "function",
+        "jsdoc": "/**\n * May the current viewer watch this video? FAILS CLOSED: missing pricing on the channel\n * or the video, or an entitlement that cannot be established, is \"no\".\n *\n * A channel with a required subscription or a pricing plan needs an active (or a\n * cancelled but unexpired) subscription. A paid video needs that subscription or its\n * own active sale or rent purchase. Query the channel with `CHANNEL_ACCESS_FIELDS` and\n * the video with `VIDEO_FIELDS`.\n */",
+        "decl": "export function canWatchVideo(channel: WixVideoChannel, video: WixVideo, now = Date.now()): boolean;"
+      },
+      {
+        "name": "latestVideos",
+        "kind": "function",
+        "jsdoc": "/**\n * Up to `limit` ready videos from the channels' preview pages (`listChannels` with\n * `videosPerChannel`, or `listLatestVideos`). Channels take turns — the first video of\n * each channel, then the second of each, … — so one large channel cannot fill the\n * whole rail. Duplicates (one video in two channels) appear once.\n */",
+        "decl": "export function latestVideos(channels: WixVideoChannel[], limit = 8): WixVideoInChannel[];"
+      },
+      {
+        "name": "WixVideoCard",
+        "kind": "interface",
+        "jsdoc": "/** The fields a video card binds to (`$item.*`). Shared by every carousel layout so the\n *  caption placement is a layout choice, never a data change. */",
+        "decl": "export interface WixVideoCard {\n  id: string;\n  channelId: string;\n  title: string;\n  /** \"4:05 · Channel\" — the parts that are known, joined. */\n  meta: string;\n  /** \"4:05\", or \"\". */\n  duration: string;\n  channelTitle: string;\n  coverUrl: string;\n  hasCover: boolean;\n  noCover: boolean;\n  /** True for a paid video (it may ask the viewer to buy or subscribe). */\n  isPaid: boolean;\n  notPaid: boolean;\n  /** One spoken label: title, length and channel. */\n  accessibilityLabel: string;\n}"
+      },
+      {
+        "name": "videoCard",
+        "kind": "function",
+        "jsdoc": "/** Shape one video for a card. `untitled` replaces an empty title. */",
+        "decl": "export function videoCard(entry: WixVideoInChannel, untitled = \"Video\", size: WixImageSize | null = WIX_LIST_IMAGE): WixVideoCard;"
+      },
+      {
+        "name": "WIX_VIDEO_GRAPHQL_URL",
+        "kind": "const",
+        "jsdoc": "/** The Wix Video GraphQL gateway (visitor and member reads). */",
+        "decl": "export const WIX_VIDEO_GRAPHQL_URL = \"https://manage.wix.com/_api/vod/public/graphql\";"
+      },
+      {
+        "name": "WixCallOptions",
+        "kind": "interface",
+        "jsdoc": "/** Per-call options. `site` reads a business other than the app's active one. */",
+        "decl": "export interface WixCallOptions {\n  site?: string;\n}"
+      },
+      {
+        "name": "WixVideoPricing",
+        "kind": "interface",
+        "jsdoc": "/** One price option of a channel (`SUBSCRIPTION` | `PRICING_PLAN`) or a video (`SALE` | `RENT`). */",
+        "decl": "export interface WixVideoPricing {\n  type?: string;\n  enabled?: boolean;\n  /** Channel only: true when every video needs the subscription or plan. */\n  required?: boolean;\n  price?: number;\n  currency?: string;\n  /** Rent period in hours (video) or subscription period (channel). */\n  period?: number;\n}"
+      },
+      {
+        "name": "WixVideoPurchase",
+        "kind": "interface",
+        "jsdoc": "/** The viewer's purchase of a channel subscription or of one video. */",
+        "decl": "export interface WixVideoPurchase {\n  /** `ACTIVE` | `PENDING` | `CANCELED` | `EXPIRED` | … */\n  status?: string;\n  expiresAt?: string;\n}"
+      },
+      {
+        "name": "WixVideoMedia",
+        "kind": "interface",
+        "jsdoc": "/** The uploaded or linked media of a video. */",
+        "decl": "export interface WixVideoMedia {\n  /** `READY` once the file can play; `IN_QUEUE` / `IN_PROGRESS` / … while it processes. */\n  status?: string;\n  /** Length in milliseconds. */\n  duration?: number;\n  thumbnailUrl?: string;\n  /** The embed URL of a linked (YouTube, Vimeo, …) video. */\n  externalUrl?: string;\n  externalId?: string;\n}"
+      },
+      {
+        "name": "WixVideoImage",
+        "kind": "interface",
+        "jsdoc": "/** A selectable image (cover or poster). `selected` is the image URL. */",
+        "decl": "export interface WixVideoImage {\n  selected?: string | null;\n}"
+      },
+      {
+        "name": "WixVideoPage",
+        "kind": "interface",
+        "jsdoc": "/** A page of a paginated list. */",
+        "decl": "export interface WixVideoPage<T> {\n  total?: number;\n  cursor?: string | null;\n  entities?: T[];\n}"
+      },
+      {
+        "name": "WixVideo",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixVideo {\n  id: string;\n  title?: string;\n  description?: string;\n  publisher?: string;\n  /** `COMPUTER` | `GOOGLE_DRIVE` | `DROPBOX` (hosted) | `YOUTUBE` | `VIMEO` | `FACEBOOK` | `LIVE`. */\n  source?: string;\n  /** `VISIBLE` for a published video. */\n  status?: string;\n  cover?: WixVideoImage | null;\n  poster?: WixVideoImage | null;\n  content?: WixVideoMedia | null;\n  pricing?: WixVideoPricing[];\n  /** The viewer's SALE purchase, when the query asks for it. */\n  purchase?: WixVideoPurchase | null;\n  /** The viewer's RENT purchase, when the query asks for it (GraphQL alias). */\n  rent_purchase?: WixVideoPurchase | null;\n}"
+      },
+      {
+        "name": "WixVideoChannel",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixVideoChannel {\n  id: string;\n  title?: string;\n  description?: string;\n  /** `INTERNAL` | `YOUTUBE`. */\n  source?: string;\n  featuredVideoId?: string | null;\n  hasPaidVideos?: boolean;\n  cover?: WixVideoImage | null;\n  pricing?: WixVideoPricing[];\n  /** The viewer's SUBSCRIPTION purchase, when the query asks for it. */\n  purchase?: WixVideoPurchase | null;\n  /** The channel's videos: only `total` in a list, a page when the query asks for one. */\n  videos?: WixVideoPage<WixVideo>;\n}"
+      },
+      {
+        "name": "WixVideoInChannel",
+        "kind": "interface",
+        "jsdoc": "/** A video together with the channel it belongs to. */",
+        "decl": "export interface WixVideoInChannel {\n  channel: WixVideoChannel;\n  video: WixVideo;\n}"
+      },
+      {
+        "name": "WixVideoErrorFlags",
+        "kind": "interface",
+        "jsdoc": "/** Flags every error this client throws carries, so a caller can branch without\n *  matching message text. */",
+        "decl": "export interface WixVideoErrorFlags {\n  /** The gateway refused the viewer (membership, purchase or permission). */\n  denied: boolean;\n  /** The gateway needs a signed-in member. */\n  signInRequired: boolean;\n  /** The requested channel does not exist or is not visible. */\n  notFound: boolean;\n}"
+      },
+      {
+        "name": "WixVideoError",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type WixVideoError = Error & WixVideoErrorFlags;"
+      },
+      {
+        "name": "wixVideoError",
+        "kind": "function",
+        "jsdoc": "/** Build an error carrying the `WixVideoErrorFlags` (each defaults to false). */",
+        "decl": "export function wixVideoError(message: string, flags: Partial<WixVideoErrorFlags> = {}): WixVideoError;"
+      },
+      {
+        "name": "isWixVideoWebRefusal",
+        "kind": "function",
+        "jsdoc": "/** True when a web bridge refused the gateway URL. Wix Video is then out of reach on\n *  this surface: the same read works in the native apps. */",
+        "decl": "export function isWixVideoWebRefusal(error: unknown): boolean;"
+      },
+      {
+        "name": "wixVideoQuery",
+        "kind": "function",
+        "jsdoc": "/**\n * Run one GraphQL read against the Wix Video gateway and return its `data`.\n *\n * The gateway answers HTTP 200 with an `errors` array for a refused or failed query.\n * That is thrown, never returned as empty data: a failed query must not look like a\n * site with no videos.\n *\n * @scope visitor\n */",
+        "decl": "export async function wixVideoQuery<T>(query: string, variables: Record<string, unknown> = {}, opts?: WixCallOptions): Promise<T>;",
+        "scope": "visitor"
+      },
+      {
+        "name": "wixVideoPages",
+        "kind": "function",
+        "jsdoc": "/** Read every page of a cursor-paginated list. Rows are de-duplicated by id. A\n *  repeated or malformed cursor throws instead of looping or returning a partial list. */",
+        "decl": "export async function wixVideoPages<T extends { id: string }>(\n  fetchPage: (cursor: string | null) => Promise<WixVideoPage<T> | null | undefined>,\n): Promise<T[]>;"
+      },
+      {
+        "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 }\";"
+      },
+      {
+        "name": "CHANNEL_ACCESS_FIELDS",
+        "kind": "const",
+        "jsdoc": "/** The channel fields an access decision needs (`canWatchVideo`). */",
+        "decl": "export const CHANNEL_ACCESS_FIELDS = \"id title pricing { type enabled required } purchase(filter: {type: SUBSCRIPTION}) { status expiresAt }\";"
+      },
+      {
+        "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 }\";"
+      },
+      {
+        "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 }\";"
+      },
+      {
+        "name": "ListChannelsOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface ListChannelsOptions extends WixCallOptions {\n  /** Also read the first N videos of each channel (owner's order). 0 (default) reads none. */\n  videosPerChannel?: number;\n}"
+      },
+      {
+        "name": "listChannels",
+        "kind": "function",
+        "jsdoc": "/**\n * Every channel of the site, in the owner's order (all pages).\n *\n * @scope visitor\n */",
+        "decl": "export async function listChannels(opts: ListChannelsOptions = {}): Promise<WixVideoChannel[]>;",
+        "scope": "visitor"
+      },
+      {
+        "name": "listChannelVideos",
+        "kind": "function",
+        "jsdoc": "/**\n * One channel and all its videos, in the owner's order. Throws a `notFound` error when\n * the channel does not exist.\n *\n * @scope visitor\n */",
+        "decl": "export async function listChannelVideos(channelId: string, opts?: WixCallOptions): Promise<{ channel: WixVideoChannel; videos: WixVideo[] }>;",
+        "scope": "visitor"
+      },
+      {
+        "name": "getVideo",
+        "kind": "function",
+        "jsdoc": "/**\n * One video with its channel's access fields. `null` when the channel does not exist;\n * `video: null` when the channel has no such video.\n *\n * @scope visitor\n */",
+        "decl": "export async function getVideo(channelId: string, videoId: string, opts?: WixCallOptions): Promise<{ channel: WixVideoChannel; video: WixVideo | null } | null>;",
+        "scope": "visitor"
+      },
+      {
+        "name": "getVideoStreamUrl",
+        "kind": "function",
+        "jsdoc": "/**\n * An authorized HLS stream URL for a hosted video (source `COMPUTER`, `GOOGLE_DRIVE`\n * or `DROPBOX`), or \"\" when the gateway gives none. Check `canWatchVideo` first: the\n * gateway authorizes the stream per viewer. A linked (YouTube, …) video has no stream\n * here; use `youtubeVideoId`.\n *\n * @scope visitor\n */",
+        "decl": "export async function getVideoStreamUrl(channelId: string, videoId: string, opts?: WixCallOptions): Promise<string>;",
+        "scope": "visitor"
+      },
+      {
+        "name": "ListLatestVideosOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface ListLatestVideosOptions extends WixCallOptions {\n  /** Most videos to return (default 8). */\n  limit?: number;\n  /** Channels to read (first page, default 10). */\n  channels?: number;\n  /** Videos to read from each channel (default 4). */\n  perChannel?: number;\n}"
+      },
+      {
+        "name": "listLatestVideos",
+        "kind": "function",
+        "jsdoc": "/**\n * The newest ready videos across the site's channels, for a rail or carousel: ONE\n * request that reads the first videos of the first channels. Channel order and each\n * channel's own video order are kept, and the channels take turns, so one large\n * channel cannot fill the whole rail.\n *\n * @scope visitor\n */",
+        "decl": "export async function listLatestVideos(opts: ListLatestVideosOptions = {}): Promise<WixVideoInChannel[]>;",
+        "scope": "visitor"
+      }
+    ]
+  },
   {
     "name": "@himalaya/wix-workflows",
     "source": "stdlib/wix-sdk/workflows-v1/src/index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1386.0",
+  "version": "0.1388.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": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "e3ab011108d918e98ce9eef090fd3e84e58228b81b990dce0393b625"
+  "falconPackageHash": "6ea552221f975dd6438104d636817ced2f4d49d9cbb69e0e8501fb91"
 }

package/templates/beauty-salon/README.md

@@ -9,12 +9,17 @@ identity and navigation in `config.ts`, look and feel in `tokens.json`.
 
 ## Point at your Wix site
 
-Your **Wix Headless `clientId` IS the site binding** — there is no separate site id to
-pass, because the visitor token minted from it already names your site. Set these before
-`himi build` / preview so calls hit YOUR site (the placeholders are not a real backend):
+Your **Wix Headless `clientId` binds the data** — the visitor token minted from it already
+names your site, so reads need nothing else. Set these before `himi build` / preview so calls
+hit YOUR site (the placeholders are not a real backend):
 
     export WIX_CLIENT_ID="<headless-oauth-client-id>"
     export WIX_SITE_URL="https://your-site.wixsite.com/…"
+    export WIX_SITE_ID="<metasite-id>"
+
+`WIX_SITE_ID` is the site that client belongs to. The member login takes it from the environment
+while `WIX_CLIENT_ID` is the client the config uses. A native build needs it for member sign-up on
+a CAPTCHA-protected site, push registration and in-app purchases.
 
 Full details, including how to ship a binary a customer can install against their own
 site: `himi docs branded-lite-site-binding`.

package/templates/beauty-salon/tier5-src/_shared/collection-contract.ts

@@ -98,7 +98,7 @@ export const COLLECTIONS: Record<string, CollectionConfig> = {
   himiBrandedBadges: { rows: 'badges', title: 'name', subtitle: 'description', view: 'grid' },
   himiBrandedDonations: { rows: 'campaigns', title: 'name', subtitle: 'description', view: 'grid', primaryVerb: { label: 'Donate' } },
   himiBrandedGiftCards: { rows: 'cards', title: 'name', subtitle: 'description', view: 'grid' },
-  himiBrandedVideos: { rows: 'channels', title: 'title', subtitle: 'description', view: 'grid' },
+  himiBrandedVideos: { rows: 'channels', title: 'title', subtitle: 'subtitle', image: 'coverUrl', view: 'grid', searchPlaceholder: 'Search channels', countNoun: ['channel', 'channels'] },
   himiBrandedPodcasts: { rows: 'episodes', title: 'title', subtitle: 'subtitle', image: 'image', metadata: ['progressLabel'], view: 'list' },
   himiBrandedForms: { rows: 'forms', title: 'name', subtitle: 'description', view: 'list' },
   himiBrandedGalleries: { rows: 'galleries', title: 'name', subtitle: 'description', image: 'image', view: 'grid' },

package/templates/beauty-salon/tier5-src/_shared/video-caption.ts

@@ -0,0 +1,21 @@
+// The video carousel's two looks: the caption ON the cover (a brand label chip over the
+// image) or UNDER it. Every slide carries both placements; the descriptor's
+// `videoCaption` appear param picks one, and these flags hide the other
+// (`hiddenWhen` hides on TRUE). So a screen switches look by changing ONE param,
+// with no second carousel and no change to the slide tree.
+export type VideoCaption = "overlay" | "below";
+
+/** The placement a param asks for. Anything but "below" is the default, "overlay". */
+export function videoCaptionOf(value: unknown): VideoCaption {
+  return value === "below" ? "below" : "overlay";
+}
+
+export interface CaptionFlags {
+  captionOnImage: boolean;
+  captionBelow: boolean;
+}
+
+/** Stamp each card with the gates its slide reads (`$item.captionOnImage` / `$item.captionBelow`). */
+export function withCaption<T extends object>(cards: T[], caption: VideoCaption): (T & CaptionFlags)[] {
+  return cards.map((card) => ({ ...card, captionOnImage: caption === "overlay", captionBelow: caption === "below" }));
+}