@wix/himalaya-cli 0.1310.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/sdk-reference.json

@@ -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,6 +1946,24 @@
         "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",

package/package.json

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