@tokenoftrust/storefront-runner 6.5.0 → 6.5.1

package/apps/storefront/src/lib/integrations/webhooks/orderFulfilledClaim.ts

@@ -0,0 +1,75 @@
+/**
+ * `order.fulfilled` is claimed once per order across its two producers: the fulfillment handoff
+ * and the order-forward receiver. The claim is keyed (tenant, stage, source, source order id,
+ * topic); each producer writes its claim and its gated event rows in one batch, and only the
+ * producer whose claim carries its event id writes the event.
+ */
+import type { CommerceStage } from "@tot/public-runtime";
+import type { CommerceEventStatement } from "./deliveryStore.js";
+
+export interface OrderFulfilledClaimKey {
+  tenantId: string;
+  stage: CommerceStage;
+  source: string;
+  sourceOrderId: string;
+}
+
+/** The forward contract's `env` mapped to a commerce stage; any other value claims and emits nothing. */
+export function forwardStage(env: string): CommerceStage | null {
+  if (env === "production") return "publication";
+  if (env === "sandbox") return "preview";
+  return null;
+}
+
+/** The handoff's claim: written only when no claim exists and `gate` holds (the handoff's CAS committed). */
+export function handoffClaimStatement(
+  key: OrderFulfilledClaimKey,
+  eventId: string,
+  now: string,
+  gate: CommerceEventStatement,
+): CommerceEventStatement {
+  return {
+    sql: `INSERT INTO commerce_event_claims
+        (tenant_id, stage, source, source_order_id, topic, event_id, claimed_by, claimed_at)
+      SELECT ?, ?, ?, ?, 'order.fulfilled', ?, 'handoff', ?
+      WHERE NOT EXISTS (
+          SELECT 1 FROM commerce_event_claims
+          WHERE tenant_id = ? AND stage = ? AND source = ? AND source_order_id = ? AND topic = 'order.fulfilled'
+        ) AND (${gate.sql})`,
+    params: [
+      key.tenantId,
+      key.stage,
+      key.source,
+      key.sourceOrderId,
+      eventId,
+      now,
+      key.tenantId,
+      key.stage,
+      key.source,
+      key.sourceOrderId,
+      ...gate.params,
+    ],
+  };
+}
+
+/** The forward receiver's claim. */
+export function forwardClaimStatement(key: OrderFulfilledClaimKey, eventId: string, now: string): CommerceEventStatement {
+  return {
+    sql: `INSERT OR IGNORE INTO commerce_event_claims
+        (tenant_id, stage, source, source_order_id, topic, event_id, claimed_by, claimed_at)
+      VALUES (?, ?, ?, ?, 'order.fulfilled', ?, 'forward', ?)`,
+    params: [key.tenantId, key.stage, key.source, key.sourceOrderId, eventId, now],
+  };
+}
+
+/** Event gate: the claim for `key` carries `eventId`. */
+export function claimedByEventGate(key: OrderFulfilledClaimKey, eventId: string): CommerceEventStatement {
+  return {
+    sql: `EXISTS (
+        SELECT 1 FROM commerce_event_claims
+        WHERE tenant_id = ? AND stage = ? AND source = ? AND source_order_id = ? AND topic = 'order.fulfilled'
+          AND event_id = ?
+      )`,
+    params: [key.tenantId, key.stage, key.source, key.sourceOrderId, eventId],
+  };
+}

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

@@ -21,6 +21,11 @@
  *     corresponding topic — e.g. -> `cancelled`, which V1 has no topic for)
  *     -> no emit; the row still updates, silently.
  *
+ * `order.fulfilled` is claimed once per order (`orderFulfilledClaim.ts`) under the key the signed
+ * intake and the fulfillment handoff use: (tenant, stage from `env`, `foxycart`, external order id).
+ * The claim, the event and its deliveries commit in one batch; a forward whose order is already
+ * claimed writes nothing, and an `env` other than production or sandbox emits no `order.fulfilled`.
+ *
  * 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
@@ -36,7 +41,8 @@ import { SourceAuthorityStore } from "./sourceAuthorityStore.js";
 import { SourceAuthorityError, parseSourceWire, exactKeys, digestJson, type BeginAck, type ResultAck, type AuthorityCode, isRecord, isSourceId } from "./sourceAuthorityContract.js";
 import { OrdersStore, ScrappyOrderLedger, type OrderLineItem, type OrderStatus, type Order } from "./ordersStore.js";
 import { emitWebhookEvent } from "../../integrations/webhooks/emit.js";
-import type { WebhookTopic } from "../../integrations/webhooks/deliveryStore.js";
+import { commerceEventStatements, commerceTargetsQuery, type WebhookTopic } from "../../integrations/webhooks/deliveryStore.js";
+import { claimedByEventGate, forwardClaimStatement, forwardStage, type OrderFulfilledClaimKey } from "../../integrations/webhooks/orderFulfilledClaim.js";
 import type { Queryable } from "../../catalog/d1/catalog.js";
 import {
   createLocalJWKSet,
@@ -125,7 +131,11 @@ function topicsFor(previousStatus: OrderStatus | null, status: OrderStatus): Web
  * 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> {
+export async function receiveForwardedOrder(
+  db: Queryable,
+  input: OrderForwardInput,
+  options: { notify?: (tenantId: string, deliveryIds: string[]) => void | Promise<void> } = {},
+): 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.
@@ -142,14 +152,65 @@ export async function receiveForwardedOrder(db: Queryable, input: OrderForwardIn
     createdAt: input.createdAt ?? new Date().toISOString(),
   });
 
-  const emitted = topicsFor(previousStatus, input.status);
-  for (const topic of emitted) {
+  const emitted: WebhookTopic[] = [];
+  for (const topic of topicsFor(previousStatus, input.status)) {
+    if (topic === "order.fulfilled") {
+      if (await emitClaimedOrderFulfilled(db, input, order, options.notify)) emitted.push(topic);
+      continue;
+    }
     await emitWebhookEvent(topic, input.tenantId, toOrderData(order), {});
+    emitted.push(topic);
   }
 
   return { order, previousStatus, emitted };
 }
 
+/** Claims `order.fulfilled` for this order and, only under that claim, writes its event and deliveries. */
+async function emitClaimedOrderFulfilled(
+  db: Queryable,
+  input: OrderForwardInput,
+  order: Order,
+  notify: ((tenantId: string, deliveryIds: string[]) => void | Promise<void>) | undefined,
+): Promise<boolean> {
+  const stage = forwardStage(input.env);
+  if (!stage) return false;
+  if (!db.batch) throw new Error("Atomic D1 batch support is required.");
+  const key: OrderFulfilledClaimKey = {
+    tenantId: input.tenantId,
+    stage,
+    source: "foxycart",
+    sourceOrderId: input.externalOrderId,
+  };
+  const eventId = crypto.randomUUID();
+  const now = new Date().toISOString();
+  const targets = commerceTargetsQuery(input.tenantId, "order.fulfilled");
+  const installs = await db.all<{ install_id: string }>(targets.sql, ...targets.params);
+  const deliveries = installs.map((row) => ({ installId: row.install_id, deliveryId: crypto.randomUUID() }));
+  await db.batch([
+    forwardClaimStatement(key, eventId, now),
+    ...commerceEventStatements({
+      eventId,
+      tenantId: input.tenantId,
+      topic: "order.fulfilled",
+      payload: toOrderData(order),
+      gate: claimedByEventGate(key, eventId),
+      targets: deliveries,
+      now,
+    }),
+  ]);
+  const written = await db.first<{ ok: number }>(`SELECT 1 AS ok FROM webhook_events WHERE id = ?`, eventId);
+  if (!written) return false;
+  const committed = await db.all<{ delivery_id: string }>(`SELECT delivery_id FROM webhook_deliveries WHERE event_id = ?`, eventId);
+  if (notify && committed.length > 0) {
+    try {
+      await notify(input.tenantId, committed.map((row) => row.delivery_id));
+    } catch {
+      // The committed deliveries stay pending; the tenant commerce alarm redelivers them.
+    }
+  }
+  return true;
+}
+
 export interface CommerceCallerConfig {
   expectedStage: CommerceStage;
   jwks: JSONWebKeySet;

package/package.json

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