@wix/himalaya-cli 0.1536.0 → 0.1538.0

package/fixtures/wix-canned.json

@@ -222,6 +222,7 @@
       "total": 2
     }
   },
+  "POST /bookings/v2/services/categories/query": { "categories": [] },
   "POST /bookings/v2/services/query": {
     "services": [
       {

package/guides/cms-collections.md

@@ -266,6 +266,12 @@ operation alone:
 { readRole: "ANYONE", writeRole: "ADMIN", insertRole: "ANYONE" }
 ```
 
+Wix stores the `ADMIN` role as `CMS_EDITOR`: reading a collection's permissions back (the
+`/wix-data/v1/permissions` endpoint, `getPermissions`) shows `CMS_EDITOR`, and writing them with
+`updatePermissions` accepts `CMS_EDITOR`, not `ADMIN`. Sending `ADMIN` there fails with a misleading
+`dataPermissions is invalid: itemUpdate value is required`. Creating a collection, which is what
+`himi cms create` does, still takes `ADMIN`.
+
 `ANYONE` is accepted on `insertRole`/`updateRole` and refused on `removeRole` and on the
 `writeRole` blanket. The asymmetry is the point: an unwanted row can be removed, a removed
 row cannot be brought back. Reach for this when the app writes as the identity it actually
@@ -386,6 +392,16 @@ seed` must not bury that under sample data again.
 
 `--only <id>` scopes to one collection; `--dry-run` reports without writing.
 
+Rows go to the site in batches of 100, one request each, in the order they appear in the
+seed array. Wix answers a batch with HTTP 200 whatever happened to the rows, so the report
+is built from each row's own result: `inserted` counts only the rows Wix confirmed, and a
+row it refused appears under `failed` with its position in the seed array, its error code
+and its reason, and the run exits 1 with `code: "seed_rows_failed"`. A request that fails
+outright is not retried — an insert has no idempotency key, so a retry could duplicate rows
+that already landed. It stops that collection and exits 1 with what landed under `partial`;
+rows marked `unconfirmed` may or may not exist, so run `himi cms query` before seeding
+again.
+
 ### `himi cms seed --ai` — generate rows to review
 
 Writes a full row set with the correct JSON type per field into a sidecar
@@ -439,6 +455,21 @@ const rows = (res.dataItems ?? []).map((item) => ({
 Do not bind `_createdDate` directly to `Text`: an object crosses the worker
 boundary as structured data and otherwise paints as `[object Object]`.
 
+`@himalaya/wix-data` covers more than a query: patch, save, count, bulk writes,
+aggregation, distinct values, search and references (the full list is in
+`himi docs wix-api-usage`). Three rules matter when your collection is one you
+own:
+
+- **Change fields with `patchDataItem`, not `updateDataItem`.** An update replaces the
+  whole item, so a call that sends two fields deletes the rest — including the field
+  you look the row up by.
+- **Write a long list with a bulk call, and check the result.** One bulk call is one
+  write against the site's per-minute quota, but it answers `200` even when some
+  items failed; `bulkFailures(res)` lists them.
+- **Do not write a multi-reference field through insert, save or update.** Wix
+  accepts the call and stores nothing. This is also why `himi cms` does not declare
+  reference fields yet.
+
 **Bake the collection ids in as a screen `input` and read them back**, so the worker holds
 no hardcoded ids and `config.ts` stays the single source of truth:
 

package/guides/himi-json-output.md

@@ -80,6 +80,15 @@ 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 cms seed` codes
+
+| Code | Meaning |
+|---|---|
+| `seed_rows_failed` | At least one seed row did not land. Wix answers a bulk insert with HTTP 200 whatever happened to the rows, so the report lists each failure under `failed`: `collection`, `rows` (zero-based positions in the seed array), `outcome` (`rejected`: Wix refused them; `unconfirmed`: they may or may not exist; `not-sent`: never attempted), Wix's `code` when it gave one, and a `reason`. `inserted` counts only confirmed rows. Exit 1. |
+| `seed_request_failed` | A bulk-insert request failed outright (a refused request, a server error, a timeout or a dropped connection), so the run stopped. Printed on stderr with `ok: false` beside the legacy `error`, `app`, `site` and `hint` fields; `partial` carries the report so far, with the same `failed` list (that batch as `rejected` or `unconfirmed`, the collection's later rows as `not-sent`) and `code: "seed_request_failed"` too, even when an earlier batch had rows refused. Collections after the failing one were not attempted. Exit 1. |
+
+This is not a whole-command migration: the command's other refusals still have no code.
+
 ## `himi store iap status` codes
 
 Status adds these stable codes to incomplete JSON results. Existing result fields and exit
@@ -116,7 +125,9 @@ An invalid manifest fails with `manifest_invalid`, like the other `store iap` co
 ## `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`.
+`ok: false` with the first step's code; each step also carries its own `code`. A dry run adds
+`diff: { inPlace, toCreate, conflicts, unverified, blocked, skipped }` (every step in exactly one list), and reports a step whose state cannot be read
+without writing (the appleIAP provider, once the app is registered) as `state: "unverified"`.
 
 | Code | Meaning |
 |---|---|
@@ -136,7 +147,7 @@ An invalid manifest fails with `manifest_invalid`, like the other `store iap` co
 | `mapping_unsupported` | The purchase flow cannot map this item yet (a vertical other than Online Programs, Wix Stores or one-time Pricing Plans, a price tier, or an item 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 or Catalog 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. |
+| `setup_incomplete` | Steps are only planned or unverified (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. |

package/guides/iap-products.md

@@ -109,8 +109,8 @@ managed submission. Other per-item failures include `catalog_screenshot_upload_f
 
 `check` combines the registration, stored purchase key, Catalog mappings, Apple product and
 screenshot readiness, vertical sales rules, app visibility, and source/build binding in one
-read-only report. Unlike `connect --dry-run`, it never reports the payment provider as planned
-and counts that as readiness. Every finding carries `state: "ok" | "missing" | "blocked"`, a
+read-only report. Like `connect --dry-run`, which reports the payment provider `unverified`, it
+never counts the unread provider as ready. Every finding carries `state: "ok" | "missing" | "blocked"`, a
 stable `code`, and a `fix`; overall `code` is `ok` or `setup_incomplete` (exit 0 or 1).
 
 ```sh
@@ -490,12 +490,14 @@ In order:
 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).
+   of the provider's state, so a rerun connects it again (the call is safe to repeat), and a dry
+   run for an app that is already registered reports this step `unverified` instead of planned.
 4. **One mapping per Wix item → Apple product, through Catalog `listProducts` / `createProduct`.** Online Programs map by program id, Wix Stores
    digital products by product id, and one-time unlimited Pricing Plans by plan id (the ids the
    purchase flow looks up), all only as non-consumables. A plan is mapped only when the site reads it
    as one-time unlimited (one payment, valid until cancelled); a recurring, time-limited or archived
-   plan, or one connect cannot read, is skipped. Other verticals, price tiers and consumable items
+   plan is skipped. When the site's plans cannot be read, each plan is `failed` (`request_failed`,
+   `unverified` in the dry-run diff) and not mapped. Other verticals, price tiers and consumable items
    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
@@ -509,7 +511,13 @@ In order:
    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
+**Review first.** `--dry-run` reads everything it can and writes nothing: the site's purchases
+apps and the app's Catalog mappings (plus the site's plans when the manifest maps plans), never
+the provider connection, the key write or a mapping write. It ends with a `diff` (in JSON,
+`diff: { inPlace, toCreate, conflicts, unverified, blocked, skipped }`, each a list of `app`,
+`key`, `provider` or `mapping <id>`, every step in exactly one): what is already in place, what
+applying would create, what it would leave as a conflict, what could not be read (including a
+read that failed), what is blocked, and what connect does not handle. 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)

package/guides/release-notes.md

@@ -14,6 +14,18 @@ areas, always in the same order, so you can skim for the one you care about.
 
 ---
 
+## 2026-11-02
+
+### Validate & test
+
+- **`himi validate` now judges `textPrimary` on card surfaces.** Body text was judged only against
+  the page (`surfacePrimary`), so a navy page with white cards and white text validated clean while
+  every card title rendered white on white. `textPrimary` is now also judged against
+  `surfaceSecondary` and `surfaceElevated`: below 1.5:1 the text is invisible and validate fails
+  with an error (also for `textPrimary` on the page); below WCAG AA 4.5:1 it is a warning. The
+  finding says when the page and the card sit on opposite sides of mid-grey, so no single text
+  colour can serve both. (#4999)
+
 ## 2026-11-01
 
 ### Getting started & the CLI

package/guides/wix-api-usage.md

@@ -197,8 +197,9 @@ surface. Lead with it: it builds the request, calls the bridge, and decodes the
 ```ts
 import { queryDataItems, insertDataItem, updateDataItem, removeDataItem } from "@himalaya/wix-data";
 
-// queryDataItems(collectionId, limit = 50, filter?, returnTotalCount = false, offset = 0, sort?)
+// queryDataItems(collectionId, limit = 50, filter?, returnTotalCount = false, offset = 0, sort?, options?)
 //   → { dataItems?, items?, pagingMetadata? }
+// `options` (all optional): { consistentRead, cursorPaging, fields, includeReferences, language, includeDraftItems }
 const res = await queryDataItems("MyCollection", 50);
 const rows = (res.dataItems ?? res.items ?? []).map((it) => it.data);   // parsed objects, not bytes
 
@@ -206,12 +207,58 @@ const rows = (res.dataItems ?? res.items ?? []).map((it) => it.data);   // parse
 const newest = await queryDataItems("Jobs", 1, undefined, false, 0, [{ fieldName: "postedDate", order: "DESC" }]);
 ```
 
-The full items CRUD is typed: `insertDataItem(collectionId, data)` (POST `/wix-data/v2/items`),
-`updateDataItem(collectionId, id, data)` (PUT), and `removeDataItem(collectionId, id)` (DELETE). This is
-**Wix CMS / Data (data *items*)** — distinct from the Catalog **`data-collections-v1` schema** API
-(`@himalaya/wix-data-collections`), which describes a collection's *shape*, not its rows; don't conflate them.
+The client covers the whole everyday items surface. This is **Wix CMS / Data (data *items*)** — distinct from the
+Catalog **`data-collections-v1` schema** API (`@himalaya/wix-data-collections`), which describes a collection's
+*shape*, not its rows; don't conflate them.
 
-Only reach for the raw transport for a `wix-data` endpoint the client doesn't cover yet:
+| You want to… | Call | Mind |
+|---|---|---|
+| Read one row | `getDataItem(collectionId, id)` | not a page plus `.find()` |
+| Create a row | `insertDataItem(collectionId, data, { id? })` | create-only: a repeated `id` is a 409, not an overwrite |
+| Insert or replace by id | `saveDataItem(collectionId, data, { id? })` | safe to retry only with an explicit `id` (without one Wix mints a new id, so a retry adds a second row); replaces the whole item |
+| Change some fields | `patchDataItem(collectionId, id, [setField("title", "New"), incrementField("views")])` | prefer this to `updateDataItem`; increments are atomic |
+| Replace a whole item | `updateDataItem(collectionId, id, data)` | **deletes every field you leave out** |
+| Delete a row | `removeDataItem(collectionId, id)` | irreversible |
+| Count rows | `countDataItems(collectionId, filter?)` | one read, no rows transferred |
+| Write many rows | `bulkInsertDataItems`, `bulkSaveDataItems`, `bulkUpdateDataItems`, `bulkPatchDataItems`, `bulkRemoveDataItems` | up to 1000 per call (100 for patch); one write against the site quota |
+| Group, sum, average | `aggregateDataItemsPipeline(collectionId, { stages })` | not for Wix app collections |
+| List the values in use | `queryDistinctValues(collectionId, fieldName, { filter? })` | for filter chips and pickers |
+| Search text | `searchDataItems(collectionId, "terms", { fuzzy? })` | always eventually consistent; offset `paging` only (Wix refuses cursor paging on search); a collection whose search is not enabled answers `428 WDE0190` |
+| Follow relations | `queryReferencedDataItems`, `isReferencedDataItem`; write with `insertDataItemReferences`, `removeDataItemReferences`, `replaceDataItemReferences` | read back with `includeReferences` |
+
+These catch people out:
+
+- **A bulk call answers `200` even when items failed.** Check `bulkFailures(res)` (or
+  `res.bulkActionMetadata.totalFailures`) and match each failure to your input with
+  `itemMetadata.originalIndex`. A failed entry looks like
+  `{ itemMetadata: { id, originalIndex: 1, success: false, error: { code: "WDE0074", description } } }`
+  (`WDE0074`: the id already exists; `WDE0073`: no such item to remove). A **permission** refusal
+  (`WDE0027`) comes back both ways: a bulk insert, update or patch the caller may not make still answers
+  `200` with every item failed, while a bulk remove the caller may not make is a `403` for the whole
+  request, like a single-item write. Handle both.
+- **Cursor paging: pass the same arguments for every page.** The cursor carries the first page's query, and Wix
+  refuses most of it beside a cursor (`400 WDE0080`): the filter, sort and `returnTotalCount` of a query, the field name
+  of distinct values, the referring item of a referenced-items read, the stages of an aggregation. The client drops
+  those on a page that carries a cursor.
+- **A read right after your own write can miss it.** Reads come from the nearest mirror; pass
+  `{ consistentRead: true }` in the query options when you need to see what you just wrote.
+- **Multi-reference values are silently dropped** when written through insert, save, update or any bulk write — Wix
+  answers `200` and stores nothing. Write links with the reference calls (or `setField` with an array of ids), and read
+  back with `includeReferences` to confirm. A multi-reference field is absent from query results unless you name it
+  in `includeReferences`, which takes objects, `{ includeReferences: [{ field: "authors" }] }`; a plain string array
+  is a `400 Expected an object`.
+- **Offline and caching treat some of these reads as writes.** On iOS, Android and the web host, the offline
+  guard counts a `POST` as a read only when its path ends in `query`, `count`, `list`, `search`, `get` or `read`. So
+  `aggregateDataItemsPipeline`, `queryDistinctValues`, `queryReferencedDataItems` and `isReferencedDataItem` are
+  refused offline like writes rather than answered from cache. And in an app whose cache policy tags
+  `/wix-data/v2/items`, any non-cacheable `POST` under that prefix, `countDataItems` and `searchDataItems` included,
+  purges that family's cached queries. Until those layers learn these endpoints, keep such reads off a hot path.
+- **Dates in filters:** compare a system date such as `_createdDate` as `{ $date: "…" }`. Wix's reference says a plain
+  ISO string is accepted, but in testing against a live site a bare string on a system date field matched nothing and
+  still answered `200` with no rows, so wrap it.
+
+Not wrapped: the draft/publish lifecycle, filter-driven async patch and remove, `truncate`, and the single-reference
+calls (use the bulk reference calls with one entry). For those, use the raw transport:
 
 ```ts
 // un-codegen'd fallback ONLY — prefer the typed queryDataItems above:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1536.0",
+  "version": "0.1538.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": "3569b3866b23c7180686bdc03257127c68ddb324a7c69092ee0951e9"
+  "falconPackageHash": "a1a15dbe939dfa2c63ef1cc4b38f88d026f5eda14efaf885d5c9aa84"
 }