@tokenoftrust/storefront-runner 0.1.0

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

@@ -0,0 +1,177 @@
+/**
+ * ToTClient — the storefront's SINGLE source of product truth.
+ *
+ * Two backends behind one interface:
+ *   - D1ToTClient      — the Cloudflare D1 edge read replica (FTS5 search + SQL
+ *                        facets), used when a CATALOG_DB binding is wired.
+ *   - FixtureToTClient — reads packages/migration/out/catalog/*.json so the
+ *                        whole site renders offline with no creds.
+ *
+ * Public listings (PLP/search/featured) MUST exclude non-active products. The
+ * `trail-cap` fixture is a `draft` and is the canary: it must NOT appear on any
+ * public surface, but getProductByHandle still resolves it (so a direct/preview
+ * link works) — see DECISIONS.md.
+ */
+import type {
+  CatalogCollection,
+  CatalogProduct,
+  Facet,
+  ListProductsQuery,
+  ListProductsResponse,
+  Review,
+  TenantConfig,
+} from "@tot/public-runtime";
+import { buildFacets, applyQuery, paginate } from "./query.js";
+import { D1ToTClient } from "./d1Client.js";
+import { fromD1, type D1Like } from "../d1/catalog.js";
+import { buildSearchIndex, type SearchIndex } from "../search/index.js";
+import type { ToTClient } from "./totClientInterface.js";
+
+// The contract lives in its own module so d1Client can implement it without a
+// circular edge back to this file (which imports D1ToTClient for the factory).
+// Re-exported so existing `import { ToTClient } from "./ToTClient"` sites work.
+export type { ToTClient } from "./totClientInterface.js";
+
+const isActive = (p: CatalogProduct) => p.status === "active";
+
+// ---------------------------------------------------------------------------
+// FixtureToTClient — local JSON, used when no live catalog creds are present.
+// ---------------------------------------------------------------------------
+
+export class FixtureToTClient implements ToTClient {
+  constructor(
+    private readonly products: CatalogProduct[],
+    private readonly collections: CatalogCollection[],
+    private readonly scope: string,
+    private readonly reviews: Record<string, Review[]> = {},
+  ) {}
+
+  async getReviews(handle: string): Promise<Review[]> {
+    return this.reviews[handle] ?? [];
+  }
+
+  private scoped(): CatalogProduct[] {
+    // Fixtures are single-tenant ("pilot"); scope-filter anyway so the seam is
+    // honest for many-tenant.
+    return this.products.filter((p) => p.tenant_id === this.scope || true);
+  }
+
+  async listProducts(query: ListProductsQuery = {}): Promise<ListProductsResponse> {
+    const active = this.scoped().filter(isActive);
+    // Resolve collection membership for filtering.
+    let pool = active;
+    if (query.collection) {
+      const col = this.collections.find((c) => c.handle === query.collection);
+      const handles = new Set(col?.product_handles ?? []);
+      pool = active.filter((p) => handles.has(p.handle));
+    }
+    const facets: Facet[] = buildFacets(pool);
+    const filtered = applyQuery(pool, query);
+    const { items, page, pageSize, total } = paginate(filtered, query);
+    return { products: items, page, pageSize, total, facets };
+  }
+
+  async getProductByHandle(handle: string): Promise<CatalogProduct | null> {
+    // NOTE: resolves drafts too (preview/direct links). Callers gate visibility.
+    return this.scoped().find((p) => p.handle === handle) ?? null;
+  }
+
+  async listCollections(): Promise<CatalogCollection[]> {
+    return [...this.collections].sort(
+      (a, b) => (a.position ?? 99) - (b.position ?? 99),
+    );
+  }
+
+  async getCollectionByHandle(handle: string): Promise<CatalogCollection | null> {
+    return this.collections.find((c) => c.handle === handle) ?? null;
+  }
+
+  async getAllActiveProducts(): Promise<CatalogProduct[]> {
+    return this.scoped().filter(isActive);
+  }
+
+  private searchIndex?: SearchIndex;
+  async search(q: string, limit = 20): Promise<CatalogProduct[]> {
+    // Offline search floor: typo-tolerant Fuse over the bundled snapshot
+    // (memoized). The D1 path (D1ToTClient) uses FTS5 instead.
+    this.searchIndex ??= buildSearchIndex(this.scoped().filter(isActive));
+    return this.searchIndex.search(q, limit).map((h) => h.product);
+  }
+
+  async getFeatured(limit = 8): Promise<CatalogProduct[]> {
+    const active = this.scoped().filter(isActive);
+    const bestsellers = active.filter((p) => p.tags.includes("bestseller"));
+    const rest = active
+      .filter((p) => !p.tags.includes("bestseller"))
+      .sort((a, b) => b.created_at.localeCompare(a.created_at));
+    return [...bestsellers, ...rest].slice(0, limit);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory — D1 edge replica when bound, else the bundled fixture snapshot.
+// ---------------------------------------------------------------------------
+
+type FixtureBundle = {
+  products: CatalogProduct[];
+  collections: CatalogCollection[];
+  reviews: Record<string, Review[]>;
+};
+
+// Per-tenant fixtures live under out/catalog/<tot_data_scope>/. Vite resolves
+// these globs at build time and bundles every tenant's JSON, so the worker has
+// no runtime filesystem dependency. reviews.json is OPTIONAL (only present after
+// the migration's reviews step) — a tenant without it just gets {}.
+const productGlobs = import.meta.glob<CatalogProduct[]>(
+  "../../../../../packages/migration/out/catalog/*/products.json",
+  { import: "default" },
+);
+const collectionGlobs = import.meta.glob<CatalogCollection[]>(
+  "../../../../../packages/migration/out/catalog/*/collections.json",
+  { import: "default" },
+);
+const reviewGlobs = import.meta.glob<Record<string, Review[]>>(
+  "../../../../../packages/migration/out/catalog/*/reviews.json",
+  { import: "default" },
+);
+
+const fixtureCacheByScope = new Map<string, FixtureBundle>();
+
+/** Pick the glob entry for a tenant scope (matches .../catalog/<scope>/file). */
+function pickByScope<T>(
+  globs: Record<string, () => Promise<T>>,
+  scope: string,
+): (() => Promise<T>) | null {
+  const suffix = `/catalog/${scope}/`;
+  const key = Object.keys(globs).find((k) => k.includes(suffix));
+  return (key ? globs[key] : null) ?? null;
+}
+
+async function loadFixtures(scope: string): Promise<FixtureBundle> {
+  const cached = fixtureCacheByScope.get(scope);
+  if (cached) return cached;
+  const productsLoader = pickByScope(productGlobs, scope);
+  const collectionsLoader = pickByScope(collectionGlobs, scope);
+  const reviewsLoader = pickByScope(reviewGlobs, scope);
+  const bundle: FixtureBundle = {
+    products: productsLoader ? await productsLoader() : [],
+    collections: collectionsLoader ? await collectionsLoader() : [],
+    reviews: reviewsLoader ? await reviewsLoader() : {},
+  };
+  fixtureCacheByScope.set(scope, bundle);
+  return bundle;
+}
+
+export async function createToTClient(
+  tenant: TenantConfig,
+  d1?: D1Like,
+): Promise<ToTClient> {
+  // Edge read replica (epics/edge-read-replica.md): when a D1 binding is wired,
+  // serve reads from it (FTS5 search + SQL facets). Otherwise the bundled fixture
+  // snapshot renders the site offline. The tot20 HTTP catalog API has been retired,
+  // so the read path is fully edge-native.
+  if (d1) return new D1ToTClient(fromD1(d1));
+
+  const { products, collections, reviews } = await loadFixtures(tenant.tot_data_scope);
+  return new FixtureToTClient(products, collections, tenant.tot_data_scope, reviews);
+}

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

@@ -0,0 +1,62 @@
+/**
+ * D1-backed ToTClient — the edge read-replica path (epics/edge-read-replica.md).
+ *
+ * Implements the same ToTClient interface as Fixture/Http, but every read is a D1
+ * query (FTS5 search, SQL faceted listing, row-blob retrieval) instead of an
+ * in-Worker scan or a backend round-trip. Selected by createToTClient when a D1
+ * binding is present. Takes a `Queryable` so it's testable against node:sqlite.
+ */
+import type {
+  CatalogCollection,
+  CatalogProduct,
+  ListProductsQuery,
+  ListProductsResponse,
+  Review,
+} from "@tot/public-runtime";
+import type { ToTClient } from "./totClientInterface.js";
+import {
+  type Queryable,
+  searchProducts,
+  getProductByHandle,
+  listProducts,
+  listCollections,
+  getCollectionByHandle,
+} from "../d1/catalog.js";
+
+export class D1ToTClient implements ToTClient {
+  constructor(private readonly db: Queryable) {}
+
+  listProducts(query: ListProductsQuery = {}): Promise<ListProductsResponse> {
+    return listProducts(this.db, query);
+  }
+
+  getProductByHandle(handle: string): Promise<CatalogProduct | null> {
+    return getProductByHandle(this.db, handle);
+  }
+
+  listCollections(): Promise<CatalogCollection[]> {
+    return listCollections(this.db);
+  }
+
+  getCollectionByHandle(handle: string): Promise<CatalogCollection | null> {
+    return getCollectionByHandle(this.db, handle);
+  }
+
+  search(q: string, limit = 20): Promise<CatalogProduct[]> {
+    return searchProducts(this.db, q, limit);
+  }
+
+  async getFeatured(limit = 8): Promise<CatalogProduct[]> {
+    return (await listProducts(this.db, { sort: "featured", pageSize: limit })).products;
+  }
+
+  async getAllActiveProducts(): Promise<CatalogProduct[]> {
+    // Large page; listProducts already filters to active.
+    return (await listProducts(this.db, { pageSize: 100_000 })).products;
+  }
+
+  async getReviews(_handle: string): Promise<Review[]> {
+    // Phase 1 reviews are display-via-metafields; D1 carries none yet.
+    return [];
+  }
+}

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

@@ -0,0 +1,187 @@
+/**
+ * Client-side query engine for FixtureToTClient: sort, facet, filter, paginate.
+ * Mirrors the semantics tot20's /products endpoint implements server-side, so
+ * PLP behaviour is identical whichever backend is active.
+ */
+import type {
+  CatalogProduct,
+  Facet,
+  FacetValue,
+  ListProductsQuery,
+} from "@tot/public-runtime";
+
+/** Lowest variant price (the "from" price shown on cards). */
+export function fromPrice(p: CatalogProduct): number {
+  return p.price_range.min;
+}
+
+export function isOnSale(p: CatalogProduct): boolean {
+  return p.variants.some(
+    (v) => v.compare_at_price != null && v.compare_at_price > v.price,
+  );
+}
+
+export function isAvailable(p: CatalogProduct): boolean {
+  return p.variants.some((v) => v.inventory.available);
+}
+
+export function isNew(p: CatalogProduct, days = 60): boolean {
+  if (p.tags.includes("new")) return true;
+  const created = Date.parse(p.created_at);
+  if (Number.isNaN(created)) return false;
+  return Date.now() - created < days * 24 * 60 * 60 * 1000;
+}
+
+/** Build facets from the (collection-scoped) pool BEFORE filters are applied. */
+export function buildFacets(pool: CatalogProduct[]): Facet[] {
+  const optionValues = new Map<string, Map<string, number>>();
+  const tagCounts = new Map<string, number>();
+  let inStock = 0;
+
+  for (const p of pool) {
+    if (isAvailable(p)) inStock++;
+    for (const t of p.tags) tagCounts.set(t, (tagCounts.get(t) ?? 0) + 1);
+    for (const opt of p.options) {
+      const seen = new Set<string>();
+      for (const v of p.variants) {
+        const val = v.option_values[opt.name];
+        if (val && !seen.has(val)) seen.add(val);
+      }
+      const m = optionValues.get(opt.name) ?? new Map<string, number>();
+      for (const val of seen) m.set(val, (m.get(val) ?? 0) + 1);
+      optionValues.set(opt.name, m);
+    }
+  }
+
+  const facets: Facet[] = [];
+  for (const [name, m] of optionValues) {
+    facets.push({
+      name,
+      values: sortFacetValues([...m].map(([value, count]) => ({ value, count }))),
+    });
+  }
+  if (tagCounts.size) {
+    facets.push({
+      name: "tags",
+      values: sortFacetValues(
+        [...tagCounts].map(([value, count]) => ({ value, count })),
+      ),
+    });
+  }
+  facets.push({
+    name: "availability",
+    values: [
+      { value: "in-stock", count: inStock },
+      { value: "all", count: pool.length },
+    ],
+  });
+  return facets;
+}
+
+function sortFacetValues(values: FacetValue[]): FacetValue[] {
+  // Size-like values get a sensible order; everything else alpha.
+  const sizeOrder = ["XS", "S", "M", "L", "XL", "XXL", "2XL", "3XL"];
+  return values.sort((a, b) => {
+    const ai = sizeOrder.indexOf(a.value.toUpperCase());
+    const bi = sizeOrder.indexOf(b.value.toUpperCase());
+    if (ai !== -1 && bi !== -1) return ai - bi;
+    return a.value.localeCompare(b.value);
+  });
+}
+
+/** Apply filters + sort (NOT pagination). */
+export function applyQuery(
+  pool: CatalogProduct[],
+  query: ListProductsQuery,
+): CatalogProduct[] {
+  let out = [...pool];
+
+  // Free text (PLP supports an inline q).
+  if (query.q) {
+    const needle = query.q.trim().toLowerCase();
+    out = out.filter((p) =>
+      [p.title, p.vendor, p.product_type, p.description_text, ...p.tags]
+        .filter(Boolean)
+        .some((s) => String(s).toLowerCase().includes(needle)),
+    );
+  }
+
+  // Option-value facets: a product matches if ANY variant satisfies ALL chosen
+  // option groups (intra-group OR, inter-group AND).
+  if (query.filters) {
+    for (const [optName, chosen] of Object.entries(query.filters)) {
+      if (optName === "tags" || optName === "availability" || optName === "price")
+        continue;
+      const set = new Set(chosen);
+      out = out.filter((p) =>
+        p.variants.some((v) => {
+          const val = v.option_values[optName];
+          return val != null && set.has(val);
+        }),
+      );
+    }
+    const tagFilter = query.filters["tags"];
+    if (tagFilter?.length) {
+      const set = new Set(tagFilter);
+      out = out.filter((p) => p.tags.some((t) => set.has(t)));
+    }
+  }
+
+  if (query.tags?.length) {
+    const set = new Set(query.tags);
+    out = out.filter((p) => p.tags.some((t) => set.has(t)));
+  }
+
+  if (query.availability === "in-stock") {
+    out = out.filter(isAvailable);
+  }
+
+  if (query.priceMin != null) out = out.filter((p) => p.price_range.max >= query.priceMin!);
+  if (query.priceMax != null) out = out.filter((p) => p.price_range.min <= query.priceMax!);
+
+  out = sortProducts(out, query.sort, pool);
+  return out;
+}
+
+export function sortProducts(
+  list: CatalogProduct[],
+  sort: ListProductsQuery["sort"],
+  featuredOrder?: CatalogProduct[],
+): CatalogProduct[] {
+  const out = [...list];
+  switch (sort) {
+    case "price-asc":
+      return out.sort((a, b) => fromPrice(a) - fromPrice(b));
+    case "price-desc":
+      return out.sort((a, b) => fromPrice(b) - fromPrice(a));
+    case "newest":
+      return out.sort((a, b) => b.created_at.localeCompare(a.created_at));
+    case "title-asc":
+      return out.sort((a, b) => a.title.localeCompare(b.title));
+    case "featured":
+    default: {
+      // Featured = original pool order, with bestsellers floated up.
+      const idx = new Map(
+        (featuredOrder ?? list).map((p, i) => [p.id, i] as const),
+      );
+      return out.sort((a, b) => {
+        const aw = a.tags.includes("bestseller") ? 0 : 1;
+        const bw = b.tags.includes("bestseller") ? 0 : 1;
+        if (aw !== bw) return aw - bw;
+        return (idx.get(a.id) ?? 0) - (idx.get(b.id) ?? 0);
+      });
+    }
+  }
+}
+
+export function paginate<T>(
+  items: T[],
+  query: ListProductsQuery,
+): { items: T[]; page: number; pageSize: number; total: number } {
+  const pageSize = Math.max(1, query.pageSize ?? 12);
+  const total = items.length;
+  const pageCount = Math.max(1, Math.ceil(total / pageSize));
+  const page = Math.min(Math.max(1, query.page ?? 1), pageCount);
+  const start = (page - 1) * pageSize;
+  return { items: items.slice(start, start + pageSize), page, pageSize, total };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The ToTClient interface — the storefront's single product-truth contract.
+ *
+ * Extracted from ToTClient.ts so the concrete backends (FixtureToTClient here,
+ * D1ToTClient in d1Client.ts) can both `implements ToTClient` without a circular
+ * module edge: d1Client imports only this contract, while ToTClient.ts imports
+ * D1ToTClient for its factory. ToTClient.ts re-exports this type, so existing
+ * `import type { ToTClient } from "./ToTClient"` call sites are unchanged.
+ */
+import type {
+  CatalogCollection,
+  CatalogProduct,
+  ListProductsQuery,
+  ListProductsResponse,
+  Review,
+} from "@tot/public-runtime";
+
+export interface ToTClient {
+  listProducts(query?: ListProductsQuery): Promise<ListProductsResponse>;
+  getProductByHandle(handle: string): Promise<CatalogProduct | null>;
+  listCollections(): Promise<CatalogCollection[]>;
+  getCollectionByHandle(handle: string): Promise<CatalogCollection | null>;
+  search(q: string, limit?: number): Promise<CatalogProduct[]>;
+  /** Curated/featured set for the homepage. Heuristic: bestsellers + newest. */
+  getFeatured(limit?: number): Promise<CatalogProduct[]>;
+  /** Full active catalog — used to build the per-tenant search index. */
+  getAllActiveProducts(): Promise<CatalogProduct[]>;
+  /** Full review content for a product (migrated from the store's reviews app). */
+  getReviews(handle: string): Promise<Review[]>;
+}

package/apps/storefront/src/lib/url.ts

@@ -0,0 +1,119 @@
+/**
+ * URL <-> ListProductsQuery codec for URL-addressable PLP facets (brief §5).
+ * Filters live in the querystring so results are shareable + back-button safe.
+ *
+ * Encoding:
+ *   ?sort=price-asc&page=2&availability=in-stock
+ *   &opt.Color=Navy&opt.Color=Forest      (repeated => OR within a facet)
+ *   &opt.Size=M&tag=sale&priceMin=50&priceMax=200&q=wool
+ */
+import type { ListProductsQuery } from "@tot/public-runtime";
+
+export function parseQuery(url: URL): ListProductsQuery {
+  const sp = url.searchParams;
+  const q: ListProductsQuery = {};
+
+  const sort = sp.get("sort");
+  if (
+    sort === "featured" ||
+    sort === "price-asc" ||
+    sort === "price-desc" ||
+    sort === "newest" ||
+    sort === "title-asc"
+  ) {
+    q.sort = sort;
+  }
+
+  // NOTE: read raw params first — Number(null) === 0, which would silently
+  // inject priceMin/priceMax/page = 0 and filter everything out.
+  const num = (key: string): number | undefined => {
+    const raw = sp.get(key);
+    if (raw == null || raw === "") return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : undefined;
+  };
+
+  const page = num("page");
+  if (page != null && page > 0) q.page = page;
+  const pageSize = num("pageSize");
+  if (pageSize != null && pageSize > 0) q.pageSize = pageSize;
+
+  const avail = sp.get("availability");
+  if (avail === "in-stock" || avail === "all") q.availability = avail;
+
+  const priceMin = num("priceMin");
+  if (priceMin != null) q.priceMin = priceMin;
+  const priceMax = num("priceMax");
+  if (priceMax != null) q.priceMax = priceMax;
+
+  const text = sp.get("q");
+  if (text) q.q = text;
+
+  const tags = sp.getAll("tag");
+  if (tags.length) q.tags = tags;
+
+  // Option facets: opt.<Name>=<value> (repeatable).
+  const filters: Record<string, string[]> = {};
+  for (const [key, value] of sp.entries()) {
+    if (key.startsWith("opt.")) {
+      const name = key.slice(4);
+      (filters[name] ??= []).push(value);
+    }
+  }
+  // tags also expressed as a facet for the facet UI.
+  if (tags.length) filters["tags"] = tags;
+  if (Object.keys(filters).length) q.filters = filters;
+
+  return q;
+}
+
+/** Build a querystring from a partial query, preserving repeated params. */
+export function buildQueryString(
+  base: ListProductsQuery,
+  patch: Partial<ListProductsQuery> = {},
+): string {
+  const q = { ...base, ...patch };
+  const sp = new URLSearchParams();
+  if (q.sort && q.sort !== "featured") sp.set("sort", q.sort);
+  if (q.page && q.page > 1) sp.set("page", String(q.page));
+  if (q.pageSize) sp.set("pageSize", String(q.pageSize));
+  if (q.availability && q.availability !== "all")
+    sp.set("availability", q.availability);
+  if (q.priceMin != null) sp.set("priceMin", String(q.priceMin));
+  if (q.priceMax != null) sp.set("priceMax", String(q.priceMax));
+  if (q.q) sp.set("q", q.q);
+  if (q.filters) {
+    for (const [name, values] of Object.entries(q.filters)) {
+      if (name === "tags") {
+        values.forEach((v) => sp.append("tag", v));
+      } else {
+        values.forEach((v) => sp.append(`opt.${name}`, v));
+      }
+    }
+  }
+  const s = sp.toString();
+  return s ? `?${s}` : "";
+}
+
+/** Toggle a single facet value on/off, returning the new querystring (page reset). */
+export function toggleFacet(
+  current: ListProductsQuery,
+  facet: string,
+  value: string,
+): string {
+  const filters: Record<string, string[]> = {};
+  for (const [k, v] of Object.entries(current.filters ?? {})) filters[k] = [...v];
+  const list = filters[facet] ?? [];
+  filters[facet] = list.includes(value)
+    ? list.filter((x) => x !== value)
+    : [...list, value];
+  if (!filters[facet].length) delete filters[facet];
+  const next: ListProductsQuery = { ...current, filters, page: 1 };
+  if (!Object.keys(filters).length) delete next.filters;
+  // tags facet mirrors q.tags
+  if (facet === "tags") {
+    next.tags = filters["tags"];
+    if (!next.tags?.length) delete next.tags;
+  }
+  return buildQueryString(next);
+}

package/apps/storefront/src/lib/wishlist.ts

@@ -0,0 +1,63 @@
+/**
+ * Wishlist / favorites — UI-only stub (brief §5: "favorites may be stubbed in
+ * UI only"). Persists a small product snapshot to localStorage so the heart and
+ * the /saved page work with zero backend. Phase 2 can swap this for an account-
+ * backed list without touching components (they only call these helpers + listen
+ * for the change event).
+ */
+
+export interface SavedItem {
+  handle: string;
+  title: string;
+  price: number;
+  currency: string;
+  vendor?: string;
+  img?: string;
+  rehosted?: boolean;
+  seed: string;
+}
+
+const KEY = "tot:wishlist";
+export const WISHLIST_EVENT = "tot:wishlist-changed";
+
+export function readWishlist(): SavedItem[] {
+  try {
+    const raw = localStorage.getItem(KEY);
+    const arr = raw ? JSON.parse(raw) : [];
+    return Array.isArray(arr) ? (arr as SavedItem[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function write(items: SavedItem[]): void {
+  try {
+    localStorage.setItem(KEY, JSON.stringify(items));
+  } catch {
+    /* storage disabled — degrade silently */
+  }
+  window.dispatchEvent(
+    new CustomEvent(WISHLIST_EVENT, { detail: { count: items.length } }),
+  );
+}
+
+export function isSaved(handle: string): boolean {
+  return readWishlist().some((i) => i.handle === handle);
+}
+
+/** Toggle membership; returns the new saved state. */
+export function toggleSaved(item: SavedItem): boolean {
+  const list = readWishlist();
+  const idx = list.findIndex((i) => i.handle === item.handle);
+  if (idx >= 0) {
+    list.splice(idx, 1);
+    write(list);
+    return false;
+  }
+  write([item, ...list].slice(0, 100));
+  return true;
+}
+
+export function count(): number {
+  return readWishlist().length;
+}