@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/lib/dev/storeStatus.ts

@@ -0,0 +1,142 @@
+/**
+ * Derive the /dev "store status" panel — a small, honest, per-tenant readout of what's
+ * already wired up for the signed-in developer's own store, computed from the resolved
+ * TenantConfig (+ whether the viewer has developer access). Pure and renderer-safe: it
+ * reads only public tenant shape, returns display strings, and NEVER emits a secret.
+ *
+ * SECRETS: the Storyblok delivery token is checked ONLY for presence (real vs the
+ * "…PLACEHOLDER" default) to decide the editorial row — the token value is never put in
+ * the returned rows. No session id, email, capability value, or magic-link data is read.
+ *
+ * PHASE HONESTY: cart/checkout/payments/excise/age-verification are Phase 2+. Even when a
+ * tenant's build-time `capabilities` flags are on, this platform hasn't shipped those, so
+ * they are ALWAYS reported as a single "coming later" row — never as live. The panel only
+ * marks something ✓ when Phase 1 actually serves it (route, catalog, theme, editorial,
+ * search, and the compliance guardrails that gate a submit).
+ */
+import type { TenantConfig } from "@tot/public-runtime";
+
+export type DevStatusState = "ok" | "todo" | "future";
+
+export interface DevStatusRow {
+  /** Stable key (for test assertions / keys). */
+  key: string;
+  /** Human label — the thing being reported. */
+  label: string;
+  /** Short value — the current standing. */
+  value: string;
+  state: DevStatusState;
+}
+
+export interface DevStoreStatus {
+  /** The tenant's display name, or null when no tenant resolved. */
+  storeName: string | null;
+  appDomain: string | null;
+  /** Best hosted URL to "open your storefront", or null. */
+  liveUrl: string | null;
+  /** True when this store carries regulated-commerce guardrails. */
+  regulated: boolean;
+  rows: DevStatusRow[];
+}
+
+/** A Storyblok token counts as configured only when it isn't the build placeholder. */
+export function editorialConfigured(token: string | undefined | null): boolean {
+  return !!token && !/PLACEHOLDER$/i.test(token) && token.trim().length > 0;
+}
+
+/** Marketing sites have no catalog/search; everything else (commerce) does. */
+function isCommerce(tenant: TenantConfig): boolean {
+  return tenant.siteType !== "marketing";
+}
+
+/** A tenant has a customized theme when it ships any theme_tokens overrides. */
+function hasCustomTheme(tenant: TenantConfig): boolean {
+  return !!tenant.theme_tokens && Object.keys(tenant.theme_tokens).length > 0;
+}
+
+/**
+ * Best hosted URL for "Open your storefront": prefer the tenant's own
+ * `*.tokenoftrust.store` hosted-store subdomain (proven real for pilot tenants); else
+ * fall back to the shared storefront host at the tenant's path.
+ */
+export function hostedStoreUrl(tenant: TenantConfig | null): string | null {
+  if (!tenant) return null;
+  const sub = tenant.domains.find((d) => d.toLowerCase().endsWith(".tokenoftrust.store"));
+  if (sub) return `https://${sub}/`;
+  return `https://storefront.tokenoftrust.store/${tenant.appDomain}/`;
+}
+
+/**
+ * Build the status readout for `tenant`. Rows are ordered "what's wired → what's a
+ * guardrail → what's coming later" so the developer reads a story, not a dashboard.
+ */
+export function deriveStoreStatus(tenant: TenantConfig | null): DevStoreStatus {
+  if (!tenant) {
+    return {
+      storeName: null,
+      appDomain: null,
+      liveUrl: null,
+      regulated: false,
+      rows: [
+        { key: "route", label: "Storefront route", value: "ready", state: "ok" },
+        { key: "store", label: "Your store", value: "sign in to detect", state: "todo" },
+      ],
+    };
+  }
+
+  const commerce = isCommerce(tenant);
+  const editorial = editorialConfigured(tenant.storyblok_space_token);
+  const regulated = !!tenant.compliance;
+  const rows: DevStatusRow[] = [];
+
+  rows.push({ key: "route", label: "Storefront route", value: "live", state: "ok" });
+  rows.push({ key: "store", label: "Your store", value: tenant.displayName, state: "ok" });
+
+  rows.push(
+    commerce
+      ? { key: "catalog", label: "Catalog", value: "connected", state: "ok" }
+      : { key: "catalog", label: "Catalog", value: "marketing site — none", state: "future" },
+  );
+
+  rows.push({
+    key: "theme",
+    label: "Theme",
+    value: hasCustomTheme(tenant) ? "your theme detected" : "reference theme",
+    state: "ok",
+  });
+
+  rows.push(
+    editorial
+      ? { key: "editorial", label: "Editorial (Storyblok)", value: "connected", state: "ok" }
+      : { key: "editorial", label: "Editorial", value: "local content", state: "ok" },
+  );
+
+  if (commerce) {
+    rows.push({ key: "search", label: "Search", value: "enabled", state: "ok" });
+  }
+
+  if (regulated) {
+    const minAge = tenant.compliance?.minAge;
+    rows.push({
+      key: "guardrails",
+      label: "Compliance guardrails",
+      value: minAge ? `${minAge}+ · checked before ship` : "checked before ship",
+      state: "ok",
+    });
+  }
+
+  rows.push({
+    key: "phase2",
+    label: "Cart · checkout · payments · age check",
+    value: "Phase 2+",
+    state: "future",
+  });
+
+  return {
+    storeName: tenant.displayName,
+    appDomain: tenant.appDomain,
+    liveUrl: hostedStoreUrl(tenant),
+    regulated,
+    rows,
+  };
+}

package/apps/storefront/src/lib/diag/redact.ts

@@ -0,0 +1,20 @@
+/**
+ * Redaction helpers for diagnostic logs — keep traces correlatable without persisting PII.
+ */
+
+/** Mask an email for logs: keep the first char + the domain (`d***@example.com`). */
+export function maskEmail(email: string): string {
+  const at = email.indexOf("@");
+  if (at <= 0) return "***";
+  return `${email[0]}***${email.slice(at)}`;
+}
+
+/**
+ * Email for a diagnostic line: the FULL address in local dev only (`import.meta.env.DEV`
+ * is a static boolean → this branch is tree-shaken from the production worker), where logs
+ * are local + gitignored and the raw address is needed for debugging; MASKED everywhere the
+ * build is deployed, so prod/worker logs never persist raw recipient PII.
+ */
+export function diagEmail(email: string): string {
+  return import.meta.env.DEV ? email : maskEmail(email);
+}

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

@@ -0,0 +1,128 @@
+/**
+ * Full-page edge cache for production browse reads (Epic Phase-2 D1).
+ *
+ * Phase 1 cached only the catalog *API* calls (HttpToTClient); the rendered HTML
+ * was re-built on every request even though browse pages change rarely. This
+ * caches the final HTML response in the Workers Cache API and short-circuits the
+ * whole render on a hit.
+ *
+ * Invalidation is a per-tenant **cache version** integer in TENANT_CACHE KV. Bump
+ * it (see api/cache-purge.ts, called by the ETL after a re-migration) and every
+ * old key becomes unreachable — tag-like purge with no URL enumeration, and no
+ * dependency on Enterprise cache-tags. Stale keys age out on their own.
+ *
+ * Deliberately NOT cached: preview/test output (per-developer, noindex), any
+ * response with Set-Cookie, and anything non-200/non-HTML. In `astro dev` there
+ * is no `caches` global, so every helper is a clean no-op.
+ *
+ * Note on the CSP nonce: a stored page carries the nonce it was rendered with, in
+ * both its inline tags and its CSP header, and is served to many users. That is
+ * safe — the nonce is not a secret; it only has to match within one identical,
+ * non-personalized document, which it does.
+ */
+
+/** Synthetic internal origin for cache keys — never hits the network. */
+const CACHE_ORIGIN = "https://page-cache.tot.internal";
+const versionKey = (tenantId: string) => `cachever:${tenantId}`;
+
+/** Default freshness window (s-maxage) and stale window for cached pages. */
+const DEFAULT_TTL = 300;
+const DEFAULT_SWR = 86_400;
+
+/**
+ * Routes worth caching. Excludes the JSON typeahead (`?format=json`, high-q
+ * cardinality), `/api/*`, and anything with a preview token (handled upstream).
+ * Single-segment slugs (e.g. /about, /shipping-returns) cover editorial pages;
+ * non-200 responses are filtered at store time, so unknown slugs never persist.
+ */
+export function isCacheablePath(pathname: string, params: URLSearchParams): boolean {
+  if (params.get("format") === "json") return false;
+  if (pathname.startsWith("/api/")) return false;
+  // Authenticated operator surfaces are per-viewer and MUST NOT be edge-cached —
+  // the bare `/dashboard` index is a single-segment slug that would otherwise
+  // match the editorial-page rule below and be served across viewers.
+  if (pathname === "/dashboard" || pathname.startsWith("/dashboard/")) return false;
+  // `/dev` is the authenticated developer surface — per-viewer (it renders the
+  // signed-in developer's own store, email, and gated demo), so like /dashboard
+  // it must never be shared across viewers. It's also the loudest failure if
+  // stale: its styles build to a CONTENT-HASHED asset (/_astro/dev.<hash>.css),
+  // so a cached old HTML keeps pointing at a hash that no longer exists after the
+  // next deploy → the stylesheet 404s and the page renders unstyled (its inline
+  // nonce'd <script> tags break the same way). Never cache it.
+  if (pathname === "/dev") return false;
+  if (pathname === "/" || pathname === "/search") return true;
+  if (pathname.startsWith("/products/")) return true;
+  if (pathname.startsWith("/collections/")) return true;
+  return /^\/[a-z0-9][a-z0-9-]*\/?$/.test(pathname);
+}
+
+export function pageCacheKey(
+  tenantId: string,
+  pathname: string,
+  search: string,
+  version: number,
+): Request {
+  return new Request(`${CACHE_ORIGIN}/${tenantId}/v${version}${pathname}${search}`);
+}
+
+/** Current cache version for a tenant (defaults to 1). KV read is edge-cached. */
+export async function readCacheVersion(
+  kv: KVNamespace,
+  tenantId: string,
+): Promise<number> {
+  const raw = await kv.get(versionKey(tenantId), { cacheTtl: 60 });
+  const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(n) && n > 0 ? n : 1;
+}
+
+/** Bump a tenant's cache version (logical purge of all its pages). Returns the new version. */
+export async function bumpCacheVersion(
+  kv: KVNamespace,
+  tenantId: string,
+): Promise<number> {
+  const next = (await readCacheVersion(kv, tenantId)) + 1;
+  await kv.put(versionKey(tenantId), String(next));
+  return next;
+}
+
+/** Return a cached page response (fresh clone), or null on miss. */
+export async function getCachedPage(
+  cache: Cache,
+  key: Request,
+): Promise<Response | null> {
+  const hit = await cache.match(key);
+  if (!hit) return null;
+  const res = new Response(hit.body, hit);
+  res.headers.set("X-ToT-Cache", "hit");
+  return res;
+}
+
+/**
+ * Store a rendered page if it is safe to cache. No-op for non-200, non-HTML, or
+ * cookie-bearing responses. Sets a public Cache-Control so any fronting CDN can
+ * help too. Caller passes the FINAL response (after CSP headers are set).
+ */
+export async function putCachedPage(
+  cache: Cache,
+  key: Request,
+  response: Response,
+  opts: { ttl?: number; swr?: number } = {},
+): Promise<void> {
+  if (response.status !== 200) return;
+  if (!(response.headers.get("content-type") ?? "").includes("text/html")) return;
+  if (response.headers.has("set-cookie")) return;
+
+  const ttl = opts.ttl ?? DEFAULT_TTL;
+  const swr = opts.swr ?? DEFAULT_SWR;
+  const cloned = response.clone();
+  const toStore = new Response(cloned.body, cloned);
+  toStore.headers.set(
+    "Cache-Control",
+    `public, s-maxage=${ttl}, stale-while-revalidate=${swr}`,
+  );
+  toStore.headers.set("X-ToT-Cache", "stored");
+  await cache.put(key, toStore).catch(() => void 0);
+}
+
+export const PAGE_CACHE_TTL = DEFAULT_TTL;
+export const PAGE_CACHE_SWR = DEFAULT_SWR;

package/apps/storefront/src/lib/email/magicLinkInviteEmail.ts

@@ -0,0 +1,62 @@
+/**
+ * The storefront's OWN branded developer-invite email (magic-link flow). The storefront
+ * owns presentation now — this is our template, our brand, rendered here and handed to
+ * tot20 only for transport (see lib/messaging/messagesClient.ts). A single primary CTA
+ * links to the GET-safe /auth/magic landing carrying the one-time token.
+ *
+ * Email HTML rules: inline styles only (no <style>/external CSS — mail clients strip them),
+ * table-free simple layout, and a visible fallback URL under the button (some clients don't
+ * render buttons). The token rides in the URL but is only consumed by a POST on the landing
+ * page, so a scanner GET can't burn it.
+ */
+
+/** Minimal HTML escape for untrusted interpolation (the inviter note). */
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export interface MagicLinkInviteEmailInput {
+  /** The full magic-link URL (…/auth/magic?token=…) — already token-carrying. */
+  magicUrl: string;
+  /** Display name of the store/experience. Default "Regulated Storefront". */
+  storeName?: string;
+  /** Optional personal note from the inviter (untrusted → escaped). */
+  note?: string;
+}
+
+export function renderMagicLinkInviteEmail(input: MagicLinkInviteEmailInput): {
+  subject: string;
+  html: string;
+} {
+  const store = input.storeName?.trim() || "Regulated Storefront";
+  const subject = `Your invitation to ${store}`;
+  const url = input.magicUrl;
+  const note = input.note?.trim() ? esc(input.note.trim()) : null;
+
+  const html = `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head>
+  <body style="margin:0;padding:0;background:#f5f4f0;">
+    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#1c1c1c;">
+      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0f7b6c;margin:0 0 24px;">
+        Token of Trust&#169; &middot; ${esc(store)}
+      </div>
+      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.01em;margin:0 0 12px;color:#0b1f3a;">You've been invited</h1>
+      <p style="margin:0 0 8px;color:#3a3a3a;">You've been given developer access to <strong>${esc(store)}</strong>. Click below to sign in — no password needed.</p>
+      ${note ? `<div style="margin:16px 0;padding:12px 14px;background:#eef4ff;border:1px solid #c3d4f5;border-radius:8px;color:#234;font-size:14px;"><strong>Note from your inviter:</strong><br>${note}</div>` : ""}
+      <div style="margin:28px 0;">
+        <a href="${url}" style="display:inline-block;background:#0f7b6c;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:9px;">Sign in to ${esc(store)}</a>
+      </div>
+      <p style="margin:0 0 4px;font-size:13px;color:#6a6a6a;">Or paste this link into your browser:</p>
+      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${url}" style="color:#0f7b6c;">${url}</a></p>
+      <p style="margin:0;font-size:12px;color:#9a9a9a;border-top:1px solid #e6e4de;padding-top:16px;">This is a single-use sign-in link. If you didn't expect this invitation, you can ignore this email.</p>
+    </div>
+  </body>
+</html>`;
+
+  return { subject, html };
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Runtime env access that works in BOTH contexts:
+ *   - `astro dev` (Node): reads import.meta.env / process.env.
+ *   - Cloudflare Workers (prod): reads the `cloudflare:workers` env module.
+ *
+ * Astro v6+/@astrojs/cloudflare v14 REMOVED `Astro.locals.runtime.env`; the
+ * supported path is `import { env } from "cloudflare:workers"`. That module only
+ * exists in the worker runtime, so we import it lazily + guarded and fall back
+ * to build-time env in dev. See DECISIONS.md.
+ */
+import type { D1Like } from "./d1/catalog.js";
+
+let workerEnv: Record<string, unknown> | null | undefined;
+
+async function getWorkerEnv(): Promise<Record<string, unknown> | null> {
+  if (workerEnv !== undefined) return workerEnv;
+  try {
+    // @ts-expect-error — virtual module, only resolvable in the Workers runtime.
+    const mod = await import("cloudflare:workers");
+    workerEnv = (mod.env ?? null) as Record<string, unknown> | null;
+  } catch {
+    workerEnv = null;
+  }
+  return workerEnv;
+}
+
+function fromBuild(key: string): string | undefined {
+  const meta = import.meta.env as Record<string, string | undefined>;
+  if (meta[key] != null) return meta[key];
+  if (typeof process !== "undefined" && process.env && process.env[key] != null) {
+    return process.env[key];
+  }
+  return undefined;
+}
+
+export async function readEnv(key: string): Promise<string | undefined> {
+  const w = await getWorkerEnv();
+  const wv = w?.[key];
+  if (typeof wv === "string" && wv.length) return wv;
+  return fromBuild(key);
+}
+
+/** KV binding for the newsletter stub / tenant cache, if present in the runtime. */
+export async function readKv(binding: string): Promise<KVNamespace | undefined> {
+  const w = await getWorkerEnv();
+  const b = w?.[binding];
+  return (b as KVNamespace | undefined) ?? undefined;
+}
+
+/** D1 catalog binding for the edge read replica, if present in the runtime. */
+export async function readD1(binding: string): Promise<D1Like | undefined> {
+  const w = await getWorkerEnv();
+  return (w?.[binding] as D1Like | undefined) ?? undefined;
+}
+
+/** R2 bucket binding (e.g. TENANT_ASSETS, PRODUCT_IMAGES), if present. */
+export async function readR2(binding: string): Promise<R2Bucket | undefined> {
+  const w = await getWorkerEnv();
+  return (w?.[binding] as R2Bucket | undefined) ?? undefined;
+}

package/apps/storefront/src/lib/fixtures/sampleProducts.ts

@@ -0,0 +1,130 @@
+/**
+ * Fixture CatalogProducts for the style guide / component previews. Hard-coded so
+ * the commerce components render WITHOUT a live catalog. Each entry exercises a
+ * different card/price/badge state (default, sale, from-price, out-of-stock,
+ * compliant, new). Preview-only — never served on a real storefront surface.
+ */
+import type { CatalogProduct, CatalogVariant } from "@tot/public-runtime";
+
+const NOW = "2026-07-01T00:00:00Z";
+
+interface VariantSeed {
+  price: number;
+  compareAt?: number;
+  available?: boolean;
+  option?: Record<string, string>;
+  title?: string;
+}
+
+function mkVariant(handle: string, i: number, v: VariantSeed): CatalogVariant {
+  return {
+    tenant_id: "sample",
+    id: `${handle}-v${i}`,
+    product_id: handle,
+    source: { platform: "shopify", source_id: `${handle}-v${i}` },
+    sku: `${handle.toUpperCase()}-${i}`,
+    title: v.title ?? "Default",
+    price: v.price,
+    compare_at_price: v.compareAt,
+    currency: "USD",
+    option_values: v.option ?? {},
+    inventory: { available: v.available ?? true },
+    position: i + 1,
+  };
+}
+
+interface ProductSeed {
+  handle: string;
+  title: string;
+  vendor?: string;
+  tags?: string[];
+  createdAt?: string;
+  options?: CatalogProduct["options"];
+  variants: VariantSeed[];
+}
+
+function mkProduct(seed: ProductSeed): CatalogProduct {
+  const variants = seed.variants.map((v, i) => mkVariant(seed.handle, i, v));
+  const prices = variants.map((v) => v.price);
+  return {
+    tenant_id: "sample",
+    id: seed.handle,
+    source: { platform: "shopify", source_id: seed.handle },
+    handle: seed.handle,
+    title: seed.title,
+    description_html: `<p>${seed.title}</p>`,
+    description_text: seed.title,
+    vendor: seed.vendor,
+    product_type: "Sample",
+    tags: seed.tags ?? [],
+    status: "active",
+    seo: {},
+    options: seed.options ?? [],
+    images: [],
+    variants,
+    price_range: { min: Math.min(...prices), max: Math.max(...prices), currency: "USD" },
+    collections: ["sample"],
+    metafields: [],
+    created_at: seed.createdAt ?? NOW,
+    updated_at: NOW,
+    migrated_at: NOW,
+    source_checksum: seed.handle,
+  };
+}
+
+/** Six products, each showing a different card/price/badge permutation. */
+export const sampleProducts: CatalogProduct[] = [
+  mkProduct({
+    handle: "sample-default",
+    title: "Classic Everyday Tee",
+    vendor: "Northwind",
+    tags: ["bestseller"],
+    variants: [{ price: 28 }],
+  }),
+  mkProduct({
+    handle: "sample-sale",
+    title: "Merino Zip Hoodie",
+    vendor: "Northwind",
+    tags: ["bestseller"],
+    variants: [{ price: 64, compareAt: 96 }],
+  }),
+  mkProduct({
+    handle: "sample-from",
+    title: "Trail Runner — All Sizes",
+    vendor: "Summit Co.",
+    options: [{ name: "Size", position: 1, values: ["S", "M", "L"] }],
+    variants: [
+      { price: 42, option: { Size: "S" }, title: "S" },
+      { price: 48, option: { Size: "M" }, title: "M" },
+      { price: 55, option: { Size: "L" }, title: "L" },
+    ],
+  }),
+  mkProduct({
+    handle: "sample-oos",
+    title: "Limited Canvas Pack",
+    vendor: "Field & Co.",
+    variants: [{ price: 120, available: false }],
+  }),
+  mkProduct({
+    handle: "sample-compliant",
+    title: "Age-Verified Reserve",
+    vendor: "Cellar 21",
+    tags: ["compliant", "bestseller"],
+    variants: [{ price: 89 }],
+  }),
+  mkProduct({
+    handle: "sample-new",
+    title: "Just-Dropped Utility Cap",
+    vendor: "Northwind",
+    tags: ["new"],
+    createdAt: NOW,
+    variants: [{ price: 24, compareAt: 32 }],
+  }),
+];
+
+/** Optional per-handle rating aggregates for the preview (source before use). */
+export const sampleRatings: Record<string, { rating: number; count: number }> = {
+  "sample-default": { rating: 4.5, count: 128 },
+  "sample-sale": { rating: 4.8, count: 64 },
+  "sample-compliant": { rating: 5, count: 12 },
+};

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

@@ -0,0 +1,38 @@
+/** Small presentation helpers shared across components. Tenant locale/currency aware. */
+
+export function formatPrice(
+  amount: number,
+  currency: string,
+  locale = "en-US",
+): string {
+  try {
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency,
+      minimumFractionDigits: amount % 1 === 0 ? 0 : 2,
+    }).format(amount);
+  } catch {
+    return `${currency} ${amount.toFixed(2)}`;
+  }
+}
+
+export function discountPercent(price: number, compareAt?: number): number | null {
+  if (!compareAt || compareAt <= price) return null;
+  return Math.round(((compareAt - price) / compareAt) * 100);
+}
+
+/** Truncate plain text for meta descriptions / card copy. */
+export function truncate(text: string, max = 160): string {
+  const clean = text.replace(/\s+/g, " ").trim();
+  if (clean.length <= max) return clean;
+  return clean.slice(0, max - 1).replace(/\s+\S*$/, "") + "…";
+}
+
+/** Locale-aware "Jan 3, 2026" formatting for an ISO date; "" if missing/invalid. */
+export function formatDate(iso: string | undefined, locale = "en-US"): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime())
+    ? ""
+    : d.toLocaleDateString(locale, { year: "numeric", month: "short", day: "numeric" });
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Request-scoped FoxyCart commerce resolution (Track A).
+ *
+ * Bridges the tenant's static `commerce.foxy` config with runtime env so the
+ * demo store can be swapped without a code change and the signing secret stays
+ * out of source:
+ *   - `FOXY_STORE_SUBDOMAIN` overrides the tenant's default subdomain (one env
+ *     var points every commerce tenant at our shared demo store).
+ *   - `FOXY_CART_SECRET` is the cart-validation secret used only in `signed`
+ *     mode; the `unsigned-demo` mode never reads it (validation is OFF), which
+ *     is what lets a developer run the whole cart locally with zero secrets.
+ */
+import type { TenantConfig, ResolvedFoxyCommerce } from "@tot/public-runtime";
+import { resolveFoxyCommerce } from "@tot/public-runtime";
+import { readEnv } from "@/lib/env";
+
+/**
+ * Resolve the effective FoxyCart facts for a tenant, or null when the tenant has
+ * no store configured. Applies the `FOXY_STORE_SUBDOMAIN` override.
+ */
+export async function resolveTenantCommerce(
+  tenant: TenantConfig,
+): Promise<ResolvedFoxyCommerce | null> {
+  const foxy = tenant.commerce?.foxy;
+  if (!foxy) return null;
+  // Per-environment overrides so the SAME tenant can point at different stores /
+  // checkout hosts by env: FOXY_STORE_SUBDOMAIN picks the Foxy store; FOXY_STORE_
+  // DOMAIN sets a branded custom checkout domain (e.g. checkout.preview.
+  // tokenoftrust.com on the shared test env, secure.<merchant>.com on live).
+  const subOverride = await readEnv("FOXY_STORE_SUBDOMAIN");
+  const domainOverride = await readEnv("FOXY_STORE_DOMAIN");
+  const storeSubDomain =
+    subOverride && subOverride.length ? subOverride : foxy.storeSubDomain;
+  const storeDomain =
+    domainOverride && domainOverride.length ? domainOverride : foxy.storeDomain;
+  return resolveFoxyCommerce({ ...foxy, storeSubDomain, storeDomain });
+}
+
+/**
+ * The cart-validation secret for signed mode. Returns undefined in
+ * `unsigned-demo` mode (never needed) or when unset. A signed-mode tenant with
+ * no secret is a misconfiguration the caller must handle (fall back to no cart).
+ */
+export async function readCartSecret(
+  commerce: ResolvedFoxyCommerce,
+): Promise<string | undefined> {
+  if (commerce.mode !== "signed") return undefined;
+  return readEnv("FOXY_CART_SECRET");
+}