@tokenoftrust/storefront-runner 0.1.0

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

@@ -0,0 +1,243 @@
+/**
+ * Tenant configuration + theme token contract.
+ *
+ * Phase 1 resolves tenants from a static config map/KV by hostname. The lookup
+ * interface (resolveTenant) is intentionally async + many-ready so the same seam
+ * scales to Cloudflare-for-SaaS custom hostnames later without a rewrite.
+ */
+import type { FoxyCommerceConfig } from "./foxy.js";
+import type { CapabilityConfig } from "./capabilities.js";
+
+export interface ThemeColorTokens {
+  bg: string;
+  surface: string;
+  text: string;
+  muted: string;
+  primary: string;
+  "primary-contrast": string;
+  accent: string;
+  border: string;
+  success: string;
+  sale: string;
+}
+
+export interface ThemeFontFamily {
+  family: string;
+  weights: number[];
+}
+
+export interface ThemeTypeTokens {
+  display: ThemeFontFamily;
+  body: ThemeFontFamily;
+  mono?: ThemeFontFamily;
+  /** Type scale ratio, e.g. 1.25 (major third). */
+  scale: number;
+  tracking?: string;
+}
+
+export interface ThemeSpaceTokens {
+  /** Base spacing unit in px. */
+  base: number;
+  /** Multiplier scale, e.g. [0, 0.25, 0.5, 1, 1.5, 2, 3, 4, 6, 8]. */
+  scale: number[];
+  containerMaxWidth: string;
+  sectionRhythm: string;
+}
+
+export interface ThemeShapeTokens {
+  radius: { sm: string; md: string; lg: string; full: string };
+  borderWeights: { thin: string; medium: string; thick: string };
+  shadow: { sm: string; md: string; lg: string };
+}
+
+export interface ThemeBrandTokens {
+  logoLight: string;
+  logoDark: string;
+  favicon: string;
+  ogImage: string;
+  /** "full" | "reduced" — tenant-level default motion preference. */
+  motion: "full" | "reduced";
+  /**
+   * Header treatment. "dark" renders the bar in the primary color carrying the
+   * light logo (matches brands whose header is dark + white logo, e.g. vape
+   * stores); "light" (default) is a light bar with the dark logo/wordmark.
+   */
+  headerVariant?: "light" | "dark";
+  /**
+   * Hero treatment. "bold" (default) paints the hero full-bleed in the primary
+   * color (one signature moment). "light" renders the hero on the page
+   * background with the brand color used only as an accent on the headline/CTA —
+   * matches merchants whose own site is a light page with color accents. The
+   * brand adopter sets "light" when it captures a real hero image.
+   */
+  heroVariant?: "bold" | "light";
+}
+
+export interface ThemeTokens {
+  color: ThemeColorTokens;
+  type: ThemeTypeTokens;
+  space: ThemeSpaceTokens;
+  shape: ThemeShapeTokens;
+  brand: ThemeBrandTokens;
+}
+
+/**
+ * Regulated-commerce compliance (e.g. vape/nicotine). Browse-surface only —
+ * the actual identity/age VERIFICATION is Token of Trust's product and is wired
+ * in a later phase; this config drives storefront affordances (FDA warning, the
+ * soft 21+ affirmation gate, shipping-restriction notices). Omit/undefined for
+ * unregulated tenants and none of it renders.
+ */
+export interface ComplianceConfig {
+  /** Minimum age to enter. Drives the soft affirmation gate (e.g. 21). */
+  minAge?: number;
+  /** Render the FDA nicotine warning sitewide + reinforced on PDP. */
+  nicotineWarning?: boolean;
+  /** Short PACT-Act / no-ship-states / adult-signature notice (plain text). */
+  shippingRestriction?: string;
+}
+
+/**
+ * What a tenant's site is FOR. "commerce" (default) is the browse/discover
+ * ecommerce storefront the platform was born as. "marketing" is a non-commerce
+ * B2B/SaaS site — chrome, rich page composition, and conversion CTAs, with the
+ * catalog/cart affordances switched off. The mode picks feature DEFAULTS
+ * (see resolveTenantFeatures); `features` overrides individual flags.
+ */
+export type SiteType = "commerce" | "marketing";
+
+/**
+ * Per-tenant capability switches. These gate whole surfaces so the same
+ * component library renders both a store and a marketing site without any
+ * tenant-specific `if` in shared code. Every flag has a sensible default keyed
+ * off `siteType`; a tenant only lists the ones it wants to flip.
+ */
+export interface TenantFeatures {
+  /** Catalog surfaces: /collections, /products/*, listing grids, PDPs. */
+  catalog: boolean;
+  /** Header search typeahead island. */
+  productSearch: boolean;
+  /** Wishlist / "saved items" surface + header heart control. */
+  savedItems: boolean;
+  /** Product quick-view dialog island. */
+  quickView: boolean;
+  /** Newsletter capture forms (footer + homepage block). */
+  newsletter: boolean;
+  /** Product/collection URLs in the XML sitemap. */
+  commerceSitemap: boolean;
+  /** Product-offer JSON-LD on product/collection pages. */
+  productJsonLd: boolean;
+  /** Soft age-affirmation gate + regulated-commerce chrome (also needs `compliance`). */
+  ageGate: boolean;
+}
+
+const COMMERCE_FEATURES: TenantFeatures = {
+  catalog: true,
+  productSearch: true,
+  savedItems: true,
+  quickView: true,
+  newsletter: true,
+  commerceSitemap: true,
+  productJsonLd: true,
+  ageGate: true,
+};
+
+const MARKETING_FEATURES: TenantFeatures = {
+  catalog: false,
+  productSearch: false,
+  savedItems: false,
+  quickView: false,
+  newsletter: false,
+  commerceSitemap: false,
+  productJsonLd: false,
+  ageGate: false,
+};
+
+/** Feature defaults for a site type (returns a fresh copy — safe to mutate). */
+export function siteTypeDefaults(siteType: SiteType): TenantFeatures {
+  return { ...(siteType === "marketing" ? MARKETING_FEATURES : COMMERCE_FEATURES) };
+}
+
+/**
+ * Resolve a tenant's effective features: siteType defaults, with any explicit
+ * `features` overrides layered on top (undefined entries ignored, so a tenant
+ * can flip one flag without restating the rest). Unset `siteType` == "commerce",
+ * preserving the platform's original behavior for existing tenants.
+ */
+export function resolveTenantFeatures(
+  tenant: Pick<TenantConfig, "siteType" | "features">,
+): TenantFeatures {
+  const base = siteTypeDefaults(tenant.siteType ?? "commerce");
+  if (!tenant.features) return base;
+  for (const [k, v] of Object.entries(tenant.features)) {
+    if (v !== undefined) base[k as keyof TenantFeatures] = v;
+  }
+  return base;
+}
+
+export interface TenantConfig {
+  tenant_id: string;
+  /** ToT-side merchant identifier (appDomain), e.g. "pilot.tokenoftrust.com". */
+  appDomain: string;
+  /** The hostname(s) that resolve to this tenant. */
+  domains: string[];
+  /** Primary canonical domain for SEO/canonical URLs. */
+  canonicalDomain: string;
+  displayName: string;
+  /** Storyblok delivery token for this tenant's child space. */
+  storyblok_space_token: string;
+  /** Data scope passed to the ToT catalog API (usually == appDomain). */
+  tot_data_scope: string;
+  /** Per-tenant theme overrides; merged over the reference theme defaults. */
+  theme_tokens: DeepPartial<ThemeTokens>;
+  /** Currency for display formatting. */
+  currency: string;
+  locale: string;
+  /**
+   * What the site is for: "commerce" (default) or "marketing". Drives feature
+   * defaults (resolveTenantFeatures) and non-commerce chrome. Omitted == commerce.
+   */
+  siteType?: SiteType;
+  /** Explicit feature overrides layered atop the siteType defaults. */
+  features?: Partial<TenantFeatures>;
+  /** Regulated-commerce affordances; undefined for unregulated tenants. */
+  compliance?: ComplianceConfig;
+  /**
+   * Cart/checkout engine wiring (FoxyCart, Track A). Present on commerce tenants
+   * that have a FoxyCart store; drives the loader + signed add-to-cart. The
+   * `storeSubDomain` here is a default — middleware may override it from env
+   * (FOXY_STORE_SUBDOMAIN) so the demo store swaps with zero code change. The
+   * signing SECRET is never stored on the tenant; it's an env Worker binding.
+   */
+  commerce?: {
+    foxy?: FoxyCommerceConfig;
+  };
+  /**
+   * PR-gated capability switches (cart/checkout, age/identity verification,
+   * excise tax). Source of truth is the tenant repo's `.tot/config.json`; this
+   * build-time default is overridden per environment by the published
+   * capabilities artifact (localhost=working tree, preview=PR head, live=promoted).
+   * Undefined entries default from siteType/compliance — see resolveCapabilities.
+   */
+  capabilities?: Partial<CapabilityConfig>;
+}
+
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/** The interface the tenant-resolution middleware implements. */
+export interface TenantResolver {
+  /**
+   * Resolve a tenant for a hostname, falling back to a default tenant for
+   * unknown hosts (Phase 1 convenience so preview/local hosts still render).
+   */
+  resolveByHost(host: string): Promise<TenantConfig | null>;
+  /**
+   * Strict match: return the tenant that explicitly claims `host` in its
+   * `domains`, or null. Unlike resolveByHost it never falls back to a default,
+   * so callers can detect "this host/segment owns no tenant" — used by the
+   * `/<domain>/*` path-prefix routing fallback.
+   */
+  resolveStrict(host: string): Promise<TenantConfig | null>;
+}

package/packages/public-runtime/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}

package/packages/public-runtime/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+    environment: "node",
+  },
+});

package/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+packages:
+  - "apps/*"
+  - "packages/*"
+onlyBuiltDependencies:
+  - esbuild
+  - sharp
+  - workerd

package/scripts/build/copy-tenant-assets.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Prebuild step for the colocated tenant layout.
+ *
+ * A tenant IS the repo-root directory `tenants/<id>/` (holding content, public,
+ * theme.json). Astro serves static assets from `apps/storefront/public/`, so a
+ * tenant's public files must land at `apps/storefront/public/tenants/<id>/`
+ * for the `/tenants/<id>/...` URLs to resolve. This script mirrors every tenant's
+ * public directory into that generated location.
+ *
+ * The destination (`apps/storefront/public/tenants/`) is a BUILD ARTIFACT
+ * (gitignored) — the source of truth is `tenants/<id>/public/`. Wired into the
+ * storefront `prebuild`/`predev` lifecycle (package.json) and invoked directly by
+ * `scripts/tot-dev.mjs` before it boots `astro dev`.
+ *
+ * Idempotent: it wipes+rewrites the destination on every run. `TENANT_ASSETS_DEST`
+ * overrides the destination (used by tests / spikes).
+ *
+ * VERSIONED TENANTS (decision `assets-r2-versioned`): a tenant whose assets are
+ * served version-scoped from R2 (src/pages/tenants/[id]/[...path].ts) must NOT be
+ * baked here — otherwise the static file would shadow the R2 route. Opt a tenant
+ * out by adding a `tenants/<id>/.tot/assets-versioned` marker file, or by listing
+ * its id in the `TENANT_ASSETS_VERSIONED` env (comma-separated). Non-versioned
+ * tenants keep the baked path unchanged (back-compat).
+ */
+import { cp, mkdir, readdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const src = resolve(repoRoot, "tenants");
+const dest = process.env.TENANT_ASSETS_DEST
+  ? resolve(process.env.TENANT_ASSETS_DEST)
+  : resolve(repoRoot, "apps/storefront/public/tenants");
+
+if (!existsSync(src)) process.exit(0);
+
+await rm(dest, { recursive: true, force: true });
+
+const versionedEnv = new Set(
+  (process.env.TENANT_ASSETS_VERSIONED ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean),
+);
+const isVersioned = (id) =>
+  versionedEnv.has(id) ||
+  existsSync(join(src, id, ".tot", "assets-versioned"));
+
+let copied = 0;
+let skipped = 0;
+for (const id of await readdir(src)) {
+  const pub = join(src, id, "public");
+  if (!existsSync(pub)) continue;
+  // Versioned tenants are served from R2 — baking would shadow the R2 route.
+  if (isVersioned(id)) {
+    skipped++;
+    continue;
+  }
+  await mkdir(join(dest, id), { recursive: true });
+  await cp(pub, join(dest, id), { recursive: true });
+  copied++;
+}
+
+const skipNote = skipped ? ` (skipped ${skipped} versioned → R2)` : "";
+console.log(
+  `copy-tenant-assets: mirrored ${copied} tenant public/ tree(s) → ${dest}${skipNote}`,
+);