@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

package/apps/storefront/src/lib/apps/orders/foxyOrderClient.ts

@@ -0,0 +1,203 @@
+/**
+ * FoxyOrderClient — the boundary to tot-foxycart's order-read surface
+ * (PrivateApps epic, D6 Chunk A/B). `ordersStore.ts` and the read
+ * routes / event receiver (later chunks) never call `fetch` directly; they go
+ * through this seam so a fake can stand in for tot-foxycart in tests.
+ *
+ * RECONCILED (Chunk B) against the real service —
+ * `tot-foxycart/routes/foxyOrderApi.js` + `modules/integrations/foxyOrderMapper.node.js`:
+ * a `GET {baseUrl}/commerce/orders?appDomain=&limit=&offset=&since=&until=&status=`
+ * list endpoint returning `{ orders, limit, offset, total, hasMore }` (limit/offset,
+ * NOT page/pageSize — chunk A guessed page/pageSize), and a
+ * `GET {baseUrl}/commerce/orders/{externalOrderId}?appDomain=` detail endpoint
+ * returning `{ order }` (an envelope, not the bare order — chunk A guessed bare),
+ * both Bearer-authenticated with the tenant's Foxy partner API key. `FoxyOrder`
+ * below now mirrors `buildOrderPayload()`'s actual normalized DTO — NOT the
+ * contract's minimized `Order` shape (`contract/openapi.yaml`); mapping one to
+ * the other is `orderMapper.ts`'s job.
+ *
+ * Modeled on `../../messaging/messagesClient.ts`'s interface + Http impl +
+ * factory shape and `../../webhooks/deliveryEngine.ts`'s bounded-timeout
+ * `fetch` (AbortController, injectable `fetchImpl`) — but adds a settable
+ * test seam (`setFoxyOrderClientForTesting`) since this client, unlike
+ * `messagesClient.ts`, is a shared singleton multiple later chunks (read
+ * routes, event receiver) will each independently resolve.
+ */
+import { readEnv } from "@/lib/env";
+
+/** One order line item, as tot-foxycart's `buildOrderPayload()` returns it. */
+export interface FoxyOrderLineItem {
+  sku: string;
+  name?: string;
+  quantity: number;
+  unitPrice?: number;
+  totalPrice?: number;
+  /** Collapsed `fx:item_options` ({ name: value }); `flavor` below mirrors the common one. */
+  options?: Record<string, string>;
+  flavor?: string;
+}
+
+/**
+ * One order, as tot-foxycart's `buildOrderPayload()` actually returns it
+ * (`foxyOrderMapper.node.js`). Deliberately does NOT model every upstream
+ * field — `shippingAddress`/`billingAddress`/`paymentRef`/`paymentMetadata`/
+ * `exciseTax` are compliance-floor/PII-adjacent internals the contract's
+ * minimized `Order` never surfaces, so they're left off here rather than
+ * risk a caller reaching for them.
+ *
+ * There is no raw customer id field — only `customerEmail`/`customerName`.
+ * `orderMapper.ts` hashes `customerEmail` (never persisted or forwarded raw)
+ * as the input to `customerHash.ts`.
+ *
+ * `status` is free text passed straight through from Foxy (only `"completed"`
+ * is observed in tot-foxycart's own fixtures; its own fallback is
+ * `"confirmed"`) — NOT the contract's closed `created|fulfilled|cancelled`
+ * enum. `orderMapper.ts` normalizes it.
+ */
+export interface FoxyOrder {
+  /** tot-foxycart's transaction id — this becomes `orders.externalOrderId`. */
+  externalId: string;
+  /** Human-facing order number (Foxy's `display_id`). */
+  externalNumber?: string;
+  /** ISO 8601-*like* — Foxy's offset omits the colon (`-0500` not `-05:00`). */
+  orderedAt: string;
+  currency: string;
+  status: string;
+  customerEmail?: string;
+  customerName?: string;
+  subtotal?: number;
+  shipping?: number;
+  tax?: number;
+  total: number;
+  lineItems: FoxyOrderLineItem[];
+}
+
+export interface FoxyOrderPage {
+  orders: FoxyOrder[];
+  limit: number;
+  offset: number;
+  total: number;
+  hasMore: boolean;
+}
+
+export interface FoxyOrderListOptions {
+  limit?: number;
+  offset?: number;
+  since?: string;
+  until?: string;
+  status?: string;
+}
+
+export interface FoxyOrderClient {
+  /** List orders for one tenant (identified by its Foxy-facing `appDomain`). */
+  listOrders(tenantAppDomain: string, options?: FoxyOrderListOptions): Promise<FoxyOrderPage>;
+  /** Fetch one order by tot-foxycart's id, or `null` if it doesn't exist. */
+  getOrder(tenantAppDomain: string, externalOrderId: string): Promise<FoxyOrder | null>;
+}
+
+export class FoxyOrderClientError extends Error {}
+
+/** Bounded per-request timeout — mirrors `deliveryEngine.ts`'s `DEFAULT_TIMEOUT_MS`. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+const FOXY_ORDER_API_URL_ENV = "FOXY_ORDER_API_URL";
+const FOXY_ORDER_API_KEY_ENV = "FOXY_ORDER_API_KEY";
+
+export interface HttpFoxyOrderClientConfig {
+  /** tot-foxycart base URL (e.g. `https://commerce.tokenoftrust.com`). No trailing slash required. */
+  baseUrl: string;
+  /** Per-store Foxy partner API key, sent as a Bearer token. */
+  apiKey: string;
+  /** Defaults to the global `fetch`. Override in tests with a fake. */
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export class HttpFoxyOrderClient implements FoxyOrderClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+
+  constructor(config: HttpFoxyOrderClientConfig) {
+    if (!config.baseUrl) throw new FoxyOrderClientError("foxyOrderClient: FOXY_ORDER_API_URL is not configured");
+    if (!config.apiKey) throw new FoxyOrderClientError("foxyOrderClient: FOXY_ORDER_API_KEY is not configured");
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.fetchImpl = config.fetchImpl ?? fetch;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  async listOrders(tenantAppDomain: string, options: FoxyOrderListOptions = {}): Promise<FoxyOrderPage> {
+    const params = new URLSearchParams({ appDomain: tenantAppDomain });
+    if (options.limit != null) params.set("limit", String(options.limit));
+    if (options.offset != null) params.set("offset", String(options.offset));
+    if (options.since != null) params.set("since", options.since);
+    if (options.until != null) params.set("until", options.until);
+    if (options.status != null) params.set("status", options.status);
+    return this.request<FoxyOrderPage>(`/commerce/orders?${params}`);
+  }
+
+  async getOrder(tenantAppDomain: string, externalOrderId: string): Promise<FoxyOrder | null> {
+    const params = new URLSearchParams({ appDomain: tenantAppDomain });
+    const result = await this.request<{ order: FoxyOrder } | null>(
+      `/commerce/orders/${encodeURIComponent(externalOrderId)}?${params}`,
+      { allowNotFound: true },
+    );
+    return result ? result.order : null;
+  }
+
+  private async request<T>(path: string, opts: { allowNotFound?: boolean } = {}): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res: Response;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${this.apiKey}`, accept: "application/json" },
+        signal: controller.signal,
+      });
+    } catch (cause) {
+      const isTimeout = cause instanceof Error && cause.name === "AbortError";
+      throw new FoxyOrderClientError(
+        `foxyOrderClient: request to ${path} failed (${isTimeout ? "timeout" : "network error"})`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (opts.allowNotFound && res.status === 404) return null as T;
+    if (!res.ok) {
+      throw new FoxyOrderClientError(`foxyOrderClient: ${path} returned ${res.status}`);
+    }
+    return (await res.json()) as T;
+  }
+}
+
+// --- Test seam ---------------------------------------------------------------
+// Later chunks (read routes, event receiver) each resolve their own client
+// instance via `getFoxyOrderClient()`; a module-level override lets a single
+// `setFoxyOrderClientForTesting` call stand in for tot-foxycart across all of
+// them in one test, without threading a fake through every call site.
+let testOverride: FoxyOrderClient | null = null;
+
+export function setFoxyOrderClientForTesting(client: FoxyOrderClient): void {
+  testOverride = client;
+}
+
+export function resetFoxyOrderClientForTesting(): void {
+  testOverride = null;
+}
+
+/**
+ * Resolve the active `FoxyOrderClient`: the test override if one is set,
+ * otherwise a real `HttpFoxyOrderClient` built from env (fails closed —
+ * throws {@link FoxyOrderClientError} — when unconfigured).
+ */
+export async function getFoxyOrderClient(
+  overrides: Partial<HttpFoxyOrderClientConfig> = {},
+): Promise<FoxyOrderClient> {
+  if (testOverride) return testOverride;
+  const baseUrl = overrides.baseUrl ?? (await readEnv(FOXY_ORDER_API_URL_ENV)) ?? "";
+  const apiKey = overrides.apiKey ?? (await readEnv(FOXY_ORDER_API_KEY_ENV)) ?? "";
+  return new HttpFoxyOrderClient({ ...overrides, baseUrl, apiKey });
+}

package/apps/storefront/src/lib/apps/orders/idempotency.ts

@@ -0,0 +1,100 @@
+/**
+ * Idempotency-Key ledger — PrivateApps epic, D6 (Chunk C). Backs the
+ * `idempotency_keys` table `schema.ts` declares: the FIRST real (not
+ * presence-only) idempotency ledger in this codebase, and the one
+ * `POST /attribution` (`docs/private-apps/contract/openapi.yaml`'s
+ * `writeAttribution`) requires — a reused key with a body hash that doesn't
+ * match the one first stored is a 409, not a silent overwrite or a second
+ * row. Contrast D4's replay endpoint (`webhooks/deliveries/{id}/replay.ts`),
+ * which only checks the header's presence because it has no request body to
+ * hash and no table backing it yet.
+ *
+ * Pure over the `Queryable` seam, same shape every other D6 store uses.
+ * Route-agnostic by design: `attribution.ts` is the first caller, but any
+ * future idempotent write route can reuse this unchanged.
+ */
+import { sha256Hex } from "@tot/public-runtime";
+import type { Queryable } from "../../d1/catalog.js";
+
+export type IdempotencyCheck =
+  | { status: "proceed" }
+  | { status: "replay"; responseBody: unknown }
+  | { status: "conflict" };
+
+interface IdempotencyKeyRow {
+  install_id: string;
+  idempotency_key: string;
+  body_hash: string;
+  response_body: string;
+  created_at: string;
+}
+
+/**
+ * Recursively sort object keys before `JSON.stringify` so two requests with
+ * the same logical content — but different key order or whitespace — hash
+ * identically. Arrays keep their order (order is meaningful there).
+ */
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[key] = canonicalize((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+/** Hash a request body into the `bodyHash` the ledger keys idempotency on. */
+export function computeBodyHash(body: unknown): Promise<string> {
+  return sha256Hex(JSON.stringify(canonicalize(body)));
+}
+
+/**
+ * Look up a prior `(installId, idempotencyKey)` write. A matching
+ * `bodyHash` is a stable replay — the caller should return the ORIGINAL
+ * response body, not re-run the write, so a retried request gets back
+ * exactly what the first one produced. A mismatched `bodyHash` is a
+ * conflict: the same key was reused for a genuinely different request. No
+ * row at all is a green light to proceed.
+ */
+export async function checkIdempotency(
+  db: Queryable,
+  installId: string,
+  idempotencyKey: string,
+  bodyHash: string,
+): Promise<IdempotencyCheck> {
+  const row = await db.first<IdempotencyKeyRow>(
+    `SELECT * FROM idempotency_keys WHERE install_id = ? AND idempotency_key = ?`,
+    installId,
+    idempotencyKey,
+  );
+  if (!row) return { status: "proceed" };
+  if (row.body_hash !== bodyHash) return { status: "conflict" };
+  return { status: "replay", responseBody: JSON.parse(row.response_body) };
+}
+
+/**
+ * Record a fresh `(installId, idempotencyKey)` write alongside the response
+ * body a replay should return. Callers run this AFTER the write it guards
+ * succeeds, never before — a failed write must leave no idempotency row
+ * behind to (wrongly) short-circuit a legitimate retry.
+ */
+export async function recordIdempotency(
+  db: Queryable,
+  installId: string,
+  idempotencyKey: string,
+  bodyHash: string,
+  responseBody: unknown,
+): Promise<void> {
+  await db.run(
+    `INSERT INTO idempotency_keys (install_id, idempotency_key, body_hash, response_body, created_at)
+     VALUES (?,?,?,?,?)`,
+    installId,
+    idempotencyKey,
+    bodyHash,
+    JSON.stringify(responseBody),
+    new Date().toISOString(),
+  );
+}

package/apps/storefront/src/lib/apps/orders/orderForwardReceiver.ts

@@ -0,0 +1,117 @@
+/**
+ * Inbound order-forward receiver — PrivateApps epic, D6 (Chunk D). The
+ * transport-free core `pages/api/apps/internal/order-forward.ts` calls once
+ * it has verified the HMAC signature: given one reconciled order from
+ * tot-foxycart, upsert it into `ordersStore.ts` and decide whether that write
+ * is worth telling the world about.
+ *
+ * `docs/private-apps/order-forward-contract.md` is the normative spec this
+ * module implements — read that first for the wire shape; this file is the
+ * decision logic only.
+ *
+ * Emit decision (idempotent — a re-forward of the same status is a no-op,
+ * never a duplicate event; see `ordersStore.ts`'s `upsertOrder` header for
+ * why `previousStatus` is the signal, not a second read):
+ *   - brand-new row (`previousStatus === null`) -> `order.created`, always;
+ *     if it arrives already `fulfilled` (e.g. instant digital fulfillment),
+ *     ALSO `order.fulfilled` — both transitions genuinely happened, just
+ *     collapsed into one delivery.
+ *   - existing row, `created` -> `fulfilled` -> `order.fulfilled`.
+ *   - anything else (same status re-forwarded, or a transition with no
+ *     corresponding topic — e.g. -> `cancelled`, which V1 has no topic for)
+ *     -> no emit; the row still updates, silently.
+ *
+ * Customer identity: `rawCustomerId` is optional (tot-foxycart's own
+ * order-forward payload doesn't always carry one — mirrors `FoxyOrder`'s
+ * own optional `customerEmail`). This receiver never derives, stores, or
+ * emits a hash from it: `orders` rows here have no `installId` (this is a
+ * tenant-wide write, not an install-owned one), so `customerHash.ts`'s
+ * per-(tenant,install) `customerHash` doesn't fit — and per decision
+ * `orders-event-customer-hash-omitted`, a fan-out event carries NO customer
+ * hash at all, not even a coarser per-tenant one, so there's nothing to
+ * compute one FOR either. `rawCustomerId` is accepted and simply unused;
+ * see `docs/private-apps/order-forward-contract.md` for the full rationale.
+ */
+import { OrdersStore, type OrderLineItem, type OrderStatus, type Order } from "./ordersStore.js";
+import { emitWebhookEvent } from "../../webhooks/emit.js";
+import type { WebhookTopic } from "../../webhooks/deliveryStore.js";
+import type { Queryable } from "../../d1/catalog.js";
+
+/** One reconciled order, as tot-foxycart forwards it. See the contract doc for the wire (JSON) shape. */
+export interface OrderForwardInput {
+  tenantId: string;
+  externalOrderId: string;
+  env: string;
+  status: OrderStatus;
+  currency: string;
+  total: number;
+  subtotal?: number;
+  lineItems: OrderLineItem[];
+  /** Raw, tenant-scoped customer identifier. Accepted but unused — see the module doc's "Customer identity" note; never stored or emitted, raw or hashed. */
+  rawCustomerId?: string;
+  /** ISO timestamp the order was actually created at tot-foxycart. Defaults to receipt time when omitted (e.g. a backfill missing it) — only matters for a brand-new row; ignored on an update. */
+  createdAt?: string;
+}
+
+export interface OrderForwardResult {
+  order: Order;
+  previousStatus: OrderStatus | null;
+  /** Topics actually emitted, in emit order — `[]` for a no-op re-forward. */
+  emitted: WebhookTopic[];
+}
+
+/** The `OrderData` wire shape (`contract/asyncapi.yaml`) — never the internal snake_case row. */
+function toOrderData(order: Order): Record<string, unknown> {
+  const data: Record<string, unknown> = {
+    id: order.externalOrderId,
+    status: order.status,
+    currency: order.currency,
+    lineItems: order.lineItems,
+    total: order.total,
+  };
+  if (order.subtotal != null) data.subtotal = order.subtotal;
+  // No customerHash field, ever — decision orders-event-customer-hash-omitted:
+  // a tenant-wide fan-out has no single install to salt a hash against, and a
+  // coarser per-tenant hash is deliberately not used as a substitute.
+  return data;
+}
+
+/** Which topics this upsert's status transition warrants — `[]` for none. */
+function topicsFor(previousStatus: OrderStatus | null, status: OrderStatus): WebhookTopic[] {
+  if (previousStatus === null) {
+    return status === "fulfilled" ? ["order.created", "order.fulfilled"] : ["order.created"];
+  }
+  if (previousStatus === "created" && status === "fulfilled") return ["order.fulfilled"];
+  return [];
+}
+
+/**
+ * Upsert one forwarded order and emit whatever topics its status transition
+ * warrants. The caller (the route) is responsible for having already
+ * verified the request's HMAC signature — this function never re-checks
+ * authenticity and must never be reached from an unverified request.
+ */
+export async function receiveForwardedOrder(db: Queryable, input: OrderForwardInput): Promise<OrderForwardResult> {
+  const store = new OrdersStore(db);
+  // input.rawCustomerId is intentionally not read here — see the module doc's
+  // "Customer identity" note for why no hash is derived from it.
+
+  const { previousStatus, order } = await store.upsertOrder({
+    tenantId: input.tenantId,
+    externalOrderId: input.externalOrderId,
+    env: input.env,
+    status: input.status,
+    currency: input.currency,
+    total: input.total,
+    subtotal: input.subtotal ?? null,
+    lineItems: input.lineItems,
+    createdAt: input.createdAt ?? new Date().toISOString(),
+  });
+
+  const emitted = topicsFor(previousStatus, input.status);
+  for (const topic of emitted) {
+    await emitWebhookEvent(topic, input.tenantId, toOrderData(order), {});
+  }
+
+  return { order, previousStatus, emitted };
+}

package/apps/storefront/src/lib/apps/orders/orderMapper.ts

@@ -0,0 +1,91 @@
+/**
+ * Pure mapper: `FoxyOrderClient`'s `FoxyOrder` (tot-foxycart's normalized
+ * transaction DTO) -> the contract's minimized `Order` shape (PrivateApps
+ * epic, D6 Chunk B; `docs/private-apps/contract/openapi.yaml`'s `Order`).
+ *
+ * Drops everything the contract's `additionalProperties: false` Order
+ * doesn't declare — no raw checkout payload, no signed-cart material, no tax
+ * internals — and never lets a raw customer identifier leave this module:
+ * customer identity is always the per-(tenant, install) `customerHash`.
+ */
+import { customerHash } from "./customerHash.js";
+import type { FoxyOrder, FoxyOrderLineItem } from "./foxyOrderClient.js";
+
+export type ContractOrderStatus = "created" | "fulfilled" | "cancelled";
+
+export interface ContractOrderLineItem {
+  sku: string;
+  handle?: string;
+  quantity: number;
+  lineTotal?: number;
+}
+
+export interface ContractOrder {
+  id: string;
+  status: ContractOrderStatus;
+  currency: string;
+  customerHash: string;
+  subtotal?: number;
+  total?: number;
+  lineItems?: ContractOrderLineItem[];
+  createdAt: string;
+  fulfilledAt?: string;
+}
+
+export interface ToContractOrderContext {
+  tenantId: string;
+  installId: string;
+}
+
+/**
+ * Foxy's transaction `status` is free text passed straight through by
+ * `buildOrderPayload()` (only `"completed"` is observed in tot-foxycart's own
+ * fixtures; its own fallback is `"confirmed"`) — there is no fulfillment/
+ * shipping signal in the normalized DTO at all, so this mapper can only ever
+ * tell a cancelled-ish terminal state apart from everything else. `fulfilled`
+ * is never produced here; flagged to the team as a gap (may need a separate
+ * signal, e.g. a shipment event, once one exists).
+ */
+const CANCELLED_STATUS_TOKENS = new Set(["cancelled", "canceled", "refunded", "voided", "rejected", "declined"]);
+
+function toContractStatus(foxyStatus: string): ContractOrderStatus {
+  return CANCELLED_STATUS_TOKENS.has(foxyStatus.toLowerCase()) ? "cancelled" : "created";
+}
+
+/**
+ * Foxy's `transaction_date` omits the timezone-offset colon (`-0500`, not
+ * `-05:00`), which some strict RFC 3339 validators reject. Round-trip through
+ * `Date` to normalize to a UTC ISO string; falls back to the raw value on an
+ * unparseable input rather than throwing (a read route shouldn't 500 over a
+ * date it can't fully trust).
+ */
+function toIsoDateTime(foxyDate: string): string {
+  const parsed = new Date(foxyDate);
+  return Number.isNaN(parsed.getTime()) ? foxyDate : parsed.toISOString();
+}
+
+function toContractLineItem(item: FoxyOrderLineItem): ContractOrderLineItem {
+  return {
+    sku: item.sku,
+    quantity: item.quantity,
+    lineTotal: item.totalPrice,
+  };
+}
+
+/**
+ * Map one `FoxyOrder` to the contract `Order` shape. `customerEmail` is the
+ * only customer identifier tot-foxycart's DTO exposes (no raw customer id) —
+ * it's hashed here and never appears in the returned shape.
+ */
+export async function toContractOrder(order: FoxyOrder, ctx: ToContractOrderContext): Promise<ContractOrder> {
+  return {
+    id: order.externalId,
+    status: toContractStatus(order.status),
+    currency: order.currency,
+    customerHash: await customerHash(ctx.tenantId, ctx.installId, order.customerEmail ?? order.externalId),
+    subtotal: order.subtotal,
+    total: order.total,
+    lineItems: order.lineItems.map(toContractLineItem),
+    createdAt: toIsoDateTime(order.orderedAt),
+  };
+}

package/apps/storefront/src/lib/apps/orders/ordersStore.ts

@@ -0,0 +1,181 @@
+/**
+ * `orders` read-model store — PrivateApps epic, D6 (Chunk A). Owns the
+ * `orders` rows `schema.ts` declares: the diffing surface a later chunk's
+ * event emission reads (`upsertOrder`'s returned `previousStatus` is how it
+ * detects a created→fulfilled transition without a second query) and the
+ * lookup surface the attribution route (also later) uses for its cross-tenant
+ * ownership check.
+ *
+ * Pure over the `Queryable` seam (see `../../d1/catalog.ts`) — same shape
+ * `AppRegistryService` uses, so this runs unchanged against real D1 in the
+ * Worker and an in-memory `node:sqlite` in tests.
+ */
+import type { Queryable } from "../../d1/catalog.js";
+
+export type OrderStatus = "created" | "fulfilled" | "cancelled";
+
+/** One order line item (JSON-as-text in the row; see `Order.lineItems` in the contract). */
+export interface OrderLineItem {
+  sku: string;
+  handle?: string;
+  quantity: number;
+  lineTotal?: number;
+}
+
+/** Domain shape of one `orders` row. */
+export interface Order {
+  tenantId: string;
+  externalOrderId: string;
+  env: string;
+  status: OrderStatus;
+  currency: string;
+  total: number;
+  subtotal: number | null;
+  customerHash: string | null;
+  lineItems: OrderLineItem[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** What `upsertOrder` takes — same shape as `Order` but `updatedAt` is optional (defaults to now). */
+export interface UpsertOrderInput {
+  tenantId: string;
+  externalOrderId: string;
+  env: string;
+  status: OrderStatus;
+  currency: string;
+  total: number;
+  subtotal?: number | null;
+  customerHash?: string | null;
+  lineItems: OrderLineItem[];
+  createdAt: string;
+  updatedAt?: string;
+}
+
+/**
+ * `upsertOrder`'s return: the row's status BEFORE this write (`null` for a
+ * brand-new order) alongside the row as it now stands — the diffing signal a
+ * later chunk's event emission needs to tell "just created" apart from
+ * "created → fulfilled" apart from "no-op re-delivery of the same status",
+ * without a second round trip.
+ */
+export interface UpsertOrderResult {
+  previousStatus: OrderStatus | null;
+  order: Order;
+}
+
+/** Raw `orders` row shape (snake_case columns, JSON-as-text). */
+interface OrderRow {
+  tenant_id: string;
+  external_order_id: string;
+  env: string;
+  status: string;
+  currency: string;
+  total: number;
+  subtotal: number | null;
+  customer_hash: string | null;
+  line_items: string;
+  created_at: string;
+  updated_at: string;
+}
+
+function toDomain(row: OrderRow): Order {
+  return {
+    tenantId: row.tenant_id,
+    externalOrderId: row.external_order_id,
+    env: row.env,
+    status: row.status as OrderStatus,
+    currency: row.currency,
+    total: row.total,
+    subtotal: row.subtotal,
+    customerHash: row.customer_hash,
+    lineItems: JSON.parse(row.line_items) as OrderLineItem[],
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export class OrdersStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  /**
+   * Insert a brand-new order, or update an existing one keyed by
+   * `(tenantId, externalOrderId)` — a re-delivered/replayed event for the
+   * same order is idempotent (last-write-wins on the mutable fields), not a
+   * duplicate row. Reads the prior row FIRST so `previousStatus` reflects
+   * what was there before this write, not after.
+   */
+  async upsertOrder(input: UpsertOrderInput): Promise<UpsertOrderResult> {
+    const existing = await this.getOrder(input.tenantId, input.externalOrderId);
+    const updatedAt = input.updatedAt ?? this.now();
+
+    if (existing) {
+      await this.db.run(
+        `UPDATE orders
+            SET env = ?, status = ?, currency = ?, total = ?, subtotal = ?,
+                customer_hash = ?, line_items = ?, updated_at = ?
+          WHERE tenant_id = ? AND external_order_id = ?`,
+        input.env,
+        input.status,
+        input.currency,
+        input.total,
+        input.subtotal ?? null,
+        input.customerHash ?? null,
+        JSON.stringify(input.lineItems),
+        updatedAt,
+        input.tenantId,
+        input.externalOrderId,
+      );
+    } else {
+      await this.db.run(
+        `INSERT INTO orders
+           (tenant_id, external_order_id, env, status, currency, total, subtotal,
+            customer_hash, line_items, created_at, updated_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?)`,
+        input.tenantId,
+        input.externalOrderId,
+        input.env,
+        input.status,
+        input.currency,
+        input.total,
+        input.subtotal ?? null,
+        input.customerHash ?? null,
+        JSON.stringify(input.lineItems),
+        input.createdAt,
+        updatedAt,
+      );
+    }
+
+    const order = await this.getOrder(input.tenantId, input.externalOrderId);
+    return { previousStatus: existing?.status ?? null, order: order! };
+  }
+
+  /** Read one order, scoped to the caller's own tenant. */
+  async getOrder(tenantId: string, externalOrderId: string): Promise<Order | null> {
+    const row = await this.db.first<OrderRow>(
+      `SELECT * FROM orders WHERE tenant_id = ? AND external_order_id = ?`,
+      tenantId,
+      externalOrderId,
+    );
+    return row ? toDomain(row) : null;
+  }
+
+  /**
+   * Look up an order by `externalOrderId` alone, with NO tenant scoping —
+   * for the attribution route's cross-tenant ownership check (contract:
+   * "MUST belong to the calling tenant/install; a cross-tenant orderId is
+   * rejected with 403"), which needs to learn WHICH tenant an order belongs
+   * to before it can compare that against the caller. Never expose this
+   * result to a caller without checking `order.tenantId` first.
+   */
+  async getByExternalId(externalOrderId: string): Promise<Order | null> {
+    const row = await this.db.first<OrderRow>(
+      `SELECT * FROM orders WHERE external_order_id = ? LIMIT 1`,
+      externalOrderId,
+    );
+    return row ? toDomain(row) : null;
+  }
+}