@tokenoftrust/storefront-runner 2.4.11 → 2.4.12

package/agency-kit/tools/lib/catalog-model/model.mjs

@@ -20,7 +20,9 @@ export const CATALOG_MODEL = {
   ProductStatus: { alias: '"active" | "draft" | "archived"' },
   ProductVisibility: { alias: '"public" | "unlisted" | "hidden"' },
   Currency: { alias: "string" },
-  SourcePlatform: { alias: '"shopify" | "bigcommerce" | "directory" | "csv" | "manual" | "synthesized"' },
+  SourcePlatform: {
+    alias: '"shopify" | "bigcommerce" | "directory" | "csv" | "manual" | "synthesized" | "tot-catalog"',
+  },
   SourceRef: {
     fields: { platform: "SourcePlatform", source_id: "string", "source_handle?": "string" },
   },
@@ -70,6 +72,28 @@ export const CATALOG_MODEL = {
   InventoryState: {
     fields: { "quantity?": "number", "policy?": "string", available: "boolean" },
   },
+  CatalogFactState: { alias: '"known" | "unknown" | "invalid" | "conflict" | "not_applicable"' },
+  CatalogFact: {
+    fields: {
+      key: "string",
+      label: "string",
+      state: "CatalogFactState",
+      "value?": "string | number | boolean",
+      "unit?": "string",
+    },
+  },
+  CatalogLink: {
+    fields: {
+      item_id: "string",
+      accepted_revision_id: "string",
+      "group_id?": "string",
+      "market?": "string",
+      "locale?": "string",
+      accepted_at: "string",
+      facts: "CatalogFact[]",
+    },
+  },
+  CatalogOverrideField: { alias: '"title" | "description_html" | "images" | "vendor" | "product_type"' },
   CatalogVariant: {
     fields: {
       tenant_id: "string",
@@ -93,6 +117,7 @@ export const CATALOG_MODEL = {
       "depth?": "number",
       position: "number",
       "image_id?": "string",
+      "catalog_link?": "CatalogLink",
     },
   },
   CatalogProduct: {
@@ -121,6 +146,7 @@ export const CATALOG_MODEL = {
       updated_at: "string",
       migrated_at: "string",
       source_checksum: "string",
+      "catalog_overrides?": "CatalogOverrideField[]",
     },
   },
   CatalogCollection: {

package/apps/storefront/package.json

@@ -35,7 +35,8 @@
     "jose": "^6.2.3",
     "parse5": "^7.2.1",
     "preact": "^10.29.2",
-    "tailwindcss": "^4.3.1"
+    "tailwindcss": "^4.3.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.4",

package/apps/storefront/src/lib/admin/productsTabClient.ts

@@ -0,0 +1,156 @@
+/**
+ * Admin Products tab client: filtering, product selection, and the catalog-update review — check a
+ * listed product's packages for newer catalog revisions, show what accepting changes, and accept
+ * explicitly as a draft change. Catalog text is set as text, never parsed as HTML.
+ */
+
+interface UpdatePlanProduct {
+  handle: string;
+  baseRevision: string;
+  fieldChanges: Array<{ field: string; applied: boolean }>;
+}
+
+interface UpdatesResponse {
+  ok: boolean;
+  message?: string;
+  updates: Array<{ title: string; acceptedRevisionId: string; latestRevisionId: string }>;
+  unchecked?: string[];
+  request?: Record<string, unknown>;
+  plan: { products: UpdatePlanProduct[] } | null;
+  planFailure?: { message?: string; pinFailures?: Array<{ message: string }> };
+}
+
+const FIELD_LABEL: Record<string, string> = {
+  title: "Title",
+  description_html: "Description",
+  images: "Photos",
+  vendor: "Brand",
+  product_type: "Product type",
+};
+
+function el(tag: string, attrs: Record<string, string> = {}, ...children: Array<Node | string>): HTMLElement {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v);
+  node.append(...children);
+  return node;
+}
+
+export function initProductsTab(root: HTMLElement): void {
+  const api = root.dataset.productsApi ?? "";
+  const statusSelect = root.querySelector<HTMLSelectElement>("[data-products-status-select]");
+  const listingSelect = root.querySelector<HTMLSelectElement>("[data-products-listing-select]");
+  const searchInput = root.querySelector<HTMLInputElement>("[data-products-search]");
+  const rows = [...root.querySelectorAll<HTMLElement>("[data-products-row]")];
+  const emptyState = root.querySelector<HTMLElement>("[data-products-empty]");
+  const records = [...root.querySelectorAll<HTMLElement>("[data-products-detail-record]")];
+
+  const applyFilters = () => {
+    const status = statusSelect?.value ?? "";
+    const listing = listingSelect?.value ?? "";
+    const term = (searchInput?.value ?? "").trim().toLowerCase();
+    let visible = 0;
+    for (const row of rows) {
+      const show =
+        (!status || row.dataset.status === status) &&
+        (!listing || row.dataset.listing === listing) &&
+        (!term || (row.dataset.searchHaystack ?? "").includes(term));
+      row.hidden = !show;
+      if (show) visible += 1;
+    }
+    if (emptyState) emptyState.hidden = visible > 0;
+  };
+
+  const select = (handle: string) => {
+    for (const row of rows) row.classList.toggle("selected", row.dataset.productId === handle);
+    for (const r of records) r.hidden = r.dataset.productsDetailRecord !== handle;
+  };
+
+  statusSelect?.addEventListener("change", applyFilters);
+  listingSelect?.addEventListener("change", applyFilters);
+  searchInput?.addEventListener("input", applyFilters);
+  for (const row of rows) row.addEventListener("click", () => row.dataset.productId && select(row.dataset.productId));
+
+  async function check(handle: string, box: HTMLElement, button: HTMLButtonElement): Promise<void> {
+    button.disabled = true;
+    box.replaceChildren(el("p", { class: "subtle" }, "Checking the ToT catalog…"));
+    try {
+      const res = await fetch(`${api}?updates=${encodeURIComponent(handle)}`, { headers: { accept: "application/json" } });
+      const body = (await res.json()) as UpdatesResponse;
+      if (!res.ok || !body.ok) {
+        box.replaceChildren(el("p", { class: "notice-error", role: "alert" }, body.message ?? `Catalog check failed (HTTP ${res.status}).`));
+        return;
+      }
+      const nodes: Node[] = [];
+      if (body.unchecked?.length) {
+        nodes.push(el("p", { class: "subtle" }, `${body.unchecked.length} listed package(s) could not be checked against the catalog's latest revision.`));
+      }
+      if (body.updates.length === 0) {
+        nodes.push(el("p", {}, "Every listed package is at the catalog's latest revision."));
+        box.replaceChildren(...nodes);
+        return;
+      }
+      nodes.push(
+        el("strong", {}, `${body.updates.length} package(s) have a newer catalog revision`),
+        el(
+          "ul",
+          { class: "update-list" },
+          ...body.updates.map((u) => el("li", {}, `${u.title}: revision ${u.acceptedRevisionId.slice(0, 8)} → ${u.latestRevisionId.slice(0, 8)}`)),
+        ),
+      );
+      const plan = body.plan;
+      if (!plan || !body.request) {
+        const reason = body.planFailure?.message ?? body.planFailure?.pinFailures?.map((f) => f.message).join("; ");
+        nodes.push(el("p", { class: "notice-error", role: "alert" }, `The update cannot be prepared: ${reason || "unknown reason"}.`));
+        box.replaceChildren(...nodes);
+        return;
+      }
+      const product = plan.products[0];
+      if (product?.fieldChanges.length) {
+        nodes.push(
+          el("p", { class: "eyebrow" }, "Product fields"),
+          el(
+            "ul",
+            { class: "update-list" },
+            ...product.fieldChanges.map((c) => el("li", {}, `${FIELD_LABEL[c.field] ?? c.field}: ${c.applied ? "takes the catalog's new value" : "keeps your value (catalog value differs)"}`)),
+          ),
+        );
+      }
+      nodes.push(el("p", { class: "subtle" }, "Your SKUs, prices and the fields you set are kept. Accepting opens a draft change; nothing is published."));
+      const accept = el("button", { type: "button", class: "btn primary" }, "Accept update as a draft") as HTMLButtonElement;
+      accept.addEventListener("click", async () => {
+        accept.disabled = true;
+        const expected = Object.fromEntries(plan.products.map((p) => [p.handle, p.baseRevision]));
+        const saveRes = await fetch(api, {
+          method: "POST",
+          headers: { "content-type": "application/json", accept: "application/json" },
+          body: JSON.stringify({ action: "save", ...body.request, expected }),
+        });
+        const saved = (await saveRes.json()) as { ok: boolean; code?: string; message?: string; error?: string; products?: Array<{ status: string }> };
+        if (!saveRes.ok || !saved.ok) {
+          const msg =
+            saved.code === "revision_conflict"
+              ? "This product changed since the update was prepared. Check again to review the latest version."
+              : saved.error ?? saved.message ?? `Saving failed (HTTP ${saveRes.status}).`;
+          box.append(el("p", { class: "notice-error", role: "alert" }, msg));
+          accept.disabled = false;
+          return;
+        }
+        box.append(el("p", {}, saved.products?.[0]?.status === "unchanged" ? "Already up to date." : "Saved as a draft change. Preview and publish it from the Publish tab."));
+      });
+      nodes.push(accept);
+      box.replaceChildren(...nodes);
+    } catch {
+      box.replaceChildren(el("p", { class: "notice-error", role: "alert" }, "The catalog check could not reach the server."));
+    } finally {
+      button.disabled = false;
+    }
+  }
+
+  for (const button of root.querySelectorAll<HTMLButtonElement>("[data-catalog-check]")) {
+    const handle = button.dataset.catalogCheck ?? "";
+    const box = button.parentElement?.querySelector<HTMLElement>("[data-catalog-result]");
+    if (box) button.addEventListener("click", () => void check(handle, box, button));
+  }
+
+  applyFilters();
+}

package/apps/storefront/src/lib/admin/services/catalogProducts.ts

@@ -0,0 +1,32 @@
+/**
+ * The admin Products tab's source: the store's own catalog files (ADR 0033's system of record).
+ * A store still served from the platform's grandfathered snapshot is shown from it, read-only,
+ * because its first catalog file would replace that snapshot on every surface.
+ */
+import type { CatalogProduct, TenantConfig } from "@tot/public-runtime";
+import { CatalogFileError } from "@tot/public-runtime/catalog-files";
+import { readGrandfatheredSnapshot } from "@/lib/tot/ToTClient";
+import { readTenantCatalogFiles, type CatalogArtifactSource } from "@/lib/tot/tenantCatalog";
+
+export type CatalogOrigin = "files" | "snapshot" | "none";
+
+export type AdminCatalog =
+  | { ok: true; origin: CatalogOrigin; products: CatalogProduct[] }
+  | { ok: false; message: string; failures?: ReadonlyArray<{ path: string; issues: readonly string[] }> };
+
+export async function catalogOrigin(tenant: TenantConfig, content: CatalogArtifactSource | undefined): Promise<CatalogOrigin> {
+  if (await readTenantCatalogFiles(tenant, content)) return "files";
+  return (await readGrandfatheredSnapshot(tenant.tot_data_scope)) ? "snapshot" : "none";
+}
+
+export async function loadAdminCatalog(tenant: TenantConfig, content: CatalogArtifactSource | undefined): Promise<AdminCatalog> {
+  try {
+    const files = await readTenantCatalogFiles(tenant, content);
+    if (files) return { ok: true, origin: "files", products: files.products };
+    const snapshot = await readGrandfatheredSnapshot(tenant.tot_data_scope);
+    return snapshot ? { ok: true, origin: "snapshot", products: snapshot } : { ok: true, origin: "none", products: [] };
+  } catch (error) {
+    if (error instanceof CatalogFileError) return { ok: false, message: error.message, failures: error.failures };
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+}

package/apps/storefront/src/lib/admin/viewmodels/catalogProducts.ts

@@ -0,0 +1,140 @@
+/**
+ * The admin Products tab's view of the store's real catalog. Two readiness measures stay separate:
+ * listing readiness (can this product be listed: active, photographed, every variant priced and
+ * SKU'd) and catalog completeness (how many accepted catalog facts are known). Tax readiness is
+ * neither, and is not judged here.
+ */
+import type { CatalogFact, CatalogProduct } from "@tot/public-runtime";
+import type { AdminCatalog, CatalogOrigin } from "../services/catalogProducts";
+
+export interface ListingReadiness {
+  ready: boolean;
+  missing: string[];
+}
+
+export interface CatalogCompleteness {
+  linkedVariants: number;
+  /** Percent of applicable accepted facts that are known; null when nothing is catalog-linked. */
+  percent: number | null;
+  unresolved: number;
+}
+
+export interface CatalogVariantRow {
+  id: string;
+  title: string;
+  sku: string | null;
+  price: string;
+  linkedItemId: string | null;
+  acceptedRevisionId: string | null;
+  acceptedAt: string | null;
+  unresolvedFacts: Array<Pick<CatalogFact, "label" | "state">>;
+}
+
+export interface CatalogProductRow {
+  handle: string;
+  title: string;
+  productType: string;
+  vendor: string;
+  status: CatalogProduct["status"];
+  variantCount: number;
+  priceLabel: string;
+  imageUrl: string | null;
+  listing: ListingReadiness;
+  catalog: CatalogCompleteness;
+}
+
+export interface CatalogProductDetail extends CatalogProductRow {
+  variants: CatalogVariantRow[];
+  images: Array<{ url: string; alt: string; variantScoped: boolean }>;
+  overrides: string[];
+  collections: string[];
+}
+
+export type CatalogProductsViewModel =
+  | {
+      state: "ready" | "empty";
+      origin: CatalogOrigin;
+      rows: CatalogProductRow[];
+      detailsByHandle: Record<string, CatalogProductDetail>;
+    }
+  | { state: "error"; message: string; failures: ReadonlyArray<{ path: string; issues: readonly string[] }> };
+
+const UNRESOLVED = new Set<CatalogFact["state"]>(["unknown", "invalid", "conflict"]);
+
+function money(amount: number, currency: string, locale: string): string {
+  try {
+    return new Intl.NumberFormat(locale, { style: "currency", currency }).format(amount);
+  } catch {
+    return `${amount.toFixed(2)} ${currency}`;
+  }
+}
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+export function listingReadiness(product: CatalogProduct): ListingReadiness {
+  const missing: string[] = [];
+  if (product.status !== "active") missing.push(`Status is ${product.status}`);
+  if (!product.title.trim()) missing.push("No title");
+  if (product.images.length === 0) missing.push("No photo");
+  if (product.variants.length === 0) missing.push("No variants");
+  const noSku = product.variants.filter((v) => !v.sku?.trim()).length;
+  const noPrice = product.variants.filter((v) => !(v.price > 0)).length;
+  if (noSku) missing.push(`${plural(noSku, "variant")} without a SKU`);
+  if (noPrice) missing.push(`${plural(noPrice, "variant")} without a price`);
+  return { ready: missing.length === 0, missing };
+}
+
+export function catalogCompleteness(product: CatalogProduct): CatalogCompleteness {
+  const facts = product.variants.flatMap((v) => v.catalog_link?.facts ?? []);
+  const applicable = facts.filter((f) => f.state !== "not_applicable");
+  const linkedVariants = product.variants.filter((v) => v.catalog_link).length;
+  return {
+    linkedVariants,
+    percent: linkedVariants && applicable.length ? Math.round((100 * applicable.filter((f) => f.state === "known").length) / applicable.length) : linkedVariants ? 100 : null,
+    unresolved: facts.filter((f) => UNRESOLVED.has(f.state)).length,
+  };
+}
+
+export function toCatalogProductsViewModel(catalog: AdminCatalog, locale: string): CatalogProductsViewModel {
+  if (!catalog.ok) return { state: "error", message: catalog.message, failures: catalog.failures ?? [] };
+  const rows: CatalogProductRow[] = [];
+  const detailsByHandle: Record<string, CatalogProductDetail> = {};
+  const sorted = [...catalog.products].sort((a, b) => a.title.localeCompare(b.title));
+  for (const p of sorted) {
+    const { min, max, currency } = p.price_range;
+    const row: CatalogProductRow = {
+      handle: p.handle,
+      title: p.title,
+      productType: p.product_type ?? "",
+      vendor: p.vendor ?? "",
+      status: p.status,
+      variantCount: p.variants.length,
+      priceLabel: min === max ? money(min, currency, locale) : `${money(min, currency, locale)} – ${money(max, currency, locale)}`,
+      imageUrl: [...p.images].sort((a, b) => a.position - b.position)[0]?.url ?? null,
+      listing: listingReadiness(p),
+      catalog: catalogCompleteness(p),
+    };
+    rows.push(row);
+    detailsByHandle[p.handle] = {
+      ...row,
+      variants: [...p.variants]
+        .sort((a, b) => a.position - b.position)
+        .map((v) => ({
+          id: v.id,
+          title: v.title,
+          sku: v.sku?.trim() || null,
+          price: v.price > 0 ? money(v.price, v.currency, locale) : "—",
+          linkedItemId: v.catalog_link?.item_id ?? null,
+          acceptedRevisionId: v.catalog_link?.accepted_revision_id ?? null,
+          acceptedAt: v.catalog_link?.accepted_at ?? null,
+          unresolvedFacts: (v.catalog_link?.facts ?? []).filter((f) => UNRESOLVED.has(f.state)).map((f) => ({ label: f.label, state: f.state })),
+        })),
+      images: [...p.images]
+        .sort((a, b) => a.position - b.position)
+        .map((img) => ({ url: img.url, alt: img.alt ?? "", variantScoped: Boolean(img.variant_ids?.length) })),
+      overrides: p.catalog_overrides ?? [],
+      collections: p.collections,
+    };
+  }
+  return { state: rows.length ? "ready" : "empty", origin: catalog.origin, rows, detailsByHandle };
+}

package/apps/storefront/src/lib/tot/ToTClient.ts

@@ -167,6 +167,11 @@ async function loadFixtures(scope: string): Promise<FixtureBundle> {
   return bundle;
 }
 
+/** The grandfathered in-repo snapshot's products for a data scope, or null when it has none. */
+export async function readGrandfatheredSnapshot(scope: string): Promise<CatalogProduct[] | null> {
+  return pickByScope(productGlobs, scope) ? (await loadFixtures(scope)).products : null;
+}
+
 /**
  * Resolves its backend on the first read, so a page that never touches the catalog
  * (a blog post, an editorial page) never pays for — or fails on — reading it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.11",
+  "version": "2.4.12",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/product.ts

@@ -31,7 +31,8 @@ export type SourcePlatform =
   | "directory"
   | "csv"
   | "manual"
-  | "synthesized";
+  | "synthesized"
+  | "tot-catalog";
 
 export interface SourceRef {
   /** Origin platform (provenance only; not branched on at runtime). */
@@ -139,6 +140,39 @@ export interface InventoryState {
   available: boolean;
 }
 
+/** How a reviewed ToT catalog fact stood at the revision the merchant accepted. */
+export type CatalogFactState = "known" | "unknown" | "invalid" | "conflict" | "not_applicable";
+
+export interface CatalogFact {
+  /** The catalog's fact key, e.g. "nicotine_strength". */
+  key: string;
+  label: string;
+  state: CatalogFactState;
+  /** Present only when `state` is "known"; never a value inferred from an unknown fact. */
+  value?: string | number | boolean;
+  unit?: string;
+}
+
+/**
+ * The reviewed ToT catalog package a variant lists, pinned to the revision the merchant
+ * accepted. One variant lists exactly one packaged item. The accepted facts are stored here
+ * so the product previews and publishes with the catalog unavailable.
+ */
+export interface CatalogLink {
+  item_id: string;
+  accepted_revision_id: string;
+  /** The catalog's explicit canonical grouping; absent when the catalog declares none. */
+  group_id?: string;
+  market?: string;
+  locale?: string;
+  /** ISO 8601. */
+  accepted_at: string;
+  facts: CatalogFact[];
+}
+
+/** Product fields a merchant set away from the accepted catalog content. */
+export type CatalogOverrideField = "title" | "description_html" | "images" | "vendor" | "product_type";
+
 export interface CatalogVariant {
   tenant_id: string;
   id: string; // stable internal id (tenant-unique)
@@ -163,6 +197,8 @@ export interface CatalogVariant {
   position: number;
   /** CatalogImage.id of the variant's featured image, if any. */
   image_id?: string;
+  /** The catalog package this variant lists; absent for a merchant-authored variant. */
+  catalog_link?: CatalogLink;
 }
 
 export interface CatalogProduct {
@@ -200,6 +236,11 @@ export interface CatalogProduct {
   migrated_at: string; // ISO 8601
   /** Content hash for incremental sync / change detection. */
   source_checksum: string;
+  /**
+   * Fields the merchant changed from the accepted catalog content. Accepting a newer
+   * catalog revision never replaces them.
+   */
+  catalog_overrides?: CatalogOverrideField[];
 }
 
 /** Public listings and search include only visible, active products. */

package/pnpm-lock.runner.yaml

@@ -75,6 +75,9 @@ importers:
       tailwindcss:
         specifier: ^4.3.1
         version: 4.3.1
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
     devDependencies:
       '@astrojs/check':
         specifier: ^0.9.4