@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -1,18 +1,18 @@
 /**
- * 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.
+ * FoxyOrderClient — the boundary to tot-foxycart's order-read surface.
+ * `ordersStore.ts` and the read routes / event receiver 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`:
+ * The service is `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
+ * NOT page/pageSize), and a
  * `GET {baseUrl}/commerce/orders/{externalOrderId}?appDomain=` detail endpoint
- * returning `{ order }` (an envelope, not the bare order — chunk A guessed bare),
+ * returning `{ order }` (an envelope, not the bare order),
  * both Bearer-authenticated with the tenant's Foxy partner API key. `FoxyOrder`
- * below now mirrors `buildOrderPayload()`'s actual normalized DTO — NOT the
+ * below 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.
  *
@@ -20,8 +20,8 @@
  * 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.
+ * `messagesClient.ts`, is a shared singleton that multiple callers (read
+ * routes, event receiver) each independently resolve.
  */
 import { readEnv } from "@/lib/env";
 
@@ -174,7 +174,7 @@ export class HttpFoxyOrderClient implements FoxyOrderClient {
 }
 
 // --- Test seam ---------------------------------------------------------------
-// Later chunks (read routes, event receiver) each resolve their own client
+// Callers (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.

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

@@ -1,17 +1,17 @@
 /**
- * Idempotency-Key ledger — PrivateApps epic, D6 (Chunk C). Backs the
- * `idempotency_keys` table `schema.ts` declares: the FIRST real (not
+ * Idempotency-Key ledger. Backs the
+ * `idempotency_keys` table `schema.ts` declares: the one 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`),
+ * row. Contrast the webhook 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.
+ * hash and no table backing it.
  *
- * 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.
+ * Pure over the `Queryable` seam, same shape every other orders store uses.
+ * Route-agnostic by design: `attribution.ts` is one caller, but any
+ * idempotent write route can reuse this.
  */
 import { sha256Hex } from "@tot/public-runtime";
 import type { Queryable } from "../../d1/catalog.js";

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

@@ -0,0 +1,150 @@
+/**
+ * The D1-backed durable seams the verified-order conversion join
+ * (`@tot/public-runtime`'s `computeOrderConversion`) needs in the Worker, plus the
+ * thin wrapper the order-forward receiver route calls to run the join.
+ *
+ * Two durable stores on `STOREFRONT_APPS_DB` (the same D1 the order rows live in, so
+ * attribution and the order it attributes share one database):
+ *   - `correlation_replay` — the single-use `jti` ledger behind the injected
+ *     {@link CorrelationReplayGuard}: a correlation token is honored exactly once, and
+ *     a replay of a consumed `jti` is refused. Rows are pruned once past their `exp`
+ *     (a past-`exp` token is already rejected `expired` before the guard is reached).
+ *   - `order_attribution` — the per-`(tenant, orderId)` attribution ledger: the order's
+ *     attribution is fixed on its first conversion and reused for later lifecycle events.
+ *
+ * Both run over the `Queryable` seam, so they serve real D1 in the Worker and an
+ * in-memory `node:sqlite` in tests unchanged.
+ */
+import type { Queryable } from "../../d1/catalog.js";
+import { readEnv } from "@/lib/env";
+import {
+  computeOrderConversion,
+  resolveConversionEnvironment,
+  readEchoedCorrelation,
+  type CorrelationReplayGuard,
+  type OrderConversionAttributionStore,
+  type OrderConversionResult,
+  type StoredAttribution,
+} from "@tot/public-runtime";
+import type { OrderForwardInput, OrderForwardResult } from "./orderForwardReceiver.js";
+
+/** The server-only correlation-signing key binding, distinct from the cart secret. */
+const CORRELATION_SECRET_ENV = "COMMERCE_CORRELATION_SECRET";
+
+/**
+ * Durable single-use `jti` guard over `correlation_replay`. `seen` is an existence
+ * check; `remember` prunes any past-`exp` rows (bounded growth) then records the `jti`
+ * idempotently.
+ */
+export class D1CorrelationReplayGuard implements CorrelationReplayGuard {
+  constructor(
+    private readonly db: Queryable,
+    private readonly nowSec: () => number = () => Math.floor(Date.now() / 1000),
+  ) {}
+
+  async seen(jti: string): Promise<boolean> {
+    const row = await this.db.first<{ one: number }>(
+      `SELECT 1 AS one FROM correlation_replay WHERE jti = ?`,
+      jti,
+    );
+    return row != null;
+  }
+
+  async remember(jti: string, expiresAtSec: number): Promise<void> {
+    const now = this.nowSec();
+    await this.db.run(`DELETE FROM correlation_replay WHERE expires_at <= ?`, now);
+    await this.db.run(
+      `INSERT OR IGNORE INTO correlation_replay (jti, expires_at, consumed_at) VALUES (?, ?, ?)`,
+      jti,
+      expiresAtSec,
+      new Date(now * 1000).toISOString(),
+    );
+  }
+}
+
+interface OrderAttributionRow {
+  attributed: number;
+  correlation_id: string | null;
+  correlation_expires_at: string | null;
+  reason: string | null;
+}
+
+/** Durable per-`(tenant, orderId)` attribution ledger over `order_attribution`. */
+export class D1OrderConversionAttributionStore implements OrderConversionAttributionStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  async get(tenant: string, orderId: string): Promise<StoredAttribution | null> {
+    const row = await this.db.first<OrderAttributionRow>(
+      `SELECT attributed, correlation_id, correlation_expires_at, reason
+         FROM order_attribution WHERE tenant_id = ? AND external_order_id = ?`,
+      tenant,
+      orderId,
+    );
+    return row ? toStored(row) : null;
+  }
+
+  async putIfAbsent(
+    tenant: string,
+    orderId: string,
+    record: StoredAttribution,
+  ): Promise<StoredAttribution> {
+    await this.db.run(
+      `INSERT OR IGNORE INTO order_attribution
+         (tenant_id, external_order_id, attributed, correlation_id, correlation_expires_at, reason, recorded_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      tenant,
+      orderId,
+      record.attributed ? 1 : 0,
+      record.correlationId,
+      record.correlationExpiresAt,
+      record.reason,
+      this.now(),
+    );
+    // Return the EFFECTIVE row: a concurrent first-writer's record wins over this one.
+    const stored = await this.get(tenant, orderId);
+    return stored ?? record;
+  }
+}
+
+function toStored(row: OrderAttributionRow): StoredAttribution {
+  return {
+    attributed: row.attributed === 1,
+    correlationId: row.correlation_id,
+    correlationExpiresAt: row.correlation_expires_at,
+    reason: (row.reason as StoredAttribution["reason"]) ?? null,
+  };
+}
+
+/**
+ * Run the verified-order → server conversion join for one forwarded order: read the
+ * echoed correlation the provider carried back, resolve the durable guard + attribution
+ * ledger over `db`, and produce the canonical server conversion event(s) plus the
+ * explicit attribution outcome. The correlation is verified against the ORDER's own
+ * tenant/environment, so a cross-tenant/stage token can never attribute.
+ */
+export async function joinForwardedOrderConversion(
+  db: Queryable,
+  input: OrderForwardInput,
+  receiverResult: OrderForwardResult,
+): Promise<OrderConversionResult> {
+  const correlationSecret = await readEnv(CORRELATION_SECRET_ENV);
+  return computeOrderConversion({
+    order: {
+      tenant: input.tenantId,
+      externalOrderId: input.externalOrderId,
+      status: receiverResult.order.status,
+      currency: input.currency,
+      total: input.total,
+      lineItems: input.lineItems,
+    },
+    environment: resolveConversionEnvironment(input.env),
+    emittedTopics: receiverResult.emitted,
+    echoedCorrelation: readEchoedCorrelation(input.providerFields),
+    correlationSecret,
+    guard: new D1CorrelationReplayGuard(db),
+    attributionStore: new D1OrderConversionAttributionStore(db),
+  });
+}

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

@@ -1,5 +1,5 @@
 /**
- * Inbound order-forward receiver — PrivateApps epic, D6 (Chunk D). The
+ * Inbound order-forward receiver. 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
@@ -51,6 +51,14 @@ export interface OrderForwardInput {
   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;
+  /** The provider's echoed custom cart fields (e.g. `h:tot_correlation`) the order-conversion join reads the correlation token from. Absent → the conversion is explicitly unattributed. */
+  providerFields?: Record<string, unknown>;
+  /** Opaque provider event identity. Missing legacy forwards are never measured. */
+  providerEventId?: string;
+  /** Exact provider event instant; measurement rejects non-canonical/missing values. */
+  occurredAt?: string;
+  /** Provider-authoritative non-negative minor-unit total; no float conversion is used. */
+  amountMinor?: number;
 }
 
 export interface OrderForwardResult {

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

@@ -1,7 +1,7 @@
 /**
  * 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`).
+ * transaction DTO) -> the contract's minimized `Order` shape
+ * (`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

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

@@ -1,9 +1,9 @@
 /**
- * `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
+ * `orders` read-model store. Owns the
+ * `orders` rows `schema.ts` declares: the diffing surface the 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
+ * lookup surface the attribution route uses for its cross-tenant
  * ownership check.
  *
  * Pure over the `Queryable` seam (see `../../d1/catalog.ts`) — same shape
@@ -12,7 +12,7 @@
  */
 import type { Queryable } from "../../d1/catalog.js";
 
-export type OrderStatus = "created" | "fulfilled" | "cancelled";
+export type OrderStatus = "created" | "fulfilled" | "refunded" | "cancelled";
 
 /** One order line item (JSON-as-text in the row; see `Order.lineItems` in the contract). */
 export interface OrderLineItem {
@@ -54,8 +54,8 @@ export interface UpsertOrderInput {
 
 /**
  * `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
+ * brand-new order) alongside the row as it now stands — the diffing signal the
+ * 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.
  */

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

@@ -0,0 +1,117 @@
+/** Durable WS4 adapter for the already HMAC-verified Foxy order-forward path.
+ * It has no browser, GTM, dataLayer, receipt-DOM, destination, or admin capability.
+ * The caller catches every error, so a measurement-store outage cannot block commerce. */
+import {
+  intentFromVerifiedProviderTruth,
+} from "../../../../../../packages/public-runtime/src/regulated-commerce/provider-order/bridge.js";
+import {
+  parseVerifiedOrderTruth,
+  resolveVerifiedOrderTruth,
+  verifiedOrderTruthFingerprint,
+  type VerifiedOrderSnapshot,
+  type VerifiedOrderTruth,
+  type VerifiedOrderTruthResolution,
+} from "../../../../../../packages/public-runtime/src/regulated-commerce/purchase-truth/contract.js";
+import type { RegulatedCommerceIntent } from "../../../../../../packages/public-runtime/src/regulated-commerce/events/contract.js";
+import type { Queryable } from "../../d1/catalog.js";
+import type { OrderForwardInput } from "./orderForwardReceiver.js";
+
+const FOXY_PROVIDER = "foxycart";
+const LIVE_ENVS = new Set(["live", "production"]);
+type ProviderEventRow = { fingerprint: string; receipt_id: string };
+type ProviderOrderRow = { provider: string; provider_order_id: string; tenant_id: string; state: "purchased" | "refunded" | "cancelled" };
+
+export type VerifiedProviderMeasurementOutcome =
+  | "recorded" | "duplicate" | "replay-conflict" | "stale-transition" | "ignored-non-live" | "ignored-malformed";
+export interface VerifiedProviderMeasurementResult { readonly outcome: VerifiedProviderMeasurementOutcome; readonly intent: RegulatedCommerceIntent | null; }
+
+function snapshot(row: ProviderOrderRow | null): VerifiedOrderSnapshot | null {
+  return row ? { provider: row.provider, providerOrderId: row.provider_order_id, tenant: row.tenant_id, state: row.state } : null;
+}
+function isIsoInstant(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
+}
+
+/** Missing event identity/minor units fails closed. Legacy forwards still ACK as
+ * commerce, but cannot become regulated measurement. */
+export function verifiedTruthFromForwardedOrder(input: OrderForwardInput): VerifiedOrderTruth | null {
+  if (!LIVE_ENVS.has(input.env)) return null;
+  if (typeof input.providerEventId !== "string" || !isIsoInstant(input.occurredAt) || typeof input.amountMinor !== "number" || !Number.isSafeInteger(input.amountMinor) || input.amountMinor < 0) return null;
+  const parsed = parseVerifiedOrderTruth({
+    schemaVersion: "1", authority: "verified-provider", provider: FOXY_PROVIDER,
+    providerEventId: input.providerEventId, providerOrderId: input.externalOrderId,
+    tenant: input.tenantId, status: input.status, occurredAt: input.occurredAt,
+    currency: input.currency, amountMinor: input.amountMinor,
+  });
+  return parsed.ok ? parsed.value : null;
+}
+
+/** Server-only D1 ledger/outbox. Event insertion uses a receipt id plus RETURNING,
+ * giving concurrent identical deliveries one winner. The order state change is a
+ * guarded SQL CAS, so a race cannot overwrite a refund/cancel with a purchase. */
+export class D1VerifiedProviderMeasurementStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly receiptId: () => string = () => crypto.randomUUID(),
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  async record(input: OrderForwardInput): Promise<VerifiedProviderMeasurementResult> {
+    if (!LIVE_ENVS.has(input.env)) return { outcome: "ignored-non-live", intent: null };
+    const record = verifiedTruthFromForwardedOrder(input);
+    if (!record) return { outcome: "ignored-malformed", intent: null };
+    const fingerprint = verifiedOrderTruthFingerprint(record);
+    const receiptId = this.receiptId();
+    const inserted = await this.db.all<{ receipt_id: string }>(
+      `INSERT INTO regulated_commerce_provider_events
+         (provider, provider_event_id, fingerprint, receipt_id, received_at)
+       VALUES (?, ?, ?, ?, ?) ON CONFLICT(provider, provider_event_id) DO NOTHING RETURNING receipt_id`,
+      record.provider, record.providerEventId, fingerprint, receiptId, this.now(),
+    );
+    if (inserted.length === 0) {
+      const existing = await this.event(record.provider, record.providerEventId);
+      return { outcome: existing?.fingerprint === fingerprint ? "duplicate" : "replay-conflict", intent: null };
+    }
+    for (let attempts = 0; attempts < 3; attempts++) {
+      const resolution = resolveVerifiedOrderTruth({ record, existingEvent: null, existingOrder: snapshot(await this.order(record)) });
+      if (resolution.outcome !== "accepted") return { outcome: resolution.outcome === "stale-transition" ? "stale-transition" : "replay-conflict", intent: null };
+      if (!(await this.claimTransition(record, resolution))) continue;
+      const built = intentFromVerifiedProviderTruth(record, resolution);
+      if (!built.intent) return { outcome: "recorded", intent: null };
+      await this.db.run(
+        `INSERT OR IGNORE INTO regulated_commerce_intent_outbox
+           (intent_id, tenant_id, provider, provider_event_id, payload, created_at) VALUES (?, ?, ?, ?, ?, ?)`,
+        built.intent.id, record.tenant, record.provider, record.providerEventId, JSON.stringify(built.intent), this.now(),
+      );
+      return { outcome: "recorded", intent: built.intent };
+    }
+    return { outcome: "stale-transition", intent: null };
+  }
+
+  /** Local/admin-safe test surface: only the minimized semantic outbox. */
+  async intents(): Promise<RegulatedCommerceIntent[]> {
+    const rows = await this.db.all<{ payload: string }>(`SELECT payload FROM regulated_commerce_intent_outbox ORDER BY created_at, intent_id`);
+    return rows.map((row) => JSON.parse(row.payload) as RegulatedCommerceIntent);
+  }
+
+  private event(provider: string, providerEventId: string): Promise<ProviderEventRow | null> {
+    return this.db.first<ProviderEventRow>(`SELECT fingerprint, receipt_id FROM regulated_commerce_provider_events WHERE provider = ? AND provider_event_id = ?`, provider, providerEventId);
+  }
+  private order(record: VerifiedOrderTruth): Promise<ProviderOrderRow | null> {
+    return this.db.first<ProviderOrderRow>(`SELECT provider, provider_order_id, tenant_id, state FROM regulated_commerce_provider_orders WHERE provider = ? AND provider_order_id = ? AND tenant_id = ?`, record.provider, record.providerOrderId, record.tenant);
+  }
+  private async claimTransition(record: VerifiedOrderTruth, resolution: Extract<VerifiedOrderTruthResolution, { outcome: "accepted" }>): Promise<boolean> {
+    const rows = await this.db.all<{ provider_event_id: string }>(
+      `INSERT INTO regulated_commerce_provider_orders
+         (provider, provider_order_id, tenant_id, state, provider_event_id, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(provider, provider_order_id, tenant_id) DO UPDATE SET
+         state = excluded.state, provider_event_id = excluded.provider_event_id, updated_at = excluded.updated_at
+       WHERE regulated_commerce_provider_orders.state = 'purchased'
+         AND excluded.state IN ('purchased', 'refunded', 'cancelled')
+       RETURNING provider_event_id`,
+      record.provider, record.providerOrderId, record.tenant, resolution.nextOrder.state, record.providerEventId, this.now(),
+    );
+    return rows.some((row) => row.provider_event_id === record.providerEventId);
+  }
+}