@wix/himalaya-cli 0.1309.0 → 0.1311.0

package/guides/himi-json-output.md

@@ -6,7 +6,7 @@ repurposed when human wording changes. New codes may be added; consumers must
 handle an unknown code as a failure, without parsing prose.
 
 **Rollout:** this contract is enforced for **`himi push`**, including `--only`,
-first. Other subcommands still have legacy failures without codes and are a
+first, and for **`himi store iap connect`**. Other subcommands still have legacy failures without codes and are a
 follow-up migration. This is an additive change: existing `error`, `errors`,
 `message`, `hint`, status, body, and gate-specific fields stay as they were.
 Some legacy envelopes have no singular `error` or `hint`; consumers must not
@@ -78,6 +78,34 @@ The `ux_evidence_*` codes map to the existing typed `uxEvidence.state`; a succes
 `recorded` state has no refusal code. Successful pushes and warnings do not gain
 failure codes. A forced push still follows the existing override rules.
 
+## `himi store iap connect` codes
+
+`connect` prints one envelope with the whole report. When the setup is not complete it is
+`ok: false` with the first step's code; each step also carries its own `code`.
+
+| Code | Meaning |
+|---|---|
+| `bundle_registered_elsewhere` | The bundle id is registered to another purchases app (another site's). Nothing was changed; only that registration's owner can remove it. |
+| `apple_key_missing` | No In-App Purchase key was given and the app has none stored. |
+| `invalid_usage` | The flags are incomplete or malformed (for example `--iap-key` without `--iap-key-id`). Nothing was read or written. |
+| `iap_key_unreadable` | `--iap-key` is missing, unreadable, inside the repository, or not a PEM private key. Nothing was written. |
+| `provider_route_unavailable` | The Serve target has no IAP routes, so the appleIAP provider was not connected. |
+| `manifest_invalid` | `--manifest` is not a valid IAP manifest; `problems` lists why. Nothing was read or written. |
+| `credentials_unavailable` | The `--profile` App Store Connect credentials could not be resolved. Nothing was read or written. |
+| `provider_not_connected` | wix-iap answered, but reported the provider account as not connected. |
+| `mapping_conflict` | The Wix item is already mapped to a different Apple product; left as it is. |
+| `mapping_inactive` | The mapping exists but is inactive; left as it is. |
+| `mapping_type_mismatch` | The mapping exists as a product type the purchase flow cannot sell (programs sell only as `NON_CONSUMABLE`); left as it is. |
+| `sku_in_use` | The Apple product is already mapped to another Wix item; left as it is. |
+| `mapping_unsupported` | The purchase flow cannot map this item yet (a vertical other than Online Programs, a price tier, or a program declared as a consumable). |
+| `no_purchases_app` | A step did not run because the site has no purchases app for the bundle. |
+| `request_failed` | A purchases-service call failed for another reason; the original message is preserved. |
+| `setup_incomplete` | Steps are only planned (a dry run) or otherwise not yet in place. |
+| `confirmation_required` | Writes were planned, but there was no terminal to ask and no `--yes`. Nothing was written. |
+| `config_conflict` | The backend setup is complete, but the app's config names a different purchases app, site or bundle. |
+| `config_not_applied` | `--content` was given, but the binding is not in its `config.ts` (no config file, a dynamic or symlinked config, an edit `himi validate` rolled back, or no validator); the `config` report or `note` says what to add by hand. |
+| `connect_failed` | An otherwise unclassified error stopped connect (for example an unreadable manifest, or a failed `--out` write). The original message is preserved. |
+
 ## Follow-ups
 
 - Migrate failure envelopes in subcommands other than `push`, keeping this contract.

package/guides/iap-products.md

@@ -149,6 +149,8 @@ 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 connect --manifest ./iap-products.json --profile fit-club-owner \
+  --iap-key ~/keys/SubscriptionKey_ABCD123456.p8 --iap-key-id ABCD123456 --content . --dry-run
 ```
 
 **`plan` is read-only.** It:
@@ -222,6 +224,53 @@ schedule, even without the local journal. Nothing is ever deleted or rolled back
 **`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.
 
+## Connecting the Wix site: `connect`
+
+`connect` makes the manifest's Wix site ready to sell those products, from the same manifest,
+as the site owner (your Wix login, like `draft`). To run it against a Serve deploy preview, pass
+`--preview-tag dp-<tag>` (or set `HIMI_SERVE_PREVIEW_TAG`). Only the Serve calls (the appleIAP
+provider connection) are routed to the preview; the purchases service and App Store Connect are
+called as usual. In order:
+
+1. **The purchases app.** It reads the site's apps and reuses the one for the manifest's bundle
+   id. Only when the site has none does it register one. A bundle id belongs to one purchases
+   app platform-wide: if another app holds it (another site's, or another account's), that is a
+   `bundle_registered_elsewhere` conflict. Only that registration's owner can remove it; `connect`
+   never does.
+2. **The In-App Purchase key.** It stores `--iap-key` / `--iap-key-id` once, server-side. This is
+   an App Store Connect **In-App Purchase** key (Users and Access → Integrations → In-App
+   Purchase), not the App Store Connect API key `--profile` names; the service rejects that kind.
+   The issuer comes from the profile. Skipped when a key is already stored.
+3. **The appleIAP payment provider** on the site, through Serve's IAP route to wix-iap
+   (`ConnectProviderAccount`). Reported as `provider_route_unavailable` only when the Serve target
+   has no IAP routes; a refusal from the service behind it is `request_failed`. There is no read
+   of the provider's state, so a rerun connects it again (the call is safe to repeat).
+4. **One mapping per Wix item → Apple product.** Online Programs map by program id (the id the
+   purchase flow looks up), and only as non-consumables. Other verticals, price tiers and
+   consumable programs are skipped with `mapping_unsupported`. An item already mapped to another
+   product (`mapping_conflict`), a mapping of another product type (`mapping_type_mismatch`), an
+   inactive mapping (`mapping_inactive`), or an Apple product mapped to another item
+   (`sku_in_use`) is reported and left exactly as it is.
+5. **The app's config.** With `--content <dir>`, it records `wixIap: { purchasesAppId }` (and the
+   `iap` capability) in the package's `config.ts`, keeping everything else byte for byte. The edit
+   is backed up under `.himi/store-iap-backup/`, checked with `himi validate`, and rolled back if it
+   introduces an error. A different purchases app already there, a member login on another
+   site, or another app's bundle is a conflict and the file is not touched. The bundle that must match
+   the manifest is the package's `store/store.config.yaml` `ios.bundleId` when it sets one;
+   otherwise `bundleId` itself or, for a dev bundle, the same without `.dev`. Whenever `--content` was given and the binding
+   did not land, the run is `ok: false` (`config_not_applied`) with what to add by hand.
+
+**Review first.** `--dry-run` reads everything and writes nothing. Without `--dry-run` it prints
+the plan and asks; a shell with no terminal (or `--json`) needs `--yes`. A rerun reuses every
+record and writes nothing new. Adding products later means adding them to the manifest and
+rerunning: only their mappings are added, and the purchases-app id (the one thing a build bakes)
+does not change, so no new build is needed.
+
+**What it does not do.** It never removes, replaces or reactivates a record. The app reads the
+mappings it writes through Serve's member and visitor route (`POST /himalaya-serve/v1/iap/mappings`;
+see [the backend integration](iap-backend-integration.md)); a build still needs the binding baked
+for its screens to use them.
+
 ## Local state
 
 Local state lives in `~/.himalaya/store-iap/<appleAppId>/`:
@@ -261,7 +310,7 @@ future importer must authenticate ownership and re-read Apple before activating
 
 | Code | Meaning |
 |---|---|
-| `0` | everything requested is in place (`apply`, `status`), or the plan has no conflicts (`plan`) |
+| `0` | everything requested is in place (`apply`, `status`, `connect`), or the plan has no conflicts (`plan`) |
 | `1` | partial, conflict, drift, or a declined prompt |
 | `2` | usage, manifest, credential, target or access error; nothing was written |
 
@@ -284,4 +333,4 @@ Not in this version:
 - review screenshot upload and submission
 - changing a live price
 - Google Play
-- backend import and checkout activation
+- the build-time binding bake and the screens' checkout (the companion PR)

package/guides/qa-builds.md

@@ -348,7 +348,7 @@ one never blocks a rollout — the dist routes just `501` with the reason.
 | `HIMI_DIST_CALLBACK_BASE` | defaults to this artifact's bo origin, so usually unset |
 | `HIMI_DIST_CONTRACT_URL_TEMPLATE` | where the pool fetches an app's brand contract; unset ⇒ the shell's committed provisioning |
 | `HIMI_DIST_NOTIFY_TAGS` | Job Service notify-on-done, independent of our callback (covers a job that dies before reporting) |
-| `HIMI_DIST_MAX_IN_FLIGHT` | simultaneous builds per APP (default 3) |
+| `HIMI_DIST_MAX_IN_FLIGHT` | simultaneous platform jobs per APP (default 3; the live config field has ceiling 40). An explicit override outranks `HimiDistCapacity.perAppInFlight`; changing or clearing it applies on the next deploy. |
 | `HIMI_DIST_MAX_IN_FLIGHT_PER_IDENTITY` | simultaneous builds per CREDENTIAL, across every app it can reach (default 6 for an issued token, **18 for a shared one** — see below). The per-app cap is not a bound on a caller: apps are free to claim, so N slugs buy N×3 concurrent jobs on the pool `native-ci` shares. This is the one that bounds a person — or an agent of ours in a retry loop, which floods the pool exactly as well as a stranger would. Setting it applies to shared and issued credentials alike, and — unlike the per-tier form below — it OUTRANKS a `HimiDistCapacity` value, so leaving one set here shadows the lever for that bound until the next deploy clears it. The 429 names the jobs holding the slots, because `himi dist cancel` takes a job id and the listing route is per-app. |
 | `HIMI_DIST_MAX_PER_IDENTITY_PER_DAY` | builds one credential may START in a rolling 24h (default 20 issued / 100 shared — see below). Concurrency alone does not bound spend — three at a time, restarted the instant each finishes, is unbounded Mac-pool time at a concurrency no in-flight cap objects to. Rolling, not calendar: the refusal carries a `resetAt` saying when the oldest build ages out. |
 | `HIMI_DIST_CAPACITY` | set to `0` to stop reading the bounds from the `HimiDistCapacity` dynamic config and fall back to the three `HIMI_DIST_MAX_*` numbers and then the compiled defaults. Inverted from a dark switch, same as `HIMI_DIST_SELFSERVE`: the config's `Default` target group holds exactly the numbers the code already enforced, so this ships **on** as a no-op and config exists to withdraw it in an incident. Only the literal `0` closes it. |
@@ -395,15 +395,17 @@ and into their own, where the tighter number is the one that applies.
 
 ### Retuning the caps without a deploy
 
-The six tiered numbers are **defaults**. What applies is resolved once per dispatch, **per bound** —
-each of the six walks the ladder on its own:
+The per-app number and six tiered numbers are **defaults**. What applies is resolved once per
+dispatch, **per bound** — each walks the ladder on its own:
 
     HIMI_DIST_MAX_* (global, if set)  →  the HimiDistCapacity field for that bound  →  the compiled default
 
 `HimiDistCapacity` is a [Wix Dynamic Config](https://wix-bo.com/dev/dynamic-config) owned by
-`himalaya`, with six `INT` fields — `selfServeInFlight`, `selfServePerDay`, `employeeInFlight`,
+`himalaya`, with seven `INT` fields — `perAppInFlight`, `selfServeInFlight`, `selfServePerDay`, `employeeInFlight`,
 `employeePerDay`, `sharedInFlight`, `sharedPerDay` — and one filterless `Default` target group
-holding the numbers in the table above. Editing a field retunes that tier and nothing else; the
+holding the existing limits. `perAppInFlight` defaults to **3** and applies independently to every
+app; the other fields apply to their credential tier across apps. iOS and Android each count as
+one job, so a paired request needs two free slots. Editing a tier field retunes only that tier; the
 write takes about **90 seconds** to reach runtime. The effective number appears in the 429 body, so
 a caller can quote what actually applied. `HIMI_DIST_CAPACITY=0` removes the layer.
 
@@ -413,9 +415,9 @@ failure modes are not symmetric: if the field won, deploying this where someone
 refusing builds that worked yesterday — active harm, from a change that is otherwise a no-op.
 Losing to a set override costs only a lever that does not move. So if a field edit appears to do
 nothing, check whether that key is set — and note that clearing it is not the fast path back: those
-two keys are read once, when a pod builds its handlers, so a cleared key applies on the next deploy
+three keys are read once, when a pod builds its handlers, so a cleared key applies on the next deploy
 rather than in 90 seconds. That staleness is what made these numbers un-editable in practice, and
-the right state for both keys is now unset.
+the right state for all three keys is now unset.
 
 **A bad answer can never widen a bound.** The read conducts the scope `himi-dist-capacity` with the
 artifact's own identity (`CONDUCTOR.READ`), and every way it can fail — no conduction clients on the
@@ -443,11 +445,13 @@ budget, so a call that never settles gives its slot back anyway and a hung condu
 retire the lever for the life of the pod. At capacity the conduction is skipped, the layers below
 answer, and that is logged once too.
 
-**The per-app cap is not on this lever, and for a single-app caller it is the ceiling that binds.**
-`HIMI_DIST_MAX_IN_FLIGHT` (3) stays a databag-only number, so raising a tier's concurrency past 3
-buys a self-serve owner nothing on its own — they may only build their own app, and the refusal just
-changes from `dist_identity_too_many_in_flight` to `dist_too_many_in_flight`. For a caller with one
-app the **rolling day** is the bound that refuses a legitimate iterate-install-test loop.
+**Both concurrency limits apply.** Raising a credential tier above `perAppInFlight` does not raise
+the app's own cap. Change `perAppInFlight` to retune that cap through the same config. A per-app
+refusal uses `dist_too_many_in_flight`; a credential refusal uses
+`dist_identity_too_many_in_flight`. Both report the effective cap. Missing or invalid
+`perAppInFlight`, or a config read failure, keeps the service override or default of 3.
+Add the field with value 3 before deployment; older serve versions ignore it, and newer ones
+keep the default when talking to an older config.
 
 ### Why the job's parameters ride in `command`, not `envVars`
 

package/guides/sdk-reference.json

@@ -1638,13 +1638,13 @@
         "name": "PurchaseContext",
         "kind": "interface",
         "jsdoc": "/** A catalog item resolved by the backend for the captured member. */",
-        "decl": "export interface PurchaseContext {\n  productId: string;\n  /** Canonical UUID the backend associates with this site/member. */\n  appAccountToken: string;\n  /** Opaque site/member scope the acknowledgement must echo. */\n  scopeKey: string;\n}"
+        "decl": "export interface PurchaseContext {\n  productId: string;\n  /** Canonical UUID for this one sale (D61: a per-payment purchase intent, not the member). */\n  appAccountToken: string;\n  /** Opaque site/member scope the acknowledgement must echo. */\n  scopeKey: string;\n}"
       },
       {
         "name": "MemberContext",
         "kind": "interface",
-        "jsdoc": "/** The current member's association, used to recover purchases without a catalog item. */",
-        "decl": "export interface MemberContext {\n  appAccountToken: string;\n  scopeKey: string;\n}"
+        "jsdoc": "/** The current member's scope, used to recover purchases without a catalog item. It names no\n *  token: each payment has its own, and the backend decides whose a transaction is. */",
+        "decl": "export interface MemberContext {\n  scopeKey: string;\n}"
       },
       {
         "name": "ContextResult",
@@ -1722,7 +1722,7 @@
         "name": "PurchaseCoordinatorDependencies",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface PurchaseCoordinatorDependencies {\n  store: TransactionStore;\n  backend: DeliveryBackend;\n  session: SessionProvider;\n  clock: Clock;\n  /** Extra milliseconds added to a backoff step; inject for deterministic tests. */\n  jitter?: (baseDelayMs: number) => number;\n  /** Receives a fresh safe snapshot after every change. */\n  onState?: (state: DeliveryState) => void;\n}"
+        "decl": "export interface PurchaseCoordinatorDependencies {\n  store: TransactionStore;\n  backend: DeliveryBackend;\n  session: SessionProvider;\n  clock: Clock;\n  /** Extra milliseconds added to a backoff step; inject for deterministic tests. */\n  jitter?: (baseDelayMs: number) => number;\n  /** Receives a fresh safe snapshot after every change. */\n  onState?: (state: DeliveryState) => void;\n  /** Called inside the purchase job when StoreKit defers for Ask to Buy, after the unfinished\n   *  queue has been listed and before the job returns. The next queued purchase has not started. */\n  onAwaitingApproval?: (productId: string) => void;\n}"
       },
       {
         "name": "PurchaseCoordinator",
@@ -1932,7 +1932,7 @@
         "name": "AppBindingSource",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface AppBindingSource {\n  /** Null when the app was never registered. */\n  current(): Promise<PurchasesAppBinding | null>;\n}"
+        "decl": "export interface AppBindingSource {\n  /** Null when the app was never registered; rejects when the host could not say. */\n  current(): Promise<PurchasesAppBinding | null>;\n}"
       },
       {
         "name": "IapAppHost",
@@ -1946,11 +1946,35 @@
         "jsdoc": "/** Where the Payments service is reachable through the Wix gateway. */",
         "decl": "export interface WixIapRoute {\n  /** The gateway path that maps to the service's `/v1`, without a trailing slash. No public route\n   *  was in the generated gateway metadata on 2026-10-08, so there is deliberately no default. */\n  prefix: string;\n}"
       },
+      {
+        "name": "HIMALAYA_SERVE_IAP_ROUTE",
+        "kind": "const",
+        "jsdoc": "/**\n * Serve's Apple-IAP routes on the public gateway (`www.wixapis.com/himalaya-serve/v1/iap`), where the\n * native bridge sends the member's or visitor's own token. One prefix for the wix-iap payment calls, the\n * cashier charge and the mapping read; Serve forwards each to the internal service that owns it.\n */",
+        "decl": "export const HIMALAYA_SERVE_IAP_ROUTE: WixIapRoute = { prefix: \"/himalaya-serve/v1/iap\" };"
+      },
+      {
+        "name": "AppleSaleRule",
+        "kind": "interface",
+        "jsdoc": "/** How the App Store sells one vertical's Wix item: the purchases catalog's `appProductId` for it, and\n *  the only product type the purchase flow sells it as. */",
+        "decl": "export interface AppleSaleRule {\n  appProductId(entityId: string): string;\n  productType: \"NON_CONSUMABLE\";\n}"
+      },
+      {
+        "name": "APPLE_SALE_RULES",
+        "kind": "const",
+        "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 * Other verticals' order item ids are not established yet, so their items keep their own commerce.\n */",
+        "decl": "export const APPLE_SALE_RULES: Readonly<Record<string, AppleSaleRule>> = {\n  onlineProgram: { appProductId: (id) => id, productType: \"NON_CONSUMABLE\" },\n};"
+      },
+      {
+        "name": "HostCallExpectation",
+        "kind": "interface",
+        "jsdoc": "/** Captured when a protected call starts. The native bridge checks it and never puts it on\n *  the HTTP request. */",
+        "decl": "export interface HostCallExpectation {\n  generation: number;\n  kind: \"member\";\n  memberId: string;\n  siteId: string;\n  appId: string;\n}"
+      },
       {
         "name": "WixTransport",
         "kind": "interface",
-        "jsdoc": "/** The host's Wix REST bridge (`himalaya.wixApi`). Resolves the parsed body of a 2xx and\n *  rejects with `HTTP <status> [<code>]: <message>` otherwise. Credentials are attached\n *  natively, never in TypeScript. */",
-        "decl": "export interface WixTransport {\n  call(method: \"GET\" | \"POST\", path: string, body?: unknown, headers?: Record<string, string>): Promise<unknown>;\n}"
+        "jsdoc": "/** The host's Wix REST bridge (`himalaya.wixApi`). Resolves the parsed body of a 2xx and\n *  rejects with `HTTP <status> [<code>]: <message>` otherwise. Credentials are attached\n *  natively, never in TypeScript. `expectation` is bridge metadata, not a header. */",
+        "decl": "export interface WixTransport {\n  call(\n    method: \"GET\" | \"POST\",\n    path: string,\n    body?: unknown,\n    headers?: Record<string, string>,\n    expectation?: HostCallExpectation,\n  ): Promise<unknown>;\n}"
       },
       {
         "name": "MemberIdentitySource",
@@ -1974,7 +1998,7 @@
         "name": "WixIapOperation",
         "kind": "type",
         "jsdoc": "",
-        "decl": "export type WixIapOperation = \"startPayment\" | \"completePayment\" | \"getCustomerId\" | \"getPayment\";"
+        "decl": "export type WixIapOperation = \"startPayment\" | \"completePayment\" | \"getPayment\";"
       },
       {
         "name": "StartPaymentErrorCode",
@@ -1986,13 +2010,7 @@
         "name": "CompletePaymentErrorCode",
         "kind": "type",
         "jsdoc": "",
-        "decl": "export type CompletePaymentErrorCode = \"INVALID_PURCHASE\" | \"OWNED_BY_ANOTHER_CUSTOMER\" | \"PURCHASE_REVOKED\"\n  | \"NOT_PURCHASED\" | \"ZERO_PRICE\" | \"NO_MATCHING_PAYMENT\" | \"APP_NOT_CONFIGURED\";"
-      },
-      {
-        "name": "GetCustomerIdErrorCode",
-        "kind": "type",
-        "jsdoc": "",
-        "decl": "export type GetCustomerIdErrorCode = \"APP_NOT_CONFIGURED\";"
+        "decl": "export type CompletePaymentErrorCode = \"INVALID_PURCHASE\" | \"OWNED_BY_ANOTHER_CUSTOMER\" | \"PURCHASE_REVOKED\"\n  | \"NOT_PURCHASED\" | \"ZERO_PRICE\" | \"NO_MATCHING_PAYMENT\" | \"PAYMENT_NOT_PENDING\" | \"APP_NOT_CONFIGURED\";"
       },
       {
         "name": "GetPaymentErrorCode",
@@ -2015,21 +2033,15 @@
       {
         "name": "StartPaymentResult",
         "kind": "type",
-        "jsdoc": "/** `customerId` goes to StoreKit as `appAccountToken` (the customer id is the token, D59). Keep it\n *  out of screen state. */",
-        "decl": "export type StartPaymentResult =\n  | { status: \"started\"; payment: WixIapPayment; storeProductId: string; customerId: string }\n  | WixIapFailure<StartPaymentErrorCode>;"
+        "jsdoc": "/** `appAccountToken` goes to StoreKit with the purchase. It is minted for this one payment (a\n *  purchase intent, D61), not the member: StartPayment for the same Wix transaction again returns\n *  the same payment and the same token. Keep it out of screen state. */",
+        "decl": "export type StartPaymentResult =\n  | { status: \"started\"; payment: WixIapPayment; storeProductId: string; appAccountToken: string }\n  | WixIapFailure<StartPaymentErrorCode>;"
       },
       {
         "name": "CompletePaymentResult",
         "kind": "type",
-        "jsdoc": "/** `matched`: the server verified the proof and matched it to `payment`, which may not be the one\n *  this device started. Its status may still be `approving`. */",
+        "jsdoc": "/** `matched`: the server verified the proof and paid the payment whose token the Apple transaction\n *  carries. Its status may still be `approving`. */",
         "decl": "export type CompletePaymentResult = { status: \"matched\"; payment: WixIapPayment } | WixIapFailure<CompletePaymentErrorCode>;"
       },
-      {
-        "name": "CustomerIdResult",
-        "kind": "type",
-        "jsdoc": "",
-        "decl": "export type CustomerIdResult = { status: \"found\"; customerId: string } | WixIapFailure<GetCustomerIdErrorCode>;"
-      },
       {
         "name": "GetPaymentResult",
         "kind": "type",
@@ -2047,16 +2059,58 @@
         "name": "WixIapClient",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface WixIapClient {\n  /** StartPayment for a pending `appleIAP` Wix Payments transaction the member placed. Returns the\n   *  store product to sell and the customer id to pass to StoreKit as `appAccountToken`. */\n  startPayment(input: { wixTransactionId: string }): Promise<StartPaymentResult>;\n  /** CompletePayment with held Apple proof, sent unchanged. Success can still be `approving`. */\n  completePayment(transaction: AppleTransaction): Promise<CompletePaymentResult>;\n  /** GetCustomerId: the member's customer id, for recovering held purchases. Creates the customer\n   *  when there is none. */\n  getCustomerId(): Promise<CustomerIdResult>;\n  /** GetPayment: one of the member's own Payments. */\n  getPayment(input: { paymentId: string }): Promise<GetPaymentResult>;\n}",
+        "decl": "export interface WixIapClient {\n  /** StartPayment for a pending `appleIAP` Wix Payments transaction the member placed. Returns the\n   *  store product to sell and this payment's `appAccountToken` to pass to StoreKit. */\n  startPayment(input: { wixTransactionId: string }): Promise<StartPaymentResult>;\n  /** CompletePayment with held Apple proof, sent unchanged: the service pays the payment whose\n   *  token the transaction carries. Success can still be `approving`. */\n  completePayment(transaction: AppleTransaction): Promise<CompletePaymentResult>;\n  /** GetPayment: one of the member's own Payments. */\n  getPayment(input: { paymentId: string }): Promise<GetPaymentResult>;\n}",
         "verified": false
       },
       {
         "name": "createWixIapClient",
         "kind": "function",
-        "jsdoc": "/**\n * Creates a client for Wix's in-app-purchase payments service (`mobile-apps-wix-iap`), which pays\n * a Wix order with a store purchase the member makes in the app.\n *\n * NOT ENABLED and not production-ready. No app wires it, and no call reaches the service: it has\n * no public gateway route yet, so `route` must be supplied and there is no default. It calls\n * StartPayment (`POST …/payments/start`), CompletePayment (`POST …/payments/complete`),\n * GetCustomerId (`GET …/customer-id`) and GetPayment (`GET …/payments/{id}`) through the\n * `wix_api` bridge. A matched or approved Payment is not durable access and never finishes the\n * store transaction.\n *\n * Production use is blocked on pending prerequisites: a public route and member authorization on\n * the service, the service's own app identity and permissions, a trusted provisioning flow for the\n * app binding, and a native bridge that binds each request to the session generation across\n * authorization, send and retry. Its checks here protect only this client's own flow.\n */",
+        "jsdoc": "/**\n * Creates a client for Wix's in-app-purchase payments service (`mobile-apps-wix-iap`), which pays\n * a Wix order with a store purchase the member makes in the app.\n *\n * NOT ENABLED and not production-ready. No app wires it, and no call reaches the service: it has\n * no public gateway route yet, so `route` must be supplied and there is no default. It calls\n * StartPayment (`POST …/payments/start`), CompletePayment (`POST …/payments/complete`)\n * and GetPayment (`GET …/payments/{id}`) through the\n * `wix_api` bridge. A matched or approved Payment is not durable access and never finishes the\n * store transaction.\n *\n * Production use stays blocked: there is no public route or member authorization on the service,\n * no trusted app-binding source, and checkout stays disabled. When this client uses the host\n * bridge, it also requires the host's identity clock and passes that captured expectation\n * through the bridge. An injected transport keeps the previous call shape unless the session\n * itself exposes an identity.\n */",
         "decl": "export function createWixIapClient(deps: WixIapClientDependencies): WixIapClient;",
         "verified": false
       },
+      {
+        "name": "HostSessionView",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface HostSessionView extends SessionSnapshot {\n  memberId: string | null;\n  siteId: string | null;\n  appId: string | null;\n  ready: boolean;\n  epoch: number;\n}"
+      },
+      {
+        "name": "HostIdentitySource",
+        "kind": "interface",
+        "jsdoc": "/** A session provider that can also name the principal captured for one generation. */",
+        "decl": "export interface HostIdentitySource {\n  readonly identityBound: boolean;\n  identity(session: SessionSnapshot): HostCallExpectation | null;\n}"
+      },
+      {
+        "name": "HostSessionProvider",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface HostSessionProvider extends SessionProvider, HostIdentitySource {}"
+      },
+      {
+        "name": "createHostSession",
+        "kind": "function",
+        "jsdoc": "/** Wraps a host session clock as the session provider the delivery coordinator and the wix-iap\n *  client share. Ignores a generation older than the last one read, and keeps the first member\n *  expectation captured for each generation for `identity()`. */",
+        "decl": "export function createHostSession(source: {\n  identityBound: boolean;\n  current(): unknown;\n  subscribe(listener: () => void): () => void;\n}): HostSessionProvider;"
+      },
+      {
+        "name": "hostSessionFromGlobal",
+        "kind": "function",
+        "jsdoc": "/** The session on `globalThis.himalaya`. Web publishes `identityBound: false`. */",
+        "decl": "export function hostSessionFromGlobal(): HostSessionProvider;"
+      },
+      {
+        "name": "memberIdentityOf",
+        "kind": "function",
+        "jsdoc": "/** The member a host session names for a captured generation, as the identity port the Apple-IAP\n *  checkout and the wix-iap client take: null when that generation has no signed-in member. */",
+        "decl": "export function memberIdentityOf(source: HostIdentitySource): MemberIdentitySource;"
+      },
+      {
+        "name": "readIdentityBound",
+        "kind": "function",
+        "jsdoc": "/** Whether the host fences protected calls to the captured member (`identityBound`). Web does not. */",
+        "decl": "export function readIdentityBound(): boolean;"
+      },
       {
         "name": "ProductType",
         "kind": "type",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1309.0",
+  "version": "0.1311.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": "02386de50054fcafd66cc4c3c44d8c8a4e9cf5de47401215465be767"
+  "falconPackageHash": "105e0572efcdcccbc0bea292e6e88354813e2abb6f818908beff3f79"
 }