@wix/himalaya-cli 0.941.0 → 0.943.0

package/templates/portfolio-creative/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: "",
+      };
     },
   },
 });

package/templates/retail-store/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: "",
+      };
     },
   },
 });