@wix/himalaya-cli 0.941.0 → 0.943.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/bookings-v2/src/index.d.ts

@@ -185,7 +185,17 @@ export interface WixUpdateBookingResponse {
 export interface WixRescheduleBookingResponse {
     booking: WixBooking;
 }
+/**
+ * @scope owner — requires an owner / business identity — a visitor session gets 403.
+ *
+ * POST /bookings/v2/bookings/query
+ */
 export declare function queryBookings(req?: WixQueryBookingsRequest, opts?: WixCallOptions): Promise<WixQueryBookingsResponse>;
+/**
+ * @scope owner — requires an owner / business identity — a visitor session gets 403.
+ *
+ * GET /bookings/v1/bookings
+ */
 export declare function listBookings(req?: WixListBookingsRequest, opts?: WixCallOptions): Promise<WixListBookingsResponse>;
 export declare function getBooking(bookingId: string, opts?: WixCallOptions): Promise<WixGetBookingResponse>;
 export declare function createBooking(req?: WixCreateBookingRequest, opts?: WixCallOptions): Promise<WixCreateBookingResponse>;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/wix-data/src/index.d.ts

@@ -50,9 +50,56 @@ export interface WixUpdateDataItemRequest {
     };
 }
 /** Query items in a collection — POST /wix-data/v2/items/query.
- *  Pass `returnTotalCount: true` to ask Wix to fill `pagingMetadata.total`
- *  (offset paging only; omitted by default because counting is extra work). */
-export declare function queryDataItems(dataCollectionId: string, limit?: number, filter?: Record<string, unknown>, returnTotalCount?: boolean): Promise<WixQueryDataItemsResponse>;
+ *
+ *  `filter` is the Wix Data v2 filter object, which the type cannot express (it is
+ *  `Record<string, unknown>` by construction). A field name maps to a value for
+ *  equality, or to an operator object:
+ *
+ *  ```ts
+ *  await queryDataItems("Listings", 20, { city: "Tel Aviv" });
+ *  await queryDataItems("Listings", 20, { price: { $lte: 2_500_000 } });
+ *  await queryDataItems("Listings", 20, { _id: { $in: [a, b] } });
+ *  ```
+ *
+ *  `offset` pages: ask for `limit` rows starting at `offset`. Pair it with
+ *  `returnTotalCount: true`, which fills `pagingMetadata.total` so a caller knows
+ *  when to stop — it is omitted by default because counting is extra work, and it
+ *  reports total for OFFSET paging only, which is the mode this function uses.
+ *
+ *  ```ts
+ *  const first = await queryDataItems("Listings", 50, undefined, true);
+ *  const total = first.pagingMetadata?.total ?? 0;
+ *  const rest  = await queryDataItems("Listings", 50, undefined, false, 50);
+ *  ```
+ *
+ *  To read ONE row, use `getDataItem` rather than a page plus a client-side
+ *  `.find()` — that pattern breaks silently once the collection outgrows `limit`. */
+export declare function queryDataItems(dataCollectionId: string, limit?: number, filter?: Record<string, unknown>, returnTotalCount?: boolean, offset?: number): Promise<WixQueryDataItemsResponse>;
+/** Read ONE item by id — GET /wix-data/v2/items/{dataItemId}?dataCollectionId=…
+ *
+ *  Reach for this on a detail screen. Before it existed the only read this package
+ *  offered was `queryDataItems`, so a detail worker had to fetch a bounded page and
+ *  find its row client-side:
+ *
+ *  ```ts
+ *  const res = await queryDataItems("Listings", 50);          // ← DON'T
+ *  const row = (res.dataItems ?? []).find((it) => it.id === id);
+ *  ```
+ *
+ *  That is correct against a handful of seeded rows and silently wrong once the
+ *  collection outgrows `limit`. Ask for the row instead:
+ *
+ *  ```ts
+ *  const { dataItem } = await getDataItem("Listings", id);     // ← DO
+ *  ```
+ *
+ *  The collection id rides the query string rather than a body, because the Wix
+ *  gateway drops a GET body — and the string is built with `encodeURIComponent`
+ *  rather than `URLSearchParams`, which the bare Tier-5 worker runtimes (JSCore /
+ *  Hermes / QuickJS-ng) do not provide. */
+export declare function getDataItem(dataCollectionId: string, dataItemId: string): Promise<{
+    dataItem?: WixDataItem;
+}>;
 /** Insert an item — POST /wix-data/v2/items. */
 export declare function insertDataItem(dataCollectionId: string, data: Record<string, unknown>): Promise<{
     dataItem?: WixDataItem;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/wix-data.mjs

@@ -7,15 +7,28 @@ function wixCall(method, path, body) {
   }
   return globalThis.himalaya.wixApi.call(method, path, body);
 }
-function queryDataItems(dataCollectionId, limit = 50, filter, returnTotalCount = false) {
+function queryDataItems(dataCollectionId, limit = 50, filter, returnTotalCount = false, offset = 0) {
   if (!dataCollectionId) throw new Error("queryDataItems: dataCollectionId is required");
   const body = {
     dataCollectionId,
-    query: { paging: { limit }, ...filter ? { filter } : {} },
+    query: {
+      // `offset` is omitted when 0 so a caller that does not page sends the byte-identical
+      // body it sent before this parameter existed.
+      paging: { limit, ...offset ? { offset } : {} },
+      ...filter ? { filter } : {}
+    },
     ...returnTotalCount ? { returnTotalCount: true } : {}
   };
   return wixCall("POST", "/wix-data/v2/items/query", body);
 }
+function getDataItem(dataCollectionId, dataItemId) {
+  if (!dataCollectionId) throw new Error("getDataItem: dataCollectionId is required");
+  if (!dataItemId) throw new Error("getDataItem: dataItemId is required");
+  return wixCall(
+    "GET",
+    `/wix-data/v2/items/${encodeURIComponent(dataItemId)}?dataCollectionId=${encodeURIComponent(dataCollectionId)}`
+  );
+}
 function insertDataItem(dataCollectionId, data) {
   if (!dataCollectionId) throw new Error("insertDataItem: dataCollectionId is required");
   return wixCall("POST", "/wix-data/v2/items", {
@@ -36,6 +49,7 @@ function removeDataItem(dataCollectionId, id) {
   return wixCall("DELETE", `/wix-data/v2/items/${encodeURIComponent(id)}?${q}`);
 }
 export {
+  getDataItem,
   insertDataItem,
   queryDataItems,
   removeDataItem,

package/dist/cli.mjs

@@ -1378,7 +1378,12 @@ function readTemplateFiles(srcRoot) {
 function scaffoldFromTemplate(name, dir, template) {
   const srcRoot = templateSourceDir(template);
   if (!existsSync2(join3(srcRoot, "himalaya.content.json"))) {
-    throw new Error(`unknown template "${template}" (available: ${availableTemplates().join(", ") || "none bundled"})`);
+    throw new Error(
+      `unknown template "${template}" \u2014 not bundled with this CLI.
+  bundled: ${availableTemplates().join(", ") || "none"}
+  The published catalog is larger: \`himi template list --remote\` lists it, and
+  \`himi init <app> --template ${template} --remote\` fetches one from there.`
+    );
   }
   return finishScaffold(materializeSource(readTemplateFiles(srcRoot), name, dir), template);
 }

package/guides/sdk-reference.json

@@ -6955,16 +6955,18 @@
       {
         "name": "queryBookings",
         "kind": "function",
-        "jsdoc": "",
+        "jsdoc": "/**\n * @scope owner — requires an owner / business identity — a visitor session gets 403.\n *\n * POST /bookings/v2/bookings/query\n */",
         "decl": "export function queryBookings(\n  req: WixQueryBookingsRequest = {} as WixQueryBookingsRequest,\n  opts?: WixCallOptions,\n): Promise<WixQueryBookingsResponse>;",
-        "http": "POST /bookings/v2/bookings/query"
+        "http": "POST /bookings/v2/bookings/query",
+        "scope": "owner"
       },
       {
         "name": "listBookings",
         "kind": "function",
-        "jsdoc": "",
+        "jsdoc": "/**\n * @scope owner — requires an owner / business identity — a visitor session gets 403.\n *\n * GET /bookings/v1/bookings\n */",
         "decl": "export function listBookings(\n  req: WixListBookingsRequest = {} as WixListBookingsRequest,\n  opts?: WixCallOptions,\n): Promise<WixListBookingsResponse>;",
-        "http": "GET /bookings/v1/bookings"
+        "http": "GET /bookings/v1/bookings",
+        "scope": "owner"
       },
       {
         "name": "getBooking",
@@ -10524,10 +10526,17 @@
       {
         "name": "queryDataItems",
         "kind": "function",
-        "jsdoc": "/** Query items in a collection — POST /wix-data/v2/items/query.\n *  Pass `returnTotalCount: true` to ask Wix to fill `pagingMetadata.total`\n *  (offset paging only; omitted by default because counting is extra work). */",
-        "decl": "export function queryDataItems(\n  dataCollectionId: string,\n  limit = 50,\n  filter?: Record<string, unknown>,\n  returnTotalCount = false,\n): Promise<WixQueryDataItemsResponse>;",
+        "jsdoc": "/** Query items in a collection — POST /wix-data/v2/items/query.\n *\n *  `filter` is the Wix Data v2 filter object, which the type cannot express (it is\n *  `Record<string, unknown>` by construction). A field name maps to a value for\n *  equality, or to an operator object:\n *\n *  ```ts\n *  await queryDataItems(\"Listings\", 20, { city: \"Tel Aviv\" });\n *  await queryDataItems(\"Listings\", 20, { price: { $lte: 2_500_000 } });\n *  await queryDataItems(\"Listings\", 20, { _id: { $in: [a, b] } });\n *  ```\n *\n *  `offset` pages: ask for `limit` rows starting at `offset`. Pair it with\n *  `returnTotalCount: true`, which fills `pagingMetadata.total` so a caller knows\n *  when to stop — it is omitted by default because counting is extra work, and it\n *  reports total for OFFSET paging only, which is the mode this function uses.\n *\n *  ```ts\n *  const first = await queryDataItems(\"Listings\", 50, undefined, true);\n *  const total = first.pagingMetadata?.total ?? 0;\n *  const rest  = await queryDataItems(\"Listings\", 50, undefined, false, 50);\n *  ```\n *\n *  To read ONE row, use `getDataItem` rather than a page plus a client-side\n *  `.find()` — that pattern breaks silently once the collection outgrows `limit`. */",
+        "decl": "export function queryDataItems(\n  dataCollectionId: string,\n  limit = 50,\n  filter?: Record<string, unknown>,\n  returnTotalCount = false,\n  offset = 0,\n): Promise<WixQueryDataItemsResponse>;",
         "http": "POST /wix-data/v2/items/query"
       },
+      {
+        "name": "getDataItem",
+        "kind": "function",
+        "jsdoc": "/** Read ONE item by id — GET /wix-data/v2/items/{dataItemId}?dataCollectionId=…\n *\n *  Reach for this on a detail screen. Before it existed the only read this package\n *  offered was `queryDataItems`, so a detail worker had to fetch a bounded page and\n *  find its row client-side:\n *\n *  ```ts\n *  const res = await queryDataItems(\"Listings\", 50);          // ← DON'T\n *  const row = (res.dataItems ?? []).find((it) => it.id === id);\n *  ```\n *\n *  That is correct against a handful of seeded rows and silently wrong once the\n *  collection outgrows `limit`. Ask for the row instead:\n *\n *  ```ts\n *  const { dataItem } = await getDataItem(\"Listings\", id);     // ← DO\n *  ```\n *\n *  The collection id rides the query string rather than a body, because the Wix\n *  gateway drops a GET body — and the string is built with `encodeURIComponent`\n *  rather than `URLSearchParams`, which the bare Tier-5 worker runtimes (JSCore /\n *  Hermes / QuickJS-ng) do not provide. */",
+        "decl": "export function getDataItem(\n  dataCollectionId: string,\n  dataItemId: string,\n): Promise<{ dataItem?: WixDataItem }>;",
+        "http": "GET /wix-data/v2/items/{…}?dataCollectionId={…}"
+      },
       {
         "name": "insertDataItem",
         "kind": "function",
@@ -19013,91 +19022,106 @@
         "name": "MuteStatus",
         "kind": "type",
         "jsdoc": "/** \"MUTED\" silences the topic on this channel; \"UNMUTED\" delivers it. */",
-        "decl": "export type MuteStatus = \"MUTED\" | \"UNMUTED\";"
+        "decl": "export type MuteStatus = \"MUTED\" | \"UNMUTED\";",
+        "verified": false
       },
       {
         "name": "Channel",
         "kind": "type",
         "jsdoc": "/** Delivery channel. The mobile push channel value is unconfirmed; \"MOBILE\" is\n *  the working default the bundle passes. */",
-        "decl": "export type Channel = \"MOBILE\" | string;"
+        "decl": "export type Channel = \"MOBILE\" | string;",
+        "verified": false
       },
       {
         "name": "PreferenceState",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface PreferenceState {\n  /** \"MUTED\" | \"UNMUTED\" — whether the topic is delivered on this channel. */\n  muteStatus?: MuteStatus;\n}"
+        "decl": "export interface PreferenceState {\n  /** \"MUTED\" | \"UNMUTED\" — whether the topic is delivered on this channel. */\n  muteStatus?: MuteStatus;\n}",
+        "verified": false
       },
       {
         "name": "PreferenceStateData",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface PreferenceStateData {\n  state?: PreferenceState;\n}"
+        "decl": "export interface PreferenceStateData {\n  state?: PreferenceState;\n}",
+        "verified": false
       },
       {
         "name": "PreferenceInfo",
         "kind": "interface",
         "jsdoc": "/** One topic×channel preference for the implicit recipient. */",
-        "decl": "export interface PreferenceInfo {\n  /** The notification topic id (matches NotificationTopic.id). */\n  topicId: string;\n  /** Delivery channel this preference applies to (e.g. \"MOBILE\"). */\n  channel?: Channel;\n  stateData?: PreferenceStateData;\n}"
+        "decl": "export interface PreferenceInfo {\n  /** The notification topic id (matches NotificationTopic.id). */\n  topicId: string;\n  /** Delivery channel this preference applies to (e.g. \"MOBILE\"). */\n  channel?: Channel;\n  stateData?: PreferenceStateData;\n}",
+        "verified": false
       },
       {
         "name": "NotificationPreferences",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface NotificationPreferences {\n  preferencesInfo?: PreferenceInfo[];\n}"
+        "decl": "export interface NotificationPreferences {\n  preferencesInfo?: PreferenceInfo[];\n}",
+        "verified": false
       },
       {
         "name": "GetMyNotificationPreferencesResponse",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface GetMyNotificationPreferencesResponse {\n  preferences?: NotificationPreferences;\n}"
+        "decl": "export interface GetMyNotificationPreferencesResponse {\n  preferences?: NotificationPreferences;\n}",
+        "verified": false
       },
       {
         "name": "NotificationTopic",
         "kind": "interface",
         "jsdoc": "/** A notification topic — its id is the PreferenceInfo.topicId; displayName is\n *  the row label shown in the UI. */",
-        "decl": "export interface NotificationTopic {\n  id: string;\n  displayName?: string;\n}"
+        "decl": "export interface NotificationTopic {\n  id: string;\n  displayName?: string;\n}",
+        "verified": false
       },
       {
         "name": "GetNotificationTopicsResponse",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface GetNotificationTopicsResponse {\n  topics?: NotificationTopic[];\n}"
+        "decl": "export interface GetNotificationTopicsResponse {\n  topics?: NotificationTopic[];\n}",
+        "verified": false
       },
       {
         "name": "UpsertMyNotificationPreferencesRequest",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface UpsertMyNotificationPreferencesRequest {\n  preferencesInfo: PreferenceInfo[];\n}"
+        "decl": "export interface UpsertMyNotificationPreferencesRequest {\n  preferencesInfo: PreferenceInfo[];\n}",
+        "verified": false
       },
       {
         "name": "UpsertMyNotificationPreferencesResponse",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface UpsertMyNotificationPreferencesResponse {\n  preferences?: NotificationPreferences;\n}"
+        "decl": "export interface UpsertMyNotificationPreferencesResponse {\n  preferences?: NotificationPreferences;\n}",
+        "verified": false
       },
       {
         "name": "muteStatusFor",
         "kind": "function",
         "jsdoc": "/** Map a UI \"on\" boolean to a MuteStatus: on ⇒ delivered (\"UNMUTED\"). */",
-        "decl": "export function muteStatusFor(on: boolean): MuteStatus;"
+        "decl": "export function muteStatusFor(on: boolean): MuteStatus;",
+        "verified": false
       },
       {
         "name": "getMyNotificationPreferences",
         "kind": "function",
         "jsdoc": "/** Get the signed-in member's notification preferences —\n *  GET /notifications/v1/preferences-by-implicit-recipient. */",
-        "decl": "export function getMyNotificationPreferences(): Promise<GetMyNotificationPreferencesResponse>;"
+        "decl": "export function getMyNotificationPreferences(): Promise<GetMyNotificationPreferencesResponse>;",
+        "verified": false
       },
       {
         "name": "getNotificationTopics",
         "kind": "function",
         "jsdoc": "/** List the available notification topics (id + displayName for labels) —\n *  GET /notifications/v1/preferences/topics. */",
-        "decl": "export function getNotificationTopics(): Promise<GetNotificationTopicsResponse>;"
+        "decl": "export function getNotificationTopics(): Promise<GetNotificationTopicsResponse>;",
+        "verified": false
       },
       {
         "name": "upsertMyNotificationPreferences",
         "kind": "function",
         "jsdoc": "/** Upsert one or more of the signed-in member's preferences —\n *  POST /notifications/v1/preferences-by-implicit-recipient, body\n *  { preferencesInfo }. Pass only the rows that changed. */",
-        "decl": "export function upsertMyNotificationPreferences(\n  preferencesInfo: PreferenceInfo[]\n): Promise<UpsertMyNotificationPreferencesResponse>;"
+        "decl": "export function upsertMyNotificationPreferences(\n  preferencesInfo: PreferenceInfo[]\n): Promise<UpsertMyNotificationPreferencesResponse>;",
+        "verified": false
       }
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.941.0",
+  "version": "0.943.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": [
@@ -64,5 +64,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "f6ef221b31d3e6cb04fc7f80011d74de1d766b5da1d85c61f7a68530"
+  "falconPackageHash": "20d4d02bfd992d1556a2c7e77e8eae63a7b4ec23e7c9e082ff43e951"
 }

package/templates/beauty-salon/tier5-src/wix-spaces-collections/index.ts

@@ -11,7 +11,12 @@ import {
 } from "@himalaya/wix-stores-collections";
 
 interface Row { id: string; name: string; subtitle: string }
-interface S { status: "loading" | "ready"; collections: Row[]; emptyText: string }
+interface S {
+  status: "loading" | "ready" | "error";
+  collections: Row[];
+  emptyText: string;
+  error: string;
+}
 
 function fromCategory(c: StoreCategory): Row {
   return { id: c.id || "", name: c.name || "Category", subtitle: categoryCount(c) };
@@ -23,26 +28,69 @@ function fromCollection(c: WixCollection): Row {
   return { id: cc.id || cc.name || "collection", name: cc.name || "Collection", subtitle: n != null ? `${n} ${n === 1 ? "product" : "products"}` : "" };
 }
 
-async function loadCollections(): Promise<Row[]> {
+type Loaded = { ok: true; rows: Row[] } | { ok: false; error: string };
+
+async function loadCollections(): Promise<Loaded> {
   try {
     const r = await queryStoreCategories(50);
-    const rows = (r.categories ?? []).map(fromCategory).filter((row) => row.id);
-    if (rows.length) return rows;
-  } catch { /* fall through to V1 */ }
+    // A V3 SUCCESS with zero rows is an empty catalogue, not a reason to try V1, and this is the
+    // line that matters. Written as `if (rows.length) return rows`, a modern (stores-v3) site
+    // that simply has no categories fell through to the V1 call — which `himi sdk
+    // wix-stores-collections` documents as answering HTTP 428 on exactly those sites — and the
+    // catch below turned that 428 into an empty list. The screen then told the visitor "No
+    // categories yet" over a dead endpoint.
+    //
+    // Only a V3 THROW earns the fallback, because a legacy V1-catalogue site is the single case
+    // the fallback exists for.
+    //
+    // WHAT IS ESTABLISHED vs WHAT IS ASSUMED, because the two are not the same here and a
+    // reviewer was right to ask. Established: V1-on-V3 answers HTTP 428 — `himi sdk
+    // wix-stores-collections` documents it and names the message. ASSUMED, and not yet
+    // verified against a live legacy site: that the reverse — the V3 Categories API, a separate
+    // app-namespaced service, called on a Catalog-V1 site — THROWS rather than answering
+    // `200 {}`. If it answers 200-empty, a legacy site stops reaching the fallback and shows
+    // "No categories yet" instead of its collections: the same wrong-empty-state this change
+    // fixes, moved to the other site type.
+    //
+    // It is left as a throw-only fallback deliberately, because the alternative is worse:
+    // falling back on a V3 empty result sends every modern site with a genuinely empty
+    // catalogue into the 428 path, and the catch below now surfaces that as "Couldn't load
+    // categories" over a catalogue that is simply empty. Confirm against a Catalog-V1 site
+    // before changing this; five templates carry this file.
+    return { ok: true, rows: (r.categories ?? []).map(fromCategory).filter((row) => row.id) };
+  } catch { /* V3 unavailable — a legacy V1 site is what the fallback is for */ }
   try {
-    const r = await queryCollections({ query: { paging: { limit: 50 } } } as never);
-    return (((r as unknown as { collections?: WixCollection[] }).collections) ?? []).map(fromCollection);
-  } catch {
-    return [];
+    // No `as never` here: `WixQueryCollectionsRequest.query` is `WixCollectionsQuery`, which
+    // declares `paging`, so this argument type-checks as written. Reach for a cast only when the
+    // types really cannot express the call — silencing them by habit hides the next real
+    // mismatch.
+    const r = await queryCollections({ query: { paging: { limit: 50 } } });
+    return { ok: true, rows: (((r as unknown as { collections?: WixCollection[] }).collections) ?? []).map(fromCollection) };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
   }
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("spacesCollections", {
-  state: { status: "loading", collections: [], emptyText: "" },
+  state: { status: "loading", collections: [], emptyText: "", error: "" },
   actions: {
     load: async () => {
-      const collections = await loadCollections();
-      return { status: "ready", collections, emptyText: collections.length ? "" : "No categories yet" };
+      const res = await loadCollections();
+      if (!res.ok) {
+        // `emptyText` carries the honest line as well as `error`, deliberately: this screen's
+        // descriptor binds only `emptyText`, so writing the failure there is what stops the
+        // visitor being told the catalogue is empty when the call actually failed. `status` and
+        // `error` are what an error-state binding and `himi test` read — bind them when you add
+        // a dedicated error view.
+        const line = "Couldn't load categories. Pull to refresh.";
+        return { status: "error", collections: [], emptyText: line, error: res.error };
+      }
+      return {
+        status: "ready",
+        collections: res.rows,
+        emptyText: res.rows.length ? "" : "No categories yet",
+        error: "",
+      };
     },
   },
 });