@tokenoftrust/storefront-runner 0.1.0

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,29 @@
+/** 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*$/, "") + "…";
+}

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");
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Image render decision — testable render logic for <Img>.
+ *
+ * Picks the `src` + responsive `srcset` for a catalog image, factored out of
+ * Img.astro so the branching is unit-testable without rendering the component:
+ *   - unusable/missing URL  -> deterministic placeholder data URI
+ *   - rehosted (R2)         -> Cloudflare Image Resizing (/cdn-cgi/image, format=auto)
+ *   - referenced Shopify CDN -> Shopify's native ?width= scheme
+ *   - anything else usable   -> the URL as-is, no srcset
+ */
+import { placeholderDataUri, isUsableImageUrl } from "./placeholder.js";
+import { cfImageUrl, cfImageSrcset, CF_IMAGE_WIDTHS } from "./cfImage.js";
+
+export interface ResolveImageInput {
+  src?: string;
+  rehosted?: boolean;
+  width: number;
+  height: number;
+  /** Placeholder seed (image id / product handle). */
+  seed: string;
+  label?: string;
+}
+
+export interface ResolvedImage {
+  src: string;
+  srcset?: string;
+}
+
+const isShopifyCdnUrl = (url: string): boolean =>
+  /\/\/cdn\.shopify\.com\//.test(url) || /\/cdn\/shop\//.test(url);
+
+export function resolveImage(input: ResolveImageInput): ResolvedImage {
+  const { src, rehosted = false, width, height, seed, label } = input;
+
+  if (!isUsableImageUrl(src, rehosted)) {
+    return { src: placeholderDataUri({ seed, width, height, label }) };
+  }
+  const url = src!;
+
+  // Rehosted (R2) images go through Cloudflare Image Resizing — true resizing +
+  // format=auto (AVIF/WebP).
+  if (rehosted) {
+    return { src: cfImageUrl(url, { width }), srcset: cfImageSrcset(url, width) };
+  }
+
+  // Referenced Shopify CDN URLs already resize via ?width=; keep that scheme.
+  if (isShopifyCdnUrl(url)) {
+    const srcset = CF_IMAGE_WIDTHS.filter((w) => w <= width * 2)
+      .map((w) => `${url}${url.includes("?") ? "&" : "?"}width=${w} ${w}w`)
+      .join(", ");
+    return { src: url, srcset };
+  }
+
+  return { src: url };
+}

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

@@ -0,0 +1,136 @@
+/**
+ * schema.org JSON-LD builders (brief §8): Product (with offers),
+ * BreadcrumbList, Organization. Kept pure so pages compose them and pass to <Seo>.
+ */
+import type { CatalogProduct, TenantConfig } from "@tot/public-runtime";
+import { isAvailable } from "./tot/query.js";
+
+export function organizationLd(tenant: TenantConfig, base: string) {
+  // Logo sourced from the migrated brand assets (og image / logo), so the
+  // Organization schema reflects the real merchant brand, not a generic favicon.
+  const brand = tenant.theme_tokens?.brand;
+  const logo =
+    brand?.ogImage ?? brand?.logoLight ?? new URL("/favicon.svg", base + "/").toString();
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: tenant.displayName,
+    url: base,
+    logo,
+  };
+}
+
+/** ItemList — the ordered products on a collection/PLP page. */
+export function itemListLd(
+  products: CatalogProduct[],
+  base: string,
+  pageOffset = 0,
+) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "ItemList",
+    numberOfItems: products.length,
+    itemListElement: products.map((p, i) => ({
+      "@type": "ListItem",
+      position: pageOffset + i + 1,
+      url: new URL(`/products/${p.handle}`, base + "/").toString(),
+      name: p.title,
+    })),
+  };
+}
+
+/**
+ * WebSite + SearchAction — enables Google's sitelinks search box, wired to the
+ * storefront's own /search?q= endpoint.
+ */
+export function websiteLd(tenant: TenantConfig, base: string) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: tenant.displayName,
+    url: base,
+    potentialAction: {
+      "@type": "SearchAction",
+      target: {
+        "@type": "EntryPoint",
+        urlTemplate: `${base.replace(/\/$/, "")}/search?q={search_term_string}`,
+      },
+      "query-input": "required name=search_term_string",
+    },
+  };
+}
+
+export function breadcrumbLd(
+  crumbs: { label: string; href: string }[],
+  base: string,
+) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: crumbs.map((c, i) => ({
+      "@type": "ListItem",
+      position: i + 1,
+      name: c.label,
+      item: new URL(c.href, base + "/").toString(),
+    })),
+  };
+}
+
+export function productLd(
+  p: CatalogProduct,
+  tenant: TenantConfig,
+  base: string,
+) {
+  const url = new URL(`/products/${p.handle}`, base + "/").toString();
+  const images = p.images
+    .map((i) => i.url)
+    .filter((u) => !/cdn\.shopify\.com/.test(u)); // skip dead fixture URLs
+
+  const offers = p.variants.map((v) => ({
+    "@type": "Offer",
+    sku: v.sku,
+    price: v.price.toFixed(2),
+    priceCurrency: v.currency,
+    availability: v.inventory.available
+      ? "https://schema.org/InStock"
+      : "https://schema.org/OutOfStock",
+    url,
+  }));
+
+  const ratingMf = p.metafields.find(
+    (m) => m.namespace === "reviews" && m.key === "rating",
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: p.title,
+    description: p.seo.description || p.description_text.slice(0, 300),
+    sku: p.variants[0]?.sku,
+    ...(images.length ? { image: images } : {}),
+    ...(p.vendor ? { brand: { "@type": "Brand", name: p.vendor } } : {}),
+    ...(p.product_type ? { category: p.product_type } : {}),
+    offers: {
+      "@type": "AggregateOffer",
+      priceCurrency: p.price_range.currency,
+      lowPrice: p.price_range.min.toFixed(2),
+      highPrice: p.price_range.max.toFixed(2),
+      offerCount: p.variants.length,
+      availability: isAvailable(p)
+        ? "https://schema.org/InStock"
+        : "https://schema.org/OutOfStock",
+      offers,
+    },
+    ...(ratingMf
+      ? {
+          aggregateRating: {
+            "@type": "AggregateRating",
+            ratingValue: ratingMf.value,
+            bestRating: "5",
+            // ASSUMPTION: review count placeholder; real capture is Phase 2.
+            ratingCount: 24,
+          },
+        }
+      : {}),
+  };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Site-wide maintenance kill-switch.
+ *
+ * When `MAINTENANCE_MODE` is truthy the middleware returns {@link maintenanceResponse}
+ * for EVERY host and path — before tenant resolution, the access gate, the edge
+ * cache, or any render. It is a deliberate full close (a "Coming Soon" holding
+ * page), NOT a login gate: auth paths are not exempt, no tenant is resolved, and
+ * nothing tenant-specific is served. Use it as the fail-safe lever to take the
+ * whole storefront offline in one config flip.
+ *
+ * Back online: set `MAINTENANCE_MODE=0` (or unset it) and redeploy.
+ */
+
+/** True for "1" / "on" / "true" / "yes" (case/space-insensitive); false otherwise. */
+export function isMaintenanceOn(raw: string | null | undefined): boolean {
+  const v = (raw ?? "").trim().toLowerCase();
+  return v === "1" || v === "on" || v === "true" || v === "yes";
+}
+
+export const MAINTENANCE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex, nofollow" />
+<title>Coming soon</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex; align-items: center; justify-content: center;
+    min-height: 100%; padding: 2rem;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    background: radial-gradient(1200px 800px at 50% -10%, #1e293b, #0f172a 60%, #020617);
+    color: #e2e8f0;
+  }
+  main { max-width: 34rem; text-align: center; }
+  .badge {
+    display: inline-block; letter-spacing: .18em; text-transform: uppercase;
+    font-size: .72rem; font-weight: 600; color: #94a3b8;
+    border: 1px solid rgba(148,163,184,.35); border-radius: 999px;
+    padding: .35rem .8rem; margin-bottom: 1.75rem;
+  }
+  h1 { font-size: clamp(2rem, 6vw, 3rem); line-height: 1.1; margin: 0 0 1rem; color: #f8fafc; }
+  p { font-size: 1.05rem; line-height: 1.6; color: #cbd5e1; margin: 0 auto; max-width: 28rem; }
+  .rule { width: 3rem; height: 3px; background: #38bdf8; border-radius: 2px; margin: 2rem auto 0; }
+</style>
+</head>
+<body>
+  <main>
+    <span class="badge">Token of Trust</span>
+    <h1>Coming soon</h1>
+    <p>We're putting the finishing touches on the storefront. It'll be back online shortly &mdash; thanks for your patience.</p>
+    <div class="rule"></div>
+  </main>
+</body>
+</html>`;
+
+/** A `503 Service Unavailable` holding page — cached nowhere, never indexed. */
+export function maintenanceResponse(): Response {
+  return new Response(MAINTENANCE_HTML, {
+    status: 503,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "retry-after": "3600",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}

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

@@ -0,0 +1,32 @@
+/**
+ * In-memory KVNamespace for local dev. Lets the real KvTenantResolver + putTenant
+ * run under `astro dev` (where no Cloudflare KV binding exists) so the dynamic
+ * tenant path and a data-driven default are testable without a Cloudflare
+ * account. NOT used in production — the Workers runtime binds the real
+ * TENANT_CACHE namespace. Process-local and non-persistent by design.
+ */
+export class MemoryKv implements KVNamespace {
+  private readonly store = new Map<string, string>();
+
+  async get(key: string): Promise<string | null> {
+    return this.store.has(key) ? (this.store.get(key) as string) : null;
+  }
+
+  async put(key: string, value: string): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async list(
+    opts?: { prefix?: string; cursor?: string; limit?: number },
+  ): Promise<{ keys: { name: string }[]; list_complete: boolean; cursor?: string }> {
+    const prefix = opts?.prefix ?? "";
+    const keys = [...this.store.keys()]
+      .filter((k) => k.startsWith(prefix))
+      .map((name) => ({ name }));
+    return { keys, list_complete: true };
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}

package/apps/storefront/src/lib/messaging/messagesClient.ts

@@ -0,0 +1,143 @@
+/**
+ * MessagesClient — the storefront's seam to tot20's inline-body send (`POST /api/messages`).
+ *
+ * The storefront RENDERS its own branded email HTML and hands it to tot20 to TRANSMIT, so we
+ * reuse tot20's Mandrill SPF/DKIM deliverability (the whole point) while owning the body/brand.
+ * Used for the magic-link invite email (see lib/grants/magicLinkInvite.ts).
+ *
+ *   POST <core>/api/messages
+ *   { channel:"email", to, subject, html, totApiKey, totSecretKey }  → 200 { sent:true, id? }
+ *
+ * Creds go in the BODY (`totApiKey`/`totSecretKey`) — tot20's `normalizeSecureUserRequest`, same
+ * wire rule as the other operator clients. The storefront's operator key already holds
+ * `messaging:send`. DELIVERABILITY: do NOT set a non-`@tokenoftrust.com` From — omit it so the
+ * send stays SPF/DKIM-aligned with tot20's domain (a misaligned From lands in spam).
+ *
+ * Built like `@/lib/grants/developerInvites` (interface + Http impl + Mock + env factory).
+ */
+import { readEnv } from "@/lib/env";
+
+export interface InlineEmail {
+  /** Recipient address. */
+  to: string;
+  /** Subject line (your copy). */
+  subject: string;
+  /** Fully-rendered branded HTML body (your template). */
+  html: string;
+}
+
+export type MessageSendResult =
+  | { sent: true; id?: string }
+  | { sent: false; status: number; reason: string };
+
+export interface MessagesClient {
+  sendInlineEmail(msg: InlineEmail): Promise<MessageSendResult>;
+}
+
+// --- HTTP transport seam (injected by tests) --------------------------------
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+export interface HttpTransport {
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
+}
+export class FetchHttpTransport implements HttpTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    return fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+  }
+}
+
+export class MessagesClientError extends Error {}
+
+export interface HttpMessagesClientConfig {
+  baseUrl: string;
+  apiKey: string;
+  secretKey?: string;
+  transport?: HttpTransport;
+}
+
+export class HttpMessagesClient implements MessagesClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly secretKey?: string;
+  private readonly transport: HttpTransport;
+
+  constructor(config: HttpMessagesClientConfig) {
+    if (!config.baseUrl) throw new MessagesClientError("messages: TOT_CORE_URL is not configured");
+    if (!config.apiKey) throw new MessagesClientError("messages: storefront ToT credentials are not configured");
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.transport = config.transport ?? new FetchHttpTransport();
+  }
+
+  private credentialFields(): Record<string, string> {
+    const f: Record<string, string> = { totApiKey: this.apiKey };
+    if (this.secretKey) f.totSecretKey = this.secretKey;
+    return f;
+  }
+
+  async sendInlineEmail(msg: InlineEmail): Promise<MessageSendResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/messages`,
+        {},
+        {
+          channel: "email",
+          to: msg.to,
+          subject: msg.subject,
+          html: msg.html,
+          // No fromEmail/fromName → stays SPF/DKIM-aligned with tot20's domain (deliverability).
+          ...this.credentialFields(),
+        },
+      );
+    } catch (cause) {
+      return { sent: false, status: 0, reason: cause instanceof Error ? cause.message : String(cause) };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return { sent: false, status: res.status, reason: `non-JSON body (status ${res.status})` };
+    }
+    return normalizeSend(res.status, body);
+  }
+}
+
+/** Parse tot20's `{ content, metadata }` send response into a typed result (fail closed). */
+export function normalizeSend(status: number, body: unknown): MessageSendResult {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const c = (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+  if (c.sent === true || (status >= 200 && status < 300 && c.sent !== false)) {
+    return { sent: true, ...(typeof c.id === "string" ? { id: c.id } : {}) };
+  }
+  const reason =
+    typeof c.message === "string" ? c.message : typeof c.reason === "string" ? c.reason : `send failed (status ${status})`;
+  return { sent: false, status, reason };
+}
+
+// --- Mock (tests + local dev) -----------------------------------------------
+export class MockMessagesClient implements MessagesClient {
+  sent: InlineEmail[] = [];
+  constructor(private readonly result: MessageSendResult = { sent: true, id: "mock-msg" }) {}
+  async sendInlineEmail(msg: InlineEmail): Promise<MessageSendResult> {
+    this.sent.push(msg);
+    return this.result;
+  }
+}
+
+// --- Factory ----------------------------------------------------------------
+export async function createMessagesClient(
+  overrides: Partial<HttpMessagesClientConfig> = {},
+): Promise<HttpMessagesClient> {
+  const baseUrl = overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "";
+  const apiKey = overrides.apiKey ?? (await readEnv("TOT_API_KEY")) ?? "";
+  const secretKey = overrides.secretKey ?? (await readEnv("TOT_SECRET_KEY"));
+  return new HttpMessagesClient({ ...overrides, baseUrl, apiKey, secretKey });
+}