@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,91 @@
+/**
+ * Tenant routing resolution: Host first, then a `/<domain>/*` path-prefix
+ * fallback for hosts that don't resolve to a tenant on their own.
+ *
+ * Precedence (host-first — matches the prod contract where a custom hostname
+ * authoritatively owns a tenant; the path form is a DNS-free escape hatch for
+ * localhost/preview):
+ *
+ *   1. Host strictly claims a tenant         -> use it, no base path.
+ *   2. Host is unknown AND the first path
+ *      segment looks like a hostname that
+ *      strictly claims a tenant              -> use it; the segment becomes the
+ *                                               base path and is stripped from
+ *                                               the rendered route.
+ *   3. Otherwise                             -> registry default (resolveByHost).
+ *
+ * Example: on localhost (which claims no tenant), GET
+ *   /store2.tokenoftrust.com/products/foo
+ * resolves tenant "store2", basePath "/store2.tokenoftrust.com", and renders
+ * the route "/products/foo". A bare localhost/products falls through to the
+ * default tenant because "products" isn't a hostname.
+ */
+import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
+
+export interface TenantRouting {
+  tenant: TenantConfig | null;
+  /** "" when host-resolved; "/<domain>" when path-resolved. */
+  basePath: string;
+  /** Route to render with the tenant prefix stripped (leading slash, no query). */
+  renderPath: string;
+}
+
+/**
+ * A path segment is treated as a tenant-domain candidate only if it looks like
+ * a hostname (has a dot, no "@" or other path-ish junk). Real first segments
+ * — products, collections, saved, search — never contain a dot, so there is no
+ * collision with genuine routes.
+ */
+export function looksLikeHost(segment: string): boolean {
+  return (
+    segment.length > 0 &&
+    segment.includes(".") &&
+    !segment.startsWith(".") &&
+    !segment.endsWith(".") &&
+    !segment.includes("@") &&
+    !segment.includes(" ")
+  );
+}
+
+/** Normalize a path: always leading slash, never a trailing slash (except "/"). */
+function normalizePath(path: string): string {
+  const withSlash = path.startsWith("/") ? path : `/${path}`;
+  const trimmed = withSlash.replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed;
+}
+
+export async function resolveTenantRouting(
+  host: string,
+  pathname: string,
+  resolver: TenantResolver,
+): Promise<TenantRouting> {
+  // 1. Host wins when it explicitly owns a tenant.
+  const byHost = await resolver.resolveStrict(host);
+  if (byHost) {
+    return { tenant: byHost, basePath: "", renderPath: normalizePath(pathname) };
+  }
+
+  // 2. Unknown host -> try a /<domain>/* path prefix.
+  const segments = pathname.replace(/^\/+/, "").split("/");
+  const firstRaw = segments[0] ?? "";
+  let first = firstRaw;
+  try {
+    first = decodeURIComponent(firstRaw);
+  } catch {
+    /* leave as-is if it isn't valid percent-encoding */
+  }
+  if (looksLikeHost(first)) {
+    const byPath = await resolver.resolveStrict(first);
+    if (byPath) {
+      return {
+        tenant: byPath,
+        basePath: `/${first}`,
+        renderPath: normalizePath(segments.slice(1).join("/")),
+      };
+    }
+  }
+
+  // 3. Fall back to the registry default for this (unknown) host.
+  const fallback = await resolver.resolveByHost(host);
+  return { tenant: fallback, basePath: "", renderPath: normalizePath(pathname) };
+}

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, query);
+    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,249 @@
+/**
+ * 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";
+import { PRICE_BUCKETS, bucketForPrice } from "../priceBuckets.js";
+
+/** 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 for the (collection-scoped) pool, with LIVE counts: each
+ * group's value counts reflect every OTHER active filter (all groups but its
+ * own, plus q/availability/price), so selecting a value narrows the other
+ * groups' counts while still letting the user multi-select/deselect within
+ * the group they're looking at. Values known to the pool but narrowed to zero
+ * by other filters still appear (count: 0) rather than vanishing, so the
+ * facet list stays stable while filtering.
+ */
+export function buildFacets(
+  pool: CatalogProduct[],
+  query: ListProductsQuery = {},
+): Facet[] {
+  const optionValues = new Map<string, Set<string>>();
+  const tagNames = new Set<string>();
+  for (const p of pool) {
+    for (const t of p.tags) tagNames.add(t);
+    for (const opt of p.options) {
+      const set = optionValues.get(opt.name) ?? new Set<string>();
+      for (const v of p.variants) {
+        const val = v.option_values[opt.name];
+        if (val) set.add(val);
+      }
+      optionValues.set(opt.name, set);
+    }
+  }
+
+  const facets: Facet[] = [];
+  for (const [name, allValues] of optionValues) {
+    facets.push(buildOptionFacet(name, allValues, applyFilters(pool, query, name)));
+  }
+  if (tagNames.size) {
+    facets.push(buildTagFacet(tagNames, applyFilters(pool, query, "tags")));
+  }
+  facets.push(buildAvailabilityFacet(applyFilters(pool, query, "availability")));
+  facets.push(buildPriceFacet(applyFilters(pool, query, "price")));
+  return facets;
+}
+
+function buildOptionFacet(
+  name: string,
+  allValues: Set<string>,
+  scoped: CatalogProduct[],
+): Facet {
+  const counts = new Map<string, number>([...allValues].map((v) => [v, 0]));
+  for (const p of scoped) {
+    const seen = new Set<string>();
+    for (const v of p.variants) {
+      const val = v.option_values[name];
+      if (val && !seen.has(val)) seen.add(val);
+    }
+    for (const val of seen) counts.set(val, (counts.get(val) ?? 0) + 1);
+  }
+  return {
+    name,
+    values: sortFacetValues([...counts].map(([value, count]) => ({ value, count }))),
+  };
+}
+
+function buildTagFacet(allTagNames: Set<string>, scoped: CatalogProduct[]): Facet {
+  const counts = new Map<string, number>([...allTagNames].map((t) => [t, 0]));
+  for (const p of scoped) for (const t of p.tags) counts.set(t, (counts.get(t) ?? 0) + 1);
+  return {
+    name: "tags",
+    values: sortFacetValues([...counts].map(([value, count]) => ({ value, count }))),
+  };
+}
+
+function buildAvailabilityFacet(scoped: CatalogProduct[]): Facet {
+  const inStock = scoped.filter(isAvailable).length;
+  return {
+    name: "availability",
+    values: [
+      { value: "in-stock", count: inStock },
+      { value: "all", count: scoped.length },
+    ],
+  };
+}
+
+function buildPriceFacet(scoped: CatalogProduct[]): Facet {
+  const counts = new Map<string, number>(PRICE_BUCKETS.map((b) => [b.key, 0]));
+  for (const p of scoped) {
+    const bucket = bucketForPrice(fromPrice(p));
+    counts.set(bucket.key, (counts.get(bucket.key) ?? 0) + 1);
+  }
+  return {
+    name: "price",
+    values: PRICE_BUCKETS.map((b) => ({ value: b.key, count: counts.get(b.key) ?? 0 })),
+  };
+}
+
+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 every active filter EXCEPT the named group (used to compute that
+ * group's own live facet counts). Pass no `except` to apply everything (the
+ * normal result-set path).
+ */
+function applyFilters(
+  pool: CatalogProduct[],
+  query: ListProductsQuery,
+  except?: string,
+): CatalogProduct[] {
+  let out = [...pool];
+
+  // Free text (PLP supports an inline q) — always applied, never excludable.
+  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;
+      if (optName === except) 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 && except !== "tags") {
+      const set = new Set(tagFilter);
+      out = out.filter((p) => p.tags.some((t) => set.has(t)));
+    }
+  }
+
+  if (query.tags?.length && except !== "tags") {
+    const set = new Set(query.tags);
+    out = out.filter((p) => p.tags.some((t) => set.has(t)));
+  }
+
+  if (except !== "availability" && query.availability === "in-stock") {
+    out = out.filter(isAvailable);
+  }
+
+  if (except !== "price") {
+    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!);
+  }
+
+  return out;
+}
+
+/** Apply filters + sort (NOT pagination). */
+export function applyQuery(
+  pool: CatalogProduct[],
+  query: ListProductsQuery,
+): CatalogProduct[] {
+  const out = applyFilters(pool, query);
+  return sortProducts(out, query.sort, pool);
+}
+
+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[]>;
+}