@tokenoftrust/storefront-runner 2.4.52 → 2.4.54

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

@@ -10,7 +10,22 @@
  * `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";
+import type { Queryable, QueryStatement } from "../../d1/catalog.js";
+import {
+  canonicalJson,
+  idempotencyKey,
+  paginateOrders,
+  sha256Hex,
+  type CommerceStage,
+  type PaymentState,
+} from "@tot/public-runtime";
+import {
+  foldCommerceEvents,
+  packCommercePayload,
+  type CommerceSnapshot,
+  type CommerceSourceEvent,
+  type StoredCommercePayload,
+} from "./orderMapper.js";
 
 export type OrderStatus = "created" | "fulfilled" | "refunded" | "cancelled";
 
@@ -179,3 +194,318 @@ export class OrdersStore {
     return row ? toDomain(row) : null;
   }
 }
+
+interface CommerceOrderRow {
+  tenant_id: string;
+  stage: string;
+  order_id: string;
+  source: string;
+  source_order_id: string;
+  currency: string;
+  placed_at: string;
+  payment_state: PaymentState;
+  compliance_state: CommerceSnapshot["compliance"];
+  stock_state: CommerceSnapshot["stock"];
+  fulfillment_state: CommerceSnapshot["fulfillment"];
+  label_state: CommerceSnapshot["label"];
+  amount_minor: number;
+  event_version: number;
+}
+
+export interface CommerceOrderQueryRow {
+  id: string;
+  placedAt: string;
+  payment: PaymentState;
+  fulfillment: CommerceSnapshot["fulfillment"];
+  amountMinor: number;
+  eventVersion: number;
+}
+
+export interface CommerceAggregate {
+  count: number;
+  amountMinor: number;
+  byPayment: Partial<Record<PaymentState, number>>;
+}
+
+export interface CommitCommerceInput {
+  tenantId: string;
+  stage: CommerceStage;
+  event: CommerceSourceEvent;
+  now: string;
+  replay?: { issuer: string; jti: string };
+}
+
+export type CommitCommerceResult =
+  | { ok: true; duplicate: boolean; snapshot: CommerceSnapshot; outboxId: string }
+  | { ok: false; reason: "replay" };
+
+async function atomic(db: Queryable, statements: readonly QueryStatement[]): Promise<void> {
+  if (typeof db.batch === "function") {
+    await db.batch(statements);
+    return;
+  }
+  await db.exec("BEGIN");
+  try {
+    for (const statement of statements) await db.run(statement.sql, ...(statement.params ?? []));
+    await db.exec("COMMIT");
+  } catch (error) {
+    await db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+function constraintTable(error: unknown): string | null {
+  if (!(error instanceof Error)) return null;
+  const match = /scrappy_[a-z_]+/.exec(error.message);
+  return match ? match[0] : null;
+}
+
+/** Durable commerce projection. Order, inbox, outbox, and caller replay commit together. */
+export class ScrappyOrderLedger {
+  constructor(private readonly db: Queryable) {}
+
+  async commit(input: CommitCommerceInput): Promise<CommitCommerceResult> {
+    const { tenantId, stage, event, now } = input;
+    if (input.replay) {
+      const seen = await this.db.first<{ jti: string }>(
+        `SELECT jti FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
+        tenantId,
+        stage,
+        input.replay.issuer,
+        input.replay.jti,
+      );
+      if (seen) return { ok: false, reason: "replay" };
+    }
+
+    const existing = await this.db.first<{ outbox_id: string; payload: string }>(
+      `SELECT outbox_id, payload FROM scrappy_commerce_outbox
+        WHERE tenant_id = ? AND stage = ? AND source = ? AND source_event_id = ?`,
+      tenantId,
+      stage,
+      event.source,
+      event.sourceEventId,
+    );
+    if (existing) {
+      if (input.replay) {
+        try {
+          await this.insertReplay(input);
+        } catch (error) {
+          if (constraintTable(error) === "scrappy_caller_replay") return { ok: false, reason: "replay" };
+          throw error;
+        }
+      }
+      const snapshot = await this.readSnapshot(tenantId, stage, event.orderId, event);
+      return { ok: true, duplicate: true, snapshot, outboxId: existing.outbox_id };
+    }
+
+    const priorRows = await this.db.all<{ payload: string }>(
+      `SELECT payload FROM scrappy_commerce_outbox WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      tenantId,
+      stage,
+      event.orderId,
+    );
+    const prior: CommerceSourceEvent[] = [];
+    for (const row of priorRows) {
+      const parsed = JSON.parse(row.payload) as StoredCommercePayload;
+      prior.push(parsed.source);
+    }
+    const snapshot = foldCommerceEvents([...prior, event]);
+    const packed = packCommercePayload(event, snapshot);
+    const key = idempotencyKey(tenantId, stage, event.source, event.sourceEventId);
+    const outboxId = (await sha256Hex(key)).slice(0, 32);
+    const digest = await sha256Hex(canonicalJson(event));
+    const statements: QueryStatement[] = [];
+    if (input.replay) {
+      statements.push({
+        sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at) VALUES (?,?,?,?,?)`,
+        params: [tenantId, stage, input.replay.issuer, input.replay.jti, now],
+      });
+    }
+    statements.push(
+      {
+        sql: `INSERT INTO scrappy_commerce_orders (
+                tenant_id, stage, order_id, source, source_order_id, currency, placed_at,
+                payment_state, compliance_state, stock_state, fulfillment_state, label_state,
+                amount_minor, event_version
+              ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+              ON CONFLICT(tenant_id, stage, order_id) DO UPDATE SET
+                source = excluded.source,
+                source_order_id = excluded.source_order_id,
+                currency = excluded.currency,
+                placed_at = excluded.placed_at,
+                payment_state = excluded.payment_state,
+                compliance_state = excluded.compliance_state,
+                stock_state = excluded.stock_state,
+                fulfillment_state = excluded.fulfillment_state,
+                label_state = excluded.label_state,
+                amount_minor = excluded.amount_minor,
+                event_version = excluded.event_version`,
+        params: [
+          tenantId,
+          stage,
+          snapshot.orderId,
+          snapshot.source,
+          snapshot.sourceOrderId,
+          snapshot.currency,
+          snapshot.placedAt,
+          snapshot.payment,
+          snapshot.compliance,
+          snapshot.stock,
+          snapshot.fulfillment,
+          snapshot.label,
+          snapshot.amountMinor,
+          snapshot.eventVersion,
+        ],
+      },
+      {
+        sql: `INSERT INTO scrappy_commerce_inbox (
+                tenant_id, stage, source, source_event_id, event_version, idempotency_key, payload_digest, received_at
+              ) VALUES (?,?,?,?,?,?,?,?)`,
+        params: [tenantId, stage, event.source, event.sourceEventId, event.eventVersion, key, digest, now],
+      },
+      {
+        sql: `INSERT INTO scrappy_commerce_outbox (
+                outbox_id, tenant_id, stage, order_id, source, source_event_id, event_version,
+                event_type, payload, available_at, attempt_count, state
+              ) VALUES (?,?,?,?,?,?,?,?,?,?,0,'pending')`,
+        params: [
+          outboxId,
+          tenantId,
+          stage,
+          snapshot.orderId,
+          event.source,
+          event.sourceEventId,
+          event.eventVersion,
+          "order.observed",
+          JSON.stringify(packed),
+          now,
+        ],
+      },
+    );
+
+    try {
+      await atomic(this.db, statements);
+    } catch (error) {
+      const table = constraintTable(error);
+      if (table === "scrappy_caller_replay") return { ok: false, reason: "replay" };
+      if (table === "scrappy_commerce_inbox" || table === "scrappy_commerce_outbox") {
+        const raced = await this.db.first<{ outbox_id: string }>(
+          `SELECT outbox_id FROM scrappy_commerce_outbox
+            WHERE tenant_id = ? AND stage = ? AND source = ? AND source_event_id = ?`,
+          tenantId,
+          stage,
+          event.source,
+          event.sourceEventId,
+        );
+        if (raced) {
+          const snapshotNow = await this.readSnapshot(tenantId, stage, event.orderId, event);
+          return { ok: true, duplicate: true, snapshot: snapshotNow, outboxId: raced.outbox_id };
+        }
+      }
+      throw error;
+    }
+    return { ok: true, duplicate: false, snapshot, outboxId };
+  }
+
+  async queryOrders(
+    tenantId: string,
+    stage: CommerceStage,
+    limit: number,
+    cursor: string | null,
+  ): Promise<{ orders: CommerceOrderQueryRow[]; nextCursor: string | null; invalidCursor: boolean }> {
+    const rows = await this.db.all<CommerceOrderRow>(
+      `SELECT * FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ?`,
+      tenantId,
+      stage,
+    );
+    const orders = rows.map((row) => ({
+      id: row.order_id,
+      placedAt: row.placed_at,
+      payment: row.payment_state,
+      fulfillment: row.fulfillment_state,
+      amountMinor: row.amount_minor,
+      eventVersion: row.event_version,
+    }));
+    return paginateOrders(orders, limit, cursor);
+  }
+
+  async aggregateOrders(tenantId: string, stage: CommerceStage): Promise<CommerceAggregate> {
+    const rows = await this.db.all<{ payment_state: PaymentState; n: number; amount: number | null }>(
+      `SELECT payment_state, COUNT(*) AS n, SUM(amount_minor) AS amount
+         FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ?
+        GROUP BY payment_state`,
+      tenantId,
+      stage,
+    );
+    const byPayment: Partial<Record<PaymentState, number>> = {};
+    let count = 0;
+    let amountMinor = 0;
+    for (const row of rows) {
+      const n = Number(row.n);
+      byPayment[row.payment_state] = n;
+      count += n;
+      amountMinor += Number(row.amount ?? 0);
+    }
+    return { count, amountMinor, byPayment };
+  }
+
+  /** Reset one outbox row for this tenant and stage. Does not write another order. */
+  async replayOutbox(tenantId: string, stage: CommerceStage, outboxId: string, now: string): Promise<boolean> {
+    const row = await this.db.first<{ outbox_id: string }>(
+      `SELECT outbox_id FROM scrappy_commerce_outbox WHERE outbox_id = ? AND tenant_id = ? AND stage = ?`,
+      outboxId,
+      tenantId,
+      stage,
+    );
+    if (!row) return false;
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox
+          SET state = 'pending', available_at = ?, attempt_count = 0
+        WHERE outbox_id = ? AND tenant_id = ? AND stage = ?`,
+      now,
+      outboxId,
+      tenantId,
+      stage,
+    );
+    return true;
+  }
+
+  async readOrder(tenantId: string, stage: CommerceStage, orderId: string): Promise<CommerceOrderRow | null> {
+    return this.db.first<CommerceOrderRow>(
+      `SELECT * FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      tenantId,
+      stage,
+      orderId,
+    );
+  }
+
+  private async insertReplay(input: CommitCommerceInput): Promise<void> {
+    if (!input.replay) return;
+    await atomic(this.db, [
+      {
+        sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at) VALUES (?,?,?,?,?)`,
+        params: [input.tenantId, input.stage, input.replay.issuer, input.replay.jti, input.now],
+      },
+    ]);
+  }
+
+  private async readSnapshot(
+    tenantId: string,
+    stage: CommerceStage,
+    orderId: string,
+    event: CommerceSourceEvent,
+  ): Promise<CommerceSnapshot> {
+    const rows = await this.db.all<{ payload: string }>(
+      `SELECT payload FROM scrappy_commerce_outbox WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      tenantId,
+      stage,
+      orderId,
+    );
+    const events: CommerceSourceEvent[] = [];
+    for (const row of rows) {
+      const parsed = JSON.parse(row.payload) as StoredCommercePayload;
+      if (parsed.source) events.push(parsed.source);
+    }
+    return foldCommerceEvents(events.length > 0 ? events : [event]);
+  }
+}

package/apps/storefront/src/lib/webhooks/deliveryEngine.ts

@@ -22,11 +22,13 @@
  * public target can't 302 its way to an internal one; either case never
  * reads as `delivered`.
  */
-import { WebhookDeliveryStore, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
+import { WebhookDeliveryStore, ScrappyCommerceOutbox, type CommerceOutboxDue, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
 import type { AppInstall } from "../apps/registryService.js";
 import { buildCloudEventEnvelope } from "./events.js";
 import { computeBackoffDelaySeconds, MAX_DELIVERY_ATTEMPTS, type AttemptOutcome } from "./dispatcher.js";
 import { validateWebhookEndpoint } from "./endpointGuard.js";
+import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
+import type { Queryable } from "../d1/catalog.js";
 
 /** Bounded per-attempt timeout — a hung receiver must not hold a dispatcher slot open indefinitely. */
 const DEFAULT_TIMEOUT_MS = 10_000;
@@ -277,3 +279,110 @@ async function postWithTimeout(
     clearTimeout(timer);
   }
 }
+
+const COMMERCE_PRIVATE_KEYS = new Set([
+  "customer",
+  "customerEmail",
+  "customerName",
+  "email",
+  "phone",
+  "line1",
+  "line2",
+  "postalCode",
+  "shippingAddress",
+  "billingAddress",
+  "address",
+  "firstName",
+  "lastName",
+  "name",
+]);
+
+function commercePayloadHasPrivateIdentity(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some((item) => commercePayloadHasPrivateIdentity(item));
+  return Object.entries(value as Record<string, unknown>).some(
+    ([key, child]) => COMMERCE_PRIVATE_KEYS.has(key) || commercePayloadHasPrivateIdentity(child),
+  );
+}
+
+function publicCommercePayload(payload: string): Record<string, unknown> | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  if (commercePayloadHasPrivateIdentity(parsed)) return null;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const body = parsed as Record<string, unknown>;
+  const event = body.public;
+  if (event === null || typeof event !== "object" || Array.isArray(event)) return null;
+  if ((event as Record<string, unknown>).type !== "order.observed") return null;
+  return event as Record<string, unknown>;
+}
+
+export type CommerceSweepResult =
+  | { ok: true; delivered: number; retried: number; dead: number }
+  | { ok: false; reason: "scheduler" };
+
+export type CommerceDeliver = (event: Record<string, unknown>) => Promise<void>;
+
+/**
+ * Deliver due commerce outbox rows. A scheduler other than the declared alarm
+ * leaves every row pending.
+ */
+export async function sweepDurableCommerce(input: {
+  db: Queryable;
+  scheduler: string;
+  now: string;
+  deliver?: CommerceDeliver;
+}): Promise<CommerceSweepResult> {
+  if (input.scheduler !== COMMERCE_SCHEDULER) return { ok: false, reason: "scheduler" };
+  const port = new ScrappyCommerceOutbox(input.db);
+  const due = await port.due(input.now);
+  let delivered = 0;
+  let retried = 0;
+  let dead = 0;
+  const tenants: { tenantId: string; stage: string }[] = [];
+  const seenTenant = (tenantId: string, stage: string) => {
+    if (!tenants.some((item) => item.tenantId === tenantId && item.stage === stage)) {
+      tenants.push({ tenantId, stage });
+    }
+  };
+  for (const row of due) {
+    seenTenant(row.tenant_id, row.stage);
+    const outcome = await settleCommerceRow(port, row, input.now, input.deliver);
+    if (outcome === "delivered") delivered += 1;
+    else if (outcome === "retried") retried += 1;
+    else dead += 1;
+  }
+  for (const tenant of tenants) await port.noteCursor(tenant.tenantId, tenant.stage, input.now);
+  return { ok: true, delivered, retried, dead };
+}
+
+async function settleCommerceRow(
+  port: ScrappyCommerceOutbox,
+  row: CommerceOutboxDue,
+  now: string,
+  deliver: CommerceDeliver | undefined,
+): Promise<"delivered" | "retried" | "dead"> {
+  const event = publicCommercePayload(row.payload);
+  if (!event) {
+    await port.markDead(row.outbox_id);
+    return "dead";
+  }
+  try {
+    if (deliver) await deliver(event);
+    await port.markDelivered(row.outbox_id);
+    return "delivered";
+  } catch {
+    const next = row.attempt_count + 1;
+    if (next >= MAX_DELIVERY_ATTEMPTS) {
+      await port.markDead(row.outbox_id, next);
+      return "dead";
+    }
+    const availableAt = new Date(Date.parse(now) + computeBackoffDelaySeconds(next) * 1000).toISOString();
+    await port.markRetry(row.outbox_id, next, availableAt);
+    return "retried";
+  }
+}

package/apps/storefront/src/lib/webhooks/deliveryStore.ts

@@ -665,3 +665,73 @@ export class WebhookDeliveryStore {
     return toDomain(await this.mustFindDeliveryRow(deliveryId));
   }
 }
+
+export interface CommerceOutboxDue {
+  outbox_id: string;
+  tenant_id: string;
+  stage: string;
+  payload: string;
+  attempt_count: number;
+  available_at: string;
+}
+
+/** Due commerce outbox rows. The order ledger owns the insert; this port owns sweep progress. */
+export class ScrappyCommerceOutbox {
+  constructor(private readonly db: Queryable) {}
+
+  async due(now: string): Promise<CommerceOutboxDue[]> {
+    const rows = await this.db.all<CommerceOutboxDue>(
+      `SELECT outbox_id, tenant_id, stage, payload, attempt_count, available_at
+         FROM scrappy_commerce_outbox
+        WHERE state = 'pending' AND available_at <= ?
+        ORDER BY available_at`,
+      now,
+    );
+    return rows.map((row) => ({ ...row, attempt_count: Number(row.attempt_count) }));
+  }
+
+  async markDelivered(outboxId: string): Promise<void> {
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox SET state = 'delivered' WHERE outbox_id = ? AND state = 'pending'`,
+      outboxId,
+    );
+  }
+
+  async markRetry(outboxId: string, attemptCount: number, availableAt: string): Promise<void> {
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox
+          SET state = 'pending', attempt_count = ?, available_at = ?
+        WHERE outbox_id = ? AND state = 'pending'`,
+      attemptCount,
+      availableAt,
+      outboxId,
+    );
+  }
+
+  async markDead(outboxId: string, attemptCount?: number): Promise<void> {
+    if (attemptCount === undefined) {
+      await this.db.run(
+        `UPDATE scrappy_commerce_outbox SET state = 'dead' WHERE outbox_id = ? AND state = 'pending'`,
+        outboxId,
+      );
+      return;
+    }
+    await this.db.run(
+      `UPDATE scrappy_commerce_outbox
+          SET state = 'dead', attempt_count = ?
+        WHERE outbox_id = ? AND state = 'pending'`,
+      attemptCount,
+      outboxId,
+    );
+  }
+
+  async noteCursor(tenantId: string, stage: string, cursor: string): Promise<void> {
+    await this.db.run(
+      `INSERT INTO scrappy_sweep_cursor (tenant_id, stage, cursor) VALUES (?,?,?)
+       ON CONFLICT(tenant_id, stage) DO UPDATE SET cursor = excluded.cursor`,
+      tenantId,
+      stage,
+      cursor,
+    );
+  }
+}

package/apps/storefront/src/lib/webhooks/getDispatcher.ts

@@ -15,15 +15,16 @@
  * design-resolution + entry-wiring context).
  */
 import { WebhookDeliveryStore } from "./deliveryStore.js";
-import { attemptDelivery } from "./deliveryEngine.js";
+import { attemptDelivery, sweepDurableCommerce, type CommerceDeliver, type CommerceSweepResult } from "./deliveryEngine.js";
 import { InMemoryDispatcher, type AttemptDeliveryFn, type WebhookDispatcher } from "./dispatcher.js";
 import { CloudflareQueueDispatcher, type CloudflareQueueSender } from "./cloudflareQueueDispatcher.js";
 import { AppRegistryService } from "../apps/registryService.js";
 import { D1CredentialStore } from "../apps/credentials.js";
 import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "../apps/gatewayKeys.js";
 import { json } from "../apps/registryAccess.js";
-import { fromD1 } from "../d1/catalog.js";
+import { fromD1, type Queryable } from "../d1/catalog.js";
 import { readD1, readEnv, readQueue } from "../env.js";
+import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
 
 /** Binding name `getDispatcher()` checks to pick the Cloudflare Queues adapter. Not yet declared in `wrangler.toml`. */
 export const WEBHOOK_QUEUE_BINDING = "WEBHOOK_DELIVERY_QUEUE";
@@ -47,3 +48,29 @@ export async function getDispatcher(): Promise<WebhookDispatcher | Response> {
   if (queueSender) return new CloudflareQueueDispatcher(queueSender);
   return new InMemoryDispatcher(attempt);
 }
+
+/**
+ * Commerce work is already durable when it is saved. This dispatcher only
+ * sweeps that outbox, and only when the declared scheduler is configured.
+ * It never falls back to an in-memory queue.
+ */
+export class CommerceAlarmDispatcher {
+  constructor(
+    private readonly db: Queryable,
+    private readonly scheduler: string,
+  ) {}
+
+  async enqueue(): Promise<void> {}
+
+  sweep(now: string, deliver?: CommerceDeliver): Promise<CommerceSweepResult> {
+    return sweepDurableCommerce({ db: this.db, scheduler: this.scheduler, now, deliver });
+  }
+}
+
+export async function getReliableDispatcher(): Promise<CommerceAlarmDispatcher | Response> {
+  const scheduler = await readEnv("SCRAPPY_COMMERCE_SCHEDULER");
+  if (scheduler !== COMMERCE_SCHEDULER) return json({ error: "commerce scheduler not configured" }, 503);
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "commerce scheduler not configured" }, 503);
+  return new CommerceAlarmDispatcher(fromD1(d1), scheduler);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.52",
+  "version": "2.4.54",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",