@wix/himalaya-cli 0.1154.0 → 0.1155.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1154.0",
+  "version": "0.1155.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": "fdcb8ee43c58cbb6299d582962eed54297bb7c2152984221e59fccd4"
 }