@wix/himalaya-cli 0.1154.0 → 0.1156.0

package/guides/getting-started.md

@@ -324,8 +324,9 @@ Keys are transmitted to the authenticated backend for Branded/Ping custody, not
 project settings or output. Enter Later to defer and continue building.
 
 `notify status` is read-only and needs no key files; `--refresh` checks providers live.
-Backend readiness does not prove notification delivery. This setup does not rewrite native
-configuration, select a Ping family, build a binary, register a device or send a notification.
+Backend readiness does not prove notification delivery. A successful setup turns push on in
+`config.ts` (the Ping family included; notification routes are derived at every build); it does
+not build a binary, register a device or send a notification.
 Continue building and publishing app content. For a customer push test, use the
 `himi dist --signing byo` flow below with existing signing assets and matching native configuration.
 The default Wix-managed binary does not match the customer's Apple identity. After an uncertain

package/guides/himi-skill.md

@@ -353,8 +353,9 @@ Keys are transmitted to the authenticated backend for Branded/Ping custody, not
 project settings or output. Enter Later to defer and continue building.
 
 `notify status` is read-only and needs no key files; `--refresh` checks providers live.
-Backend readiness does not prove notification delivery. This setup does not rewrite native
-configuration, select a Ping family, build a binary, register a device or send a notification.
+Backend readiness does not prove notification delivery. A successful setup turns push on in
+`config.ts` (the Ping family included; notification routes are derived at every build); it does
+not build a binary, register a device or send a notification.
 Continue building and publishing app content. For a customer push test, use the
 `himi dist --signing byo` flow below with existing signing assets and matching native configuration.
 The default Wix-managed binary does not match the customer's Apple identity. After an uncertain

package/guides/himi-test.md

@@ -116,6 +116,7 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `non-finite-number` | error | `NaN` / `Infinity` in worker state — the wrong-total / missing-operand reducer bug. Read live, before the JSON trip to the host flattens it to `null`. On device it renders as an **empty** label, not the text "NaN". |
 | `placeholder-in-text` | error | `undefined`, `null`, `NaN`, `[object Object]` or a JSON blob rendered as visible text. |
 | `unsubstituted-binding` | error | A raw `$service:` / `$item` token, or an unresolved `$t:` i18n key, reaching visible text. |
+| `item-field-missing` | error | A list row template binds `$item.<field>`, but none of the list's real rows carries `<field>`: the web preview paints `item.<field>` as text and native paints nothing (a worker emitting `jobType` while the template reads `$item.type`). Judged only against real rows, and on the first segment. `warning` when the prop declares `collapseWhenEmpty`. |
 | `unresolved-wix-media` | error | A media-typed prop holding a raw Wix media handle/id the renderer cannot load. |
 | `binding-unresolved` | error / warning | A `$service:` binding aimed at state the worker never defines. It is an error when the missing value can leave visible UI blank. A direct prop with sibling `collapseWhenEmpty: true` is an advisory warning instead: the renderer deliberately removes that zero-size optional chrome, while the warning keeps the omitted contract auditable. |
 | `nav-param-dropped` | error | A bound `himi.open` param that resolves to nothing, so the target opens without it and error-cards. |

package/guides/iap-products.md

@@ -1,16 +1,17 @@
 # Registering digital products as App Store in-app purchases (`himi store iap`)
 
-`himi store iap` registers an app owner's **selected digital products** in the owner's
-existing App Store Connect app. It configures each product's draft metadata, an exact
+`himi store iap` registers an app owner's **digital products** in the owner's existing
+App Store Connect app. It configures each product's draft metadata, an exact
 initial price and explicit territories. It then exports a Wix→Apple mapping for a future
 backend import.
 
 It is an administration workflow, not a build: it never builds, signs or bumps a version,
-and it runs anywhere `himi` is installed. An owner needs only a manifest and a credential
-profile. It does not run during an app build or a customer checkout.
+and it runs anywhere `himi` is installed. An owner needs only a credential profile, plus
+either a manifest or a Wix site for `draft` to read. It does not run during an app build or
+a customer checkout.
 
-This version supports **one-time non-consumable** products only. Every other product type
-is refused before anything reaches Apple.
+It registers one-time **non-consumables**, and **consumable price tiers** for large
+catalogs. Subscriptions are refused before anything reaches Apple.
 
 ## Before you start
 
@@ -33,6 +34,56 @@ is refused before anything reaches Apple.
 There is **no ambient fallback**. `--profile` is required, and exported `ASC_*` variables
 are never used to decide which account to write to.
 
+## 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:
+
+```bash
+himi store iap draft --site <msid> --profile fit-club-owner --apple-app 6450000001 \
+  --bundle com.example.fitclub --base-territory USA --territories USA,CAN --out ./iap-products.json
+```
+
+| Wix item | Drafted as |
+|---|---|
+| Digital store product, paid online program, one-time "unlimited" pricing plan | a non-consumable |
+| 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 |
+| Free, hidden (unpublished, archived or not visible) or unclassified item | skipped |
+| Item priced in another currency than the base territory | skipped |
+| Bookings services and events | never read: real-world services can't be in-app purchases |
+
+- **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.
+- **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.
+- **`--merge <manifest>` keeps an earlier manifest's mappings.** Anything it already maps
+  keeps its product id, and only new catalog items are added. Use it on every redraft,
+  because product ids are permanent.
+- **`--report <file>`** saves the skipped items and their reasons.
+- **The draft is a starting point.** Review or trim it if you like, then run `plan` as
+  usual. Nothing in App Store Connect changes until `apply`.
+
+### Price tiers for large catalogs: `--mode tiers`
+
+Thousands of items would mean thousands of Apple products, each needing App Review.
+`--mode tiers` drafts **one consumable per Apple price point** instead (for example
+`<bundle>.tier.usd_1_99`). Each tier lists, under `unlocks`, every Wix item it pays for.
+
+- **Wix prices are grouped by the Apple point they resolve to.** Items at 1.10, 1.50 and
+  1.99 USD all go into the 1.99 tier, and the shopper pays the tier's Apple price.
+- **An item priced above Apple's highest point is skipped,** with its reason.
+- **This needs Apple's price grid,** read through any in-app purchase the app already has.
+  If the app has none yet, tiers are keyed by Wix price and the draft says so; redraft
+  once the first product exists.
+
+A shopper buys the tier, and the backend grants the item they chose.
+
+Apple can't restore a consumable, so each unlocked item must be recorded against the
+shopper's Wix member account. That delivery is the backend's job, not this command's.
+
 ## The manifest
 
 The manifest is an explicit, versioned selection. Nothing is inferred from names or prices,
@@ -74,19 +125,27 @@ Rules, all checked locally before any request:
 - **`classification`** must be `"digital"`. Physical goods and unclassified products are
   refused. The classification is your configuration; this command does not make Apple's
   policy decisions for you.
-- **`productId`** must be stable, and you supply it. Apple product ids and types are
-  **immutable** once created, so the id is never generated or regenerated.
-- **`price.amount`** is an exact decimal **string**. It must match one of Apple's price
-  points exactly. It is never rounded, and a nearby price is never substituted.
+- **`productId`** must be stable: drafted from the Wix id, or chosen by you. Apple product
+  ids and types are **immutable** once created, so an id is never regenerated.
+- **`type`** is `"nonConsumable"` or `"consumable"`. A consumable price tier names
+  `unlocks` (a list of `{entityType, entityId, entitlement}`) instead of `wix`; every other
+  item names exactly one `wix` entity.
+- **`price.amount`** is a decimal **string**. Under the default `price.rule` of `"exact"`
+  it must match one of Apple's price points exactly; it is never rounded, and a nearby
+  price is never substituted. With `"rule": "atLeast"` it takes the lowest point at or
+  above the amount, and `plan` shows which.
+- **Apple's field limits:** display name 2–30 characters, description at most 45,
+  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.
 - **Duplicates are refused:** a product id, Wix entity, entitlement or reference name
-  used twice.
+  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.
 
 ## The workflow
 
 ```bash
+himi store iap draft  --site <msid> --profile fit-club-owner --apple-app 6450000001 --bundle com.example.fitclub --base-territory USA --out ./iap-products.json
 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
@@ -138,6 +197,19 @@ created. The plan marks this in the item's `notes`.
    it reads everything back.
 5. Writes the result file, even when the run is partial.
 
+**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.
+
+- **`apply --limit <n>`** creates at most `n` new products per run and reports the rest as
+  `deferred`. Rerunning the same plan continues where the last run stopped.
+- **Only products with planned writes are re-read.** Products the plan reused are reported
+  from the plan.
+- **Per-item registration of thousands of products still takes many hours.** Every one
+  also needs App Review, so prefer `--mode tiers` at that scale.
+- **Rate limits are handled:** throttled reads wait for Apple's `Retry-After` and retry.
+- **Plans and results with more than 50 products print a summary,** including any products
+  whose Apple price is higher than requested. The files always list every product.
+
 **When a write's outcome is unknown** (a lost response, a timeout, a 409), apply reads
 Apple again before doing anything else:
 
@@ -154,7 +226,8 @@ to save it in the same shape as the result file.
 
 Local state lives in `~/.himalaya/store-iap/<appleAppId>/`:
 
-- **`journal.json`** is an append-only record of identifiers and step outcomes. Nothing
+- **`journal.jsonl`** is an append-only record of identifiers and step outcomes, one line
+  per step. Nothing
   reads it back to decide anything. Every run re-reads the target app, and a product Apple
   hasn't listed yet is caught by apply's read-before-retry, so deleting the journal is
   always safe.
@@ -165,11 +238,11 @@ Local state lives in `~/.himalaya/store-iap/<appleAppId>/`:
 
 Each item has two parts:
 
-- **`mapping`** — the Wix site/app/bundle, the Wix entity and entitlement, the Apple product
-  id, the Apple resource id and the product type.
+- **`mapping`** — the Wix site/app/bundle, the Wix entity and entitlement (or, for a price
+  tier, its `unlocks`), the Apple product id, the Apple resource id and the product type.
 - **`provisioning`**:
   - `outcome` — one of `created`, `updated`, `reused`, `conflict`, `partial`, `failed`
-    (`status` also reports `absent` and `incomplete`)
+    or `deferred` (`status` also reports `absent` and `incomplete`)
   - per-step states and any conflicts
   - `unmet` — where Apple still differs from the manifest
   - the requested and observed price, availability and locales
@@ -207,9 +280,8 @@ future importer must authenticate ownership and re-read Apple before activating
 
 Not in this version:
 
-- subscriptions and consumables
+- subscriptions
 - review screenshot upload and submission
 - changing a live price
-- Wix catalog discovery
 - Google Play
 - backend import and checkout activation

package/guides/push-cli-onboarding.md

@@ -45,7 +45,8 @@ himi notify setup --content ./liftgear --target wix \
 The APNs environment must match the signed app. The Android package must match its
 Firebase client configuration; it need not equal the iOS bundle ID. Existing public
 bindings come from `provisioning.json`; flags override them. Keep the build configuration
-aligned with the selections. This command does not rewrite `config.ts` or build a binary.
+aligned with the selections. A successful setup turns push on in `config.ts` (see
+[Native push configuration](#native-push-configuration)); the command never builds a binary.
 
 To also request Apple signing resources, add `--apple-signing`, `--asc-key-file`,
 `--asc-key-id`, and `--asc-issuer-id`. The App Store Connect key is separate from the
@@ -82,13 +83,26 @@ repeats the provisioning POST automatically. Inspect status before retrying.
 After setup, continue normal app development, validation, publish/preview/promote and
 native distribution. Native push configuration, member authentication, device-token
 registration and a delivery/tap test are still required; for the test, see
-[Send a test notification](#send-a-test-notification). Setup does not enable native
-capabilities, choose a Ping family, send notifications or verify phone delivery; the app's
-`config.ts` does the first two (see [Native push configuration](#native-push-configuration)).
+[Send a test notification](#send-a-test-notification). Setup turns push on in the app's
+`config.ts` and picks the Ping family there (see
+[Native push configuration](#native-push-configuration)); it does not send notifications or
+verify phone delivery.
 
 ## Native push configuration
 
-The app's own `config.ts` turns push on; `himi notify setup` never edits it.
+Once the setup is accepted (`ready`, or still `provisioning`), `himi notify setup` turns push on in
+the app's own `config.ts`, once. Until it is on, the command does not report success.
+It adds only what is missing and leaves what you wrote alone:
+
+- a `push` block with no `routes`;
+- `"push"` in `capabilities`;
+- `siteId` in a `WixConsumerAuthProvider({ … })` login that has none.
+
+It saves the original to `.himi/notify-setup-backup/`, checks the edit with
+`himi validate --strict`, and puts the original back if the edit introduced an error. What it
+cannot add safely, such as a login that is not a Wix member login or a `push` block of your own,
+it prints as an instruction instead. `--dry-run` shows the planned edit without writing it, and
+a second run changes nothing. The result:
 
 ```ts
 auth: WixConsumerAuthProvider({
@@ -99,15 +113,12 @@ auth: WixConsumerAuthProvider({
   bootAsVisitor: true,
 }),
 capabilities: ["push" /* , … */],
+// Routes are derived at build time from provisioning.json and your screens; see himi validate.
 push: {
   registrar: "wix-ping",
   pingAppName: "WixBrandedWebApp",
   requestPermissionOnLaunch: true,
   payloadAdapter: "wix-ping",
-  routes: [
-    { match: "my-account/:site/stores/orders/:orderId",
-      link: "<scheme>://screen/<order-screen>?id={orderId}" },
-  ],
 },
 ```
 
@@ -119,13 +130,72 @@ push: {
   Keep `siteId` in `auth` on the site `himi notify setup` configured. A changed `siteId` or
   `clientId` ships with `himi push` like the rest of the config, and the app picks it up on
   its next launch; until then iOS stops registering rather than register the old site.
-- `routes` turn the Wix links inside notifications into the app's screens, one route per
-  link shape. A notification whose link matches no route opens the app without navigating.
-  `himi validate` warns when a route names a screen the app does not declare.
+  `himi validate` reports `push-auth-site` when the login is not a member login on that site.
 - The `push` block ships with `himi push`; changing it needs no new binary. The binary still
   has to carry the push entitlement: the `branded-lite` shell requests it, and the signing
   profile must grant `aps-environment` (see the QA build notes below).
 
+### Notification routes
+
+Routes turn the Wix links inside notifications into the app's screens. When the `push` block
+has no `routes` and `provisioning.json` lists the site's verticals (`himi site analyze --apply`
+writes them), every build (`himi run`, `himi validate` and `himi push`) derives the routes from
+the app's linkable screens: `navigation.linkableScreens`, or every screen when it lists none.
+
+Routes are never written into `config.ts`, so adding or renaming a screen needs only the next
+build. A notification gets a route only when its screen is certain: the screen `push.screens`
+names, or else the destination's canonical screen id. Template apps already use those ids. The
+site's verticals decide which destinations `himi validate` expects a screen for.
+
+| Destination | Site vertical | Canonical screen | Opens |
+|---|---|---|---|
+| `store.order` | `store` | `himi_order` | the order |
+| `bookings.session` | `bookings` | `himi_bookings` | the member's bookings |
+| `groups.post` | `groups` | `himi_group` | the group |
+| `forum.thread` | `forum` | `himi_forum_post` | the post |
+| `forum.create` | `forum` | `himi_create_post` | the new-post screen |
+| `blog.post` | `blog` | `himi_blog_post` | the post |
+| `members.profile` | `members` | `himi_member` | the member |
+| `events.event` | `events` | `himi_event` | the event |
+| `galleries.shared` | `galleries` | `himi_galleries` | the gallery list |
+| `galleries.album` | `galleries` | `himi_photo_album` | the album |
+| `notifications.list` | `notifications` | `himi_notifications` | the notifications list |
+
+For screens with other ids, name them in `push.screens`. It is for authoring only and is never
+served:
+
+```ts
+push: {
+  // …
+  screens: {
+    "store.order": "my_order",
+    "bookings.session": "my_bookings",
+    "blog.post": { screenId: "article", paramKey: "slug" },
+  },
+},
+```
+
+A screen that opens one item gets its id in the param named `id` when its linkable screen
+declares one, otherwise in its only declared param key. When it declares several, name the one it
+reads with `paramKey`. The key has to be one of the screen's `paramKeys`: a shell passes a screen
+only the params its linkable screen declares.
+
+`himi validate` lists, without failing even under `--strict`, each destination the site has that
+no screen takes, with the fix, and the verticals Wix sends no member notification links for.
+
+To write the table yourself, declare `routes`. A declared table, even an empty one, is used as
+is:
+
+```ts
+routes: [
+  { match: "my-account/:site/stores/orders/:orderId",
+    link: "<scheme>://screen/<order-screen>?id={orderId}" },
+],
+```
+
+A notification whose link matches no route opens the app without navigating. `himi validate`
+warns when a declared route names a screen the app does not declare.
+
 **Customer push QA builds use `himi dist --signing byo`.** After publishing an approved
 release, use a backend and reachable runner source that support the customer-signing flow.
 Use the app owner's account for both logins and explicitly select the deployed customer target:

package/guides/wix-site-to-himi-app.md

@@ -217,6 +217,11 @@ images stay as `static.wixstatic.com` URLs in descriptors — do not vendor
   literals (`HIMALAYA.md` copy rule).
 - **Auth** — `wix-consumer`; boot visitor unless a job needs members.
   `himi docs wix-login-integration`. Members are **site members**.
+- **Notifications** — give each vertical's detail screen its canonical id (`himi_order`,
+  `himi_event`, `himi_forum_post`, …) or name it in `push.screens`, and list it in
+  `navigation.linkableScreens` with the param it reads. After `himi notify setup`, every build
+  derives the notification routes from `provisioning.json` and those screens; `himi validate`
+  lists the ones still unrouted. `himi docs push-cli-onboarding`.
 
 ### 5. Prove it, then ship
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1154.0",
+  "version": "0.1156.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": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "abcc18f41ab0377e683efdd8751e550f7c7aad90c431731a54d9960c"
+  "falconPackageHash": "5d6bcf8d364821a37f27c35e0d3c50376b277479f44cc1e94d5c6729"
 }