@tokenoftrust/storefront-runner 1.3.2

package/packages/public-runtime/LICENSE

@@ -0,0 +1,58 @@
+Token of Trust Source-Available License — Local Development Only
+Version 1.0
+
+Copyright (c) 2026 Token of Trust, Inc. All rights reserved.
+
+1. DEFINITIONS
+   "Software" means this source code and any accompanying files in this
+   repository or distribution, including the storefront renderer runtime, the
+   `@tot/public-runtime` package, the storefront-runner distributable, and any
+   derivative works.
+   "Local Development" means running, building, and modifying the Software on a
+   machine you control, for the sole purpose of evaluating it or developing and
+   previewing your own tenant content against it. Serving the Software to any
+   third party, or over any public or shared network, is NOT Local Development.
+   "Token of Trust" means Token of Trust, Inc.
+
+2. GRANT (LOCAL DEVELOPMENT ONLY)
+   Subject to the terms below, Token of Trust grants you a personal,
+   non-exclusive, non-transferable, revocable license to use, copy, build, and
+   modify the Software SOLELY for Local Development.
+
+3. PERMISSION REQUIRED FOR EVERYTHING ELSE
+   Any use of the Software beyond Local Development requires the PRIOR WRITTEN
+   PERMISSION of Token of Trust. Without such permission you may NOT, in whole or
+   in part:
+   (a) deploy, host, serve, or otherwise run the Software in production or for
+       any third party, or on any public, staging, or shared/network-accessible
+       environment;
+   (b) use the Software for any commercial purpose or to provide a service to
+       others;
+   (c) distribute, publish, sublicense, sell, rent, lease, or otherwise make the
+       Software (or a derivative of it) available to any third party; or
+   (d) remove or obscure this license or the copyright notices.
+   To request permission, contact Token of Trust at legal@tokenoftrust.com.
+
+4. NO TRADEMARK LICENSE
+   This license grants no rights to the Token of Trust name, logos, or
+   trademarks.
+
+5. RESERVATION OF RIGHTS
+   All rights not expressly granted are reserved by Token of Trust. This is a
+   source-available license, not an open-source license; the Software is not
+   licensed under any OSI-approved license.
+
+6. TERMINATION
+   This license terminates automatically if you breach it. On termination you
+   must stop using the Software and destroy all copies in your possession.
+
+7. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL TOKEN OF TRUST BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.

package/packages/public-runtime/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@tot/public-runtime",
+  "version": "0.1.0",
+  "private": true,
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}

package/packages/public-runtime/src/binary-path.ts

@@ -0,0 +1,68 @@
+/**
+ * Binary-vs-text path classification — the SINGLE source of truth shared by the
+ * write side (seed's `buildSeedFiles`) and the read side (the Gitea read seam).
+ *
+ * The extraction/preview loop moves a tenant's files through two seams that MUST
+ * agree on what is binary, or a file's bytes round-trip differently on each side
+ * and binaries corrupt:
+ *
+ *   - WRITE: `customization-seed.ts#buildSeedFiles` base64-encodes binaries when
+ *     it materializes the colocated subtree into a flat Gitea-repo seed.
+ *   - READ:  `gitea-source.ts#createGiteaHttpSource().readContent` base64-encodes
+ *     binaries when it reads them back at a commit for the reconcile/assets sink.
+ *
+ * Keeping the extension set here (and importing it in both) guarantees the two
+ * seams classify identically. Runtime-portable (no `node:*`) so it is safe in the
+ * renderer, the Worker, the publish pipeline, and unit tests alike.
+ *
+ * SVG is intentionally TEXT (it is XML the verbatim-serve path can nonce-inject);
+ * CSS/JSON/HTML/JS/TXT/XML are text. Everything in the set below is opaque bytes.
+ */
+
+/**
+ * File extensions treated as BINARY (base64-encoded so raw bytes round-trip).
+ * Every other extension is emitted/read as UTF-8 text.
+ */
+export const BINARY_EXTENSIONS: ReadonlySet<string> = new Set([
+  // raster images
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "avif",
+  "ico",
+  "bmp",
+  "tiff",
+  "tif",
+  // fonts
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "eot",
+  // media
+  "mp4",
+  "webm",
+  "mov",
+  "mp3",
+  "wav",
+  "ogg",
+  // docs / archives
+  "pdf",
+  "zip",
+  "gz",
+]);
+
+/** The lowercased extension of `path` (no leading dot), or "" when it has none. */
+export function extensionOf(path: string): string {
+  const dot = path.lastIndexOf(".");
+  const slash = path.lastIndexOf("/");
+  if (dot === -1 || dot < slash) return "";
+  return path.slice(dot + 1).toLowerCase();
+}
+
+/** True when `path` names a binary asset (base64), false for text. */
+export function isBinaryPath(path: string): boolean {
+  return BINARY_EXTENSIONS.has(extensionOf(path));
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Tenant capability switches — config that travels with the PR (Track A/B).
+ *
+ * Three independently-toggleable capabilities:
+ *   - cartCheckout      — FoxyCart cart/checkout ("Powered by FoxyCart", Track A)
+ *   - ageVerification   — Token of Trust age/identity gate (21+ regulated)
+ *   - exciseTax         — excise tax collection at checkout (Track B, tot-foxycart)
+ *
+ * The source of truth is the tenant repo's `.tot/config.json` `capabilities`
+ * block — so a change is a code change that travels with a PR. Resolution is
+ * per-environment on the SAME published-artifact spine as theme/content:
+ *   localhost → working-tree config (ungated, HMR)
+ *   preview   → PR-head config reconciled to the `test` pointer
+ *   live      → the promoted config on the `live` pointer (evidence-gated promote)
+ * so each environment's capability state is independently pinned and a shared-env
+ * change is PR-gated by construction. `readPublishedArtifact(env, capabilities
+ * ArtifactPath)` overrides the build-time `TenantConfig.capabilities` default.
+ */
+import type { TenantConfig } from "./tenant.js";
+
+export interface CapabilityState {
+  enabled: boolean;
+}
+
+export interface CapabilityConfig {
+  /** FoxyCart cart/checkout: loader + signed add-to-cart. */
+  cartCheckout: CapabilityState;
+  /** Token of Trust age/identity verification (soft 21+ gate now; full ToT later). */
+  ageVerification: CapabilityState;
+  /** Excise tax collection at checkout (materialized in the FoxyCart cart). */
+  exciseTax: CapabilityState;
+}
+
+export type CapabilityKey = keyof CapabilityConfig;
+
+/** Stable capability order + labels for any surface that lists them. */
+export const CAPABILITY_KEYS: CapabilityKey[] = [
+  "cartCheckout",
+  "ageVerification",
+  "exciseTax",
+];
+
+/**
+ * Canonical published-artifact path for a tenant's capabilities. Same colocated
+ * `tenants/<id>/…` contract as theme/content, so the reconcile pipeline keys the
+ * KV artifact by it and the storefront reads it back per environment.
+ */
+export function capabilitiesArtifactPath(tenantId: string): string {
+  return `tenants/${tenantId}/capabilities.json`;
+}
+
+/**
+ * Resolve a tenant's effective capabilities: build-time `TenantConfig.capabilities`
+ * default (itself defaulted from siteType/compliance), then any per-environment
+ * published `override` layered on top. Undefined entries fall through, so a PR can
+ * flip ONE capability without restating the rest.
+ */
+export function resolveCapabilities(
+  tenant: Pick<TenantConfig, "capabilities" | "compliance" | "siteType">,
+  override?: Partial<CapabilityConfig> | null,
+): CapabilityConfig {
+  const c = tenant.capabilities;
+  const base: CapabilityConfig = {
+    // Commerce tenants get a cart by default; marketing tenants don't.
+    cartCheckout: {
+      enabled: c?.cartCheckout?.enabled ?? tenant.siteType !== "marketing",
+    },
+    // Regulated tenants (an age minimum) verify by default.
+    ageVerification: {
+      enabled: c?.ageVerification?.enabled ?? !!tenant.compliance?.minAge,
+    },
+    // Nicotine/vape tenants collect excise by default.
+    exciseTax: {
+      enabled: c?.exciseTax?.enabled ?? !!tenant.compliance?.nicotineWarning,
+    },
+  };
+  if (!override) return base;
+  return {
+    cartCheckout: {
+      enabled: override.cartCheckout?.enabled ?? base.cartCheckout.enabled,
+    },
+    ageVerification: {
+      enabled: override.ageVerification?.enabled ?? base.ageVerification.enabled,
+    },
+    exciseTax: {
+      enabled: override.exciseTax?.enabled ?? base.exciseTax.enabled,
+    },
+  };
+}

package/packages/public-runtime/src/catalog-api.ts

@@ -0,0 +1,81 @@
+/**
+ * Canonical catalog data contract (shared types). The tot20 HTTP catalog API has
+ * been retired — the storefront reads from a Cloudflare D1 edge replica — so these
+ * are now the in-process shapes shared across the catalog path:
+ *   - packages/migration  — the LOAD step's bulk-upsert result shape (counts/rows).
+ *   - apps/storefront      — the read clients' (D1 / fixture) list-query, facet,
+ *                            and list-response shapes.
+ *
+ * Tenant scoping is by `appDomain` (== TenantConfig.tot_data_scope).
+ */
+
+import type { CatalogCollection, CatalogProduct } from "./product.js";
+
+/** POST /api/catalog/products:bulkUpsert */
+export interface BulkUpsertProductsRequest {
+  appDomain?: string;
+  totApiKey?: string;
+  totSecretKey?: string;
+  products: CatalogProduct[];
+  /** When true, server skips records whose source_checksum is unchanged. */
+  incremental?: boolean;
+}
+
+export interface UpsertResultRow {
+  source_id: string;
+  handle: string;
+  action: "inserted" | "updated" | "skipped" | "error";
+  message?: string;
+}
+
+export interface BulkUpsertProductsResponse {
+  results: UpsertResultRow[];
+  counts: { inserted: number; updated: number; skipped: number; error: number };
+}
+
+/** POST /api/catalog/collections:bulkUpsert */
+export interface BulkUpsertCollectionsRequest {
+  appDomain?: string;
+  totApiKey?: string;
+  totSecretKey?: string;
+  collections: CatalogCollection[];
+  incremental?: boolean;
+}
+
+export interface BulkUpsertCollectionsResponse {
+  results: UpsertResultRow[];
+  counts: { inserted: number; updated: number; skipped: number; error: number };
+}
+
+/** GET /api/catalog/products  (list + facet, querystring-driven) */
+export interface ListProductsQuery {
+  collection?: string; // collection handle
+  sort?: "featured" | "price-asc" | "price-desc" | "newest" | "title-asc";
+  /** Facet filters: option name -> selected values. Encoded as repeated query params. */
+  filters?: Record<string, string[]>;
+  priceMin?: number;
+  priceMax?: number;
+  availability?: "in-stock" | "all";
+  tags?: string[];
+  page?: number;
+  pageSize?: number;
+  q?: string; // free-text search
+}
+
+export interface FacetValue {
+  value: string;
+  count: number;
+}
+
+export interface Facet {
+  name: string; // option name or "price"/"availability"/"tags"
+  values: FacetValue[];
+}
+
+export interface ListProductsResponse {
+  products: CatalogProduct[];
+  page: number;
+  pageSize: number;
+  total: number;
+  facets: Facet[];
+}

package/packages/public-runtime/src/catalog-d1.ts

@@ -0,0 +1,192 @@
+/**
+ * D1 (edge SQLite) catalog read-model — schema + row projections (the one-store
+ * target from epics/edge-read-replica.md). The storefront reads search, faceted
+ * listing, and full products from D1; the ETL emits the rows. This is the shared
+ * contract both sides agree on.
+ *
+ * - `products`         — one row per product: slim query columns + a `data` blob
+ *                        (the full CatalogProduct JSON) for PDP/listing retrieval.
+ * - `product_collections` — membership (handle -> collection handle).
+ * - `product_facets`   — (handle, name, value) for SQL GROUP BY facet counts.
+ * - `products_fts`      — FTS5 (trigram) over the searchable text: typo-tolerant
+ *                        search without loading the catalog into the Worker.
+ */
+import type { CatalogCollection, CatalogProduct } from "./product.js";
+
+export const CATALOG_D1_SCHEMA = `
+CREATE TABLE IF NOT EXISTS products (
+  handle           TEXT PRIMARY KEY NOT NULL,
+  title            TEXT NOT NULL,
+  vendor           TEXT,
+  product_type     TEXT,
+  tags             TEXT NOT NULL DEFAULT '[]',
+  description_text TEXT NOT NULL DEFAULT '',
+  price_min        REAL NOT NULL,
+  price_max        REAL NOT NULL,
+  currency         TEXT NOT NULL,
+  image            TEXT,
+  available        INTEGER NOT NULL DEFAULT 0,
+  status           TEXT NOT NULL,
+  position         INTEGER NOT NULL DEFAULT 0,
+  created_at       TEXT,
+  data             TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS product_collections (
+  handle     TEXT NOT NULL,
+  collection TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_pc_collection ON product_collections (collection);
+CREATE TABLE IF NOT EXISTS product_facets (
+  handle TEXT NOT NULL,
+  name   TEXT NOT NULL,
+  value  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_pf_name ON product_facets (name, value);
+CREATE TABLE IF NOT EXISTS collections (
+  handle   TEXT PRIMARY KEY NOT NULL,
+  title    TEXT NOT NULL,
+  position INTEGER NOT NULL DEFAULT 99,
+  data     TEXT NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS products_fts USING fts5 (
+  handle UNINDEXED, title, vendor, product_type, tags, description_text,
+  tokenize = 'trigram'
+);
+`.trim();
+
+export interface ProductRow {
+  handle: string;
+  title: string;
+  vendor: string | null;
+  product_type: string | null;
+  tags: string; // JSON array
+  description_text: string;
+  price_min: number;
+  price_max: number;
+  currency: string;
+  image: string | null;
+  available: number; // 0 | 1
+  status: string;
+  position: number;
+  created_at: string | null;
+  data: string; // full CatalogProduct JSON
+}
+
+const firstImage = (p: CatalogProduct): string | null =>
+  (p.images.find((i) => i.url) ?? p.images[0])?.url ?? null;
+
+/** Project a CatalogProduct into the `products` row. */
+export function toProductRow(p: CatalogProduct, position = 0): ProductRow {
+  return {
+    handle: p.handle,
+    title: p.title,
+    vendor: p.vendor ?? null,
+    product_type: p.product_type ?? null,
+    tags: JSON.stringify(p.tags),
+    description_text: p.description_text,
+    price_min: p.price_range.min,
+    price_max: p.price_range.max,
+    currency: p.price_range.currency,
+    image: firstImage(p),
+    available: p.variants.some((v) => v.inventory.available) ? 1 : 0,
+    status: p.status,
+    position,
+    created_at: p.created_at,
+    data: JSON.stringify(p),
+  };
+}
+
+/** Facet rows: one per distinct option value (across variants) + one per tag. */
+export function facetRows(p: CatalogProduct): Array<{ name: string; value: string }> {
+  const out: Array<{ name: string; value: string }> = [];
+  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);
+        out.push({ name: opt.name, value: val });
+      }
+    }
+  }
+  for (const tag of p.tags) out.push({ name: "tags", value: tag });
+  return out;
+}
+
+/** Collection-membership rows for a product. */
+export function collectionRows(p: CatalogProduct): Array<{ collection: string }> {
+  return p.collections.map((collection) => ({ collection }));
+}
+
+export interface CollectionRow {
+  handle: string;
+  title: string;
+  position: number;
+  data: string;
+}
+
+/** Project a CatalogCollection into the `collections` row. */
+export function toCollectionRow(c: CatalogCollection): CollectionRow {
+  return {
+    handle: c.handle,
+    title: c.title,
+    position: c.position ?? 99,
+    data: JSON.stringify(c),
+  };
+}
+
+/** SQL literal: NULL, a number, or a single-quote-escaped string. */
+function lit(v: string | number | null): string {
+  if (v === null) return "NULL";
+  if (typeof v === "number") return Number.isFinite(v) ? String(v) : "NULL";
+  return `'${v.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Emit a self-contained SQL seed (schema + a clean reseed of all rows) for a
+ * tenant, loadable into D1 via `wrangler d1 execute <DB> --file catalog.sql`.
+ * Includes ALL products (status column drives query visibility; getProductByHandle
+ * still resolves drafts). Re-runnable: it clears the tables before inserting.
+ */
+export function emitCatalogSql(
+  products: CatalogProduct[],
+  collections: CatalogCollection[] = [],
+): string {
+  const out: string[] = [
+    CATALOG_D1_SCHEMA,
+    "DELETE FROM products;",
+    "DELETE FROM product_collections;",
+    "DELETE FROM product_facets;",
+    "DELETE FROM products_fts;",
+    "DELETE FROM collections;",
+  ];
+  for (const c of collections) {
+    const r = toCollectionRow(c);
+    out.push(
+      `INSERT INTO collections (handle,title,position,data) VALUES (${[r.handle, r.title, r.position, r.data].map(lit).join(",")});`,
+    );
+  }
+  let position = 0;
+  for (const p of products) {
+    const r = toProductRow(p, position++);
+    out.push(
+      `INSERT INTO products (handle,title,vendor,product_type,tags,description_text,price_min,price_max,currency,image,available,status,position,created_at,data) VALUES (${[
+        r.handle, r.title, r.vendor, r.product_type, r.tags, r.description_text,
+        r.price_min, r.price_max, r.currency, r.image, r.available, r.status,
+        r.position, r.created_at, r.data,
+      ].map(lit).join(",")});`,
+    );
+    out.push(
+      `INSERT INTO products_fts (handle,title,vendor,product_type,tags,description_text) VALUES (${[
+        p.handle, p.title, p.vendor ?? "", p.product_type ?? "", p.tags.join(" "), p.description_text,
+      ].map(lit).join(",")});`,
+    );
+    for (const f of facetRows(p)) {
+      out.push(`INSERT INTO product_facets (handle,name,value) VALUES (${lit(p.handle)},${lit(f.name)},${lit(f.value)});`);
+    }
+    for (const c of collectionRows(p)) {
+      out.push(`INSERT INTO product_collections (handle,collection) VALUES (${lit(p.handle)},${lit(c.collection)});`);
+    }
+  }
+  return `${out.join("\n")}\n`;
+}