@wix/himalaya-cli 0.1536.0 → 0.1537.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

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.1537.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": "d6ee8032d51eaeb8dc274ee3f30d37f7461aff9849c18acd863e9fd6"
 }