@tokenoftrust/storefront-runner 2.4.54 → 2.4.55

package/apps/storefront/src/lib/fulfillment/readiness.ts

@@ -0,0 +1,150 @@
+/**
+ * Release and hand-off gates for whole-order fulfillment.
+ *
+ * Evidence, payment, stock, refund, and cancel are rechecked from stored source
+ * truth. Compliance `fresh` is not evidence. A carrier account is tenant
+ * configuration: its absence is not a hold, and this module does not select a vendor.
+ */
+import {
+  decideCommerceCommand,
+  paymentIsCaptured,
+  type CommerceEvidence,
+  type ComplianceRuleProfile,
+  type EvidenceState,
+  type FulfillmentState,
+  type LabelState,
+  type PaymentState,
+  type ProviderOutcome,
+  type StockState,
+} from "@tot/public-runtime";
+import { COMPLIANCE_RULE_PROFILES } from "@/config/compliance/rulesets";
+
+export const RELEASE_HOLDS = [
+  "evidence-unknown",
+  "evidence-stale",
+  "evidence-unreadable",
+  "evidence-absent",
+  "operator-hold",
+  "payment-pending",
+  "payment-unknown",
+  "payment-not-captured",
+  "refund-pending",
+  "refunded",
+  "refund-unknown",
+  "cancel-pending",
+  "cancelled",
+  "stock-unknown",
+  "stock-unconfirmed",
+  "fulfillment-unknown",
+] as const;
+
+export type ReleaseHold = (typeof RELEASE_HOLDS)[number];
+
+export interface CarrierPolicy {
+  adultSignatureRequired: boolean;
+  prohibitedCarriers: readonly string[];
+  /** Null when the tenant has not configured an account. Absence is not a hold. */
+  carrierAccountId: string | null;
+}
+
+export interface ReadinessInput {
+  payment: PaymentState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  evidence: CommerceEvidence;
+  operatorHold: boolean;
+  cancelPending: boolean;
+  providerOutcome: ProviderOutcome | null;
+  adultSignature: "accepted" | "refused" | "absent";
+  adultSignatureRequired: boolean;
+}
+
+const EVIDENCE_HOLDS: Record<EvidenceState, ReleaseHold | null> = {
+  fresh: null,
+  UNKNOWN: "evidence-unknown",
+  stale: "evidence-stale",
+  unreadable: "evidence-unreadable",
+  absent: "evidence-absent",
+};
+
+function add(holds: ReleaseHold[], hold: ReleaseHold | null): void {
+  if (hold && !holds.includes(hold)) holds.push(hold);
+}
+
+/** Holds that forbid creating a shipment intent. Compliance is not an input. */
+export function releaseHolds(input: ReadinessInput): ReleaseHold[] {
+  const holds: ReleaseHold[] = [];
+  for (const field of ["verification", "tax", "risk", "stock"] as const) {
+    const value = input.evidence[field];
+    add(holds, value in EVIDENCE_HOLDS ? EVIDENCE_HOLDS[value as EvidenceState] : "evidence-unreadable");
+  }
+  if (input.operatorHold) add(holds, "operator-hold");
+  if (input.cancelPending) add(holds, "cancel-pending");
+  if (input.fulfillment === "cancelled") add(holds, "cancelled");
+  if (input.fulfillment === "UNKNOWN") add(holds, "fulfillment-unknown");
+  if (input.payment === "pending" || input.payment === "authorized") add(holds, "payment-pending");
+  else if (input.payment === "UNKNOWN" || input.payment === "capture_unknown") add(holds, "payment-unknown");
+  else if (input.payment === "refund_requested") add(holds, "refund-pending");
+  else if (input.payment === "refunded") add(holds, "refunded");
+  else if (input.payment === "refund_unknown") add(holds, "refund-unknown");
+  else if (input.payment === "voided") add(holds, "cancelled");
+  else if (!paymentIsCaptured(input.payment)) add(holds, "payment-not-captured");
+  if (input.stock === "UNKNOWN") add(holds, "stock-unknown");
+  else if (input.stock !== "confirmed") add(holds, "stock-unconfirmed");
+  return holds;
+}
+
+export function canRelease(input: ReadinessInput): boolean {
+  return input.fulfillment === "ready" && releaseHolds(input).length === 0;
+}
+
+export function handoffRefusal(input: ReadinessInput): ReleaseHold | "adult-signature" | "label" | "reconcile" | "fulfillment" | "evidence" | "payment" | "stock" | "reuse" | null {
+  const holds = releaseHolds(input);
+  if (holds.length > 0) return holds[0] ?? "fulfillment";
+  const decision = decideCommerceCommand({
+    command: "hand-off",
+    payment: input.payment,
+    stock: input.stock,
+    fulfillment: input.fulfillment,
+    label: input.label,
+    evidence: input.evidence,
+    providerOutcome: input.providerOutcome,
+  });
+  if (!decision.admit) return decision.reason === "admitted" ? "fulfillment" : decision.reason;
+  if (input.adultSignatureRequired && input.adultSignature !== "accepted") return "adult-signature";
+  return null;
+}
+
+export function carrierPolicyForTenant(tenant: {
+  tenant_id: string;
+  compliance?: { ruleProfile?: string };
+  carrierAccountId?: unknown;
+}): CarrierPolicy {
+  const profile = tenant.compliance?.ruleProfile;
+  const build =
+    profile && Object.hasOwn(COMPLIANCE_RULE_PROFILES, profile)
+      ? COMPLIANCE_RULE_PROFILES[profile as ComplianceRuleProfile]
+      : undefined;
+  const ruleset = build ? build(tenant.tenant_id) : null;
+  const raw = tenant.carrierAccountId;
+  const carrierAccountId = typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+  const enabled = ruleset?.pactAct.enabled === true;
+  return {
+    adultSignatureRequired: enabled && ruleset.pactAct.adultSignatureRequired === true,
+    prohibitedCarriers: enabled ? [...ruleset.pactAct.prohibitedCarriers] : [],
+    carrierAccountId,
+  };
+}
+
+/** A supplied carrier is never a selection. USPS is refused when the policy prohibits it. */
+export function carrierSelectionRefusal(
+  policy: CarrierPolicy,
+  carrier: string | undefined,
+): "carrier-prohibited" | "vendor-not-selected" | null {
+  if (carrier === undefined) return null;
+  const normalized = carrier.trim().toUpperCase();
+  if (normalized === "") return "vendor-not-selected";
+  if (policy.prohibitedCarriers.some((item) => item.toUpperCase() === normalized)) return "carrier-prohibited";
+  return "vendor-not-selected";
+}

package/apps/storefront/src/lib/fulfillment/store.ts

@@ -0,0 +1,109 @@
+/**
+ * Tenant-scoped SQL seam for scrappy commerce tables.
+ *
+ * Batch phase, holds, packing slips, and label intents are rows in
+ * `scrappy_shipment_audit` (append-only). The commerce migration has no batch
+ * table; this store does not create one.
+ */
+import type { D1Like } from "../d1/catalog.js";
+
+export interface SqlStatement {
+  sql: string;
+  params: readonly unknown[];
+}
+
+export interface FulfillmentDatabase {
+  get<T extends Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T | undefined>;
+  all<T extends Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+  /** One transaction. A unique-constraint loss returns zeros so the caller can re-read. */
+  batch(statements: readonly SqlStatement[]): Promise<number[]>;
+}
+
+interface SqliteStatement {
+  all(...params: unknown[]): Array<Record<string, unknown>>;
+  get(...params: unknown[]): Record<string, unknown> | undefined;
+  run(...params: unknown[]): { changes?: number | bigint };
+}
+
+export interface SqliteDatabase {
+  prepare(sql: string): SqliteStatement;
+  exec(sql: string): void;
+}
+
+function changesOf(result: { changes?: number | bigint } | undefined): number {
+  const changes = result?.changes ?? 0;
+  return typeof changes === "bigint" ? Number(changes) : changes;
+}
+
+function lostRace(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("UNIQUE constraint failed");
+}
+
+export function fulfillmentDbFromSqlite(db: SqliteDatabase): FulfillmentDatabase {
+  db.exec("PRAGMA foreign_keys = ON");
+  let chain: Promise<unknown> = Promise.resolve();
+  const enqueue = <T>(fn: () => T): Promise<T> => {
+    const run = chain.then(
+      () => fn(),
+      () => fn(),
+    );
+    chain = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  };
+  return {
+    get: (sql, params = []) => enqueue(() => db.prepare(sql).get(...params) as never),
+    all: (sql, params = []) => enqueue(() => db.prepare(sql).all(...params) as never),
+    batch: (statements) =>
+      enqueue(() => {
+        if (statements.length === 0) return [];
+        db.exec("BEGIN IMMEDIATE");
+        const changes: number[] = [];
+        try {
+          for (const statement of statements) {
+            changes.push(changesOf(db.prepare(statement.sql).run(...statement.params)));
+          }
+          db.exec("COMMIT");
+          return changes;
+        } catch (error) {
+          try {
+            db.exec("ROLLBACK");
+          } catch {
+            /* the transaction is already closed */
+          }
+          if (lostRace(error)) return statements.map(() => 0);
+          throw new Error("storage", { cause: error });
+        }
+      }),
+  };
+}
+
+export function fulfillmentDbFromD1(db: D1Like): FulfillmentDatabase {
+  return {
+    async get(sql, params = []) {
+      const row = await db.prepare(sql).bind(...params).first();
+      return (row ?? undefined) as never;
+    },
+    async all(sql, params = []) {
+      const result = await db.prepare(sql).bind(...params).all();
+      return (result.results ?? []) as never;
+    },
+    async batch(statements) {
+      if (statements.length === 0) return [];
+      if (!db.batch) throw new Error("storage");
+      try {
+        const results = await db.batch(statements.map((statement) => db.prepare(statement.sql).bind(...statement.params)));
+        return results.map((result) => {
+          if (!result || typeof result !== "object") return 0;
+          const meta = Reflect.get(result, "meta") as { changes?: number } | undefined;
+          return Number(meta?.changes ?? 0);
+        });
+      } catch (error) {
+        if (lostRace(error)) return statements.map(() => 0);
+        throw new Error("storage", { cause: error });
+      }
+    },
+  };
+}

package/apps/storefront/src/pages/api/admin/fulfillment/batches.ts

@@ -0,0 +1,59 @@
+/**
+ * Authenticated owner API for whole-order batch claim and batch read.
+ */
+import type { APIContext } from "astro";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
+import {
+  fulfillmentResultResponse,
+  isOpaqueId,
+  openFulfillment,
+  parseFulfillmentBody,
+  readJsonBody,
+} from "@/lib/fulfillment/fulfillmentService";
+
+export const prerender = false;
+
+function ownerRefusal(status: number, reason: string): Response {
+  return new Response(JSON.stringify({ error: reason }), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}
+
+async function requireOwner(context: APIContext): Promise<Response | null> {
+  const access = await requireAdminApiEntry(context, { requireOwner: true });
+  if (access.ok) return null;
+  return ownerRefusal(access.status, access.reason);
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const refused = await requireOwner(context);
+  if (refused) return refused;
+  const opened = await openFulfillment(context);
+  if (!opened.ok) return opened.response;
+  const batchId = new URL(context.request.url).searchParams.get("batchId") ?? "";
+  if (!isOpaqueId(batchId)) return fulfillmentResultResponse({ ok: false, code: "not-found" }, () => ({}));
+  return fulfillmentResultResponse(await opened.service.batch(opened.actor, batchId), (batch) => batch);
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const refused = await requireOwner(context);
+  if (refused) return refused;
+  const raw = await readJsonBody(context.request);
+  if (!raw.ok) return fulfillmentResultResponse(raw, () => ({}));
+  const parsed = parseFulfillmentBody(raw.value);
+  if (!parsed.ok) return fulfillmentResultResponse(parsed, () => ({}));
+  if (!parsed.value.orderIds || parsed.value.orderIds.length === 0) {
+    return fulfillmentResultResponse({ ok: false, code: "malformed" }, () => ({}));
+  }
+  const opened = await openFulfillment(context, parsed.value.tenantId ?? null);
+  if (!opened.ok) return opened.response;
+  return fulfillmentResultResponse(
+    await opened.service.claim(opened.actor, parsed.value.orderIds, parsed.value.expectedVersions),
+    (batch) => batch,
+  );
+}

package/apps/storefront/src/pages/api/admin/fulfillment/orders/[id]/address.ts

@@ -0,0 +1,32 @@
+/**
+ * Owner-only retrieval of a stored ship-to address.
+ * The read runs only after the owner gate admits the caller.
+ */
+import type { APIContext } from "astro";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
+import {
+  fulfillmentResultResponse,
+  isOpaqueId,
+  openFulfillment,
+} from "@/lib/fulfillment/fulfillmentService";
+
+export const prerender = false;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const access = await requireAdminApiEntry(context, { requireOwner: true });
+  if (!access.ok) {
+    return new Response(JSON.stringify({ error: access.reason }), {
+      status: access.status,
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        "x-robots-tag": "noindex, nofollow",
+      },
+    });
+  }
+  const orderId = context.params.id ?? "";
+  if (!isOpaqueId(orderId)) return fulfillmentResultResponse({ ok: false, code: "not-found" }, () => ({}));
+  const opened = await openFulfillment(context);
+  if (!opened.ok) return opened.response;
+  return fulfillmentResultResponse(await opened.service.readAddress(opened.actor, orderId), (address) => address);
+}

package/apps/storefront/src/pages/api/admin/fulfillment/orders/[id].ts

@@ -0,0 +1,117 @@
+/**
+ * Authenticated owner API for one order's fulfillment commands.
+ * The response is state codes and the fulfillment view. It never returns an address.
+ */
+import type { APIContext } from "astro";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
+import {
+  fulfillmentResultResponse,
+  isOpaqueId,
+  openFulfillment,
+  parseFulfillmentBody,
+  readJsonBody,
+  type FulfillmentCommandOptions,
+  type LabelOutcomeInput,
+} from "@/lib/fulfillment/fulfillmentService";
+
+export const prerender = false;
+
+function ownerRefusal(status: number, reason: string): Response {
+  return new Response(JSON.stringify({ error: reason }), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}
+
+async function requireOwner(context: APIContext): Promise<Response | null> {
+  const access = await requireAdminApiEntry(context, { requireOwner: true });
+  if (access.ok) return null;
+  return ownerRefusal(access.status, access.reason);
+}
+
+const ACTIONS = new Set([
+  "pick",
+  "pack",
+  "release",
+  "hold",
+  "clear-hold",
+  "cancel",
+  "refund",
+  "label-outcome",
+  "hand-off",
+  "return",
+]);
+
+function fail(code: string): Response {
+  return fulfillmentResultResponse({ ok: false, code }, () => ({}));
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const refused = await requireOwner(context);
+  if (refused) return refused;
+  const orderId = context.params.id ?? "";
+  if (!isOpaqueId(orderId)) return fail("not-found");
+  const opened = await openFulfillment(context);
+  if (!opened.ok) return opened.response;
+  return fulfillmentResultResponse(await opened.service.get(opened.actor, orderId), (view) => view);
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const refused = await requireOwner(context);
+  if (refused) return refused;
+  const orderId = context.params.id ?? "";
+  if (!isOpaqueId(orderId)) return fail("not-found");
+  const raw = await readJsonBody(context.request);
+  if (!raw.ok) return fulfillmentResultResponse(raw, () => ({}));
+  const parsed = parseFulfillmentBody(raw.value);
+  if (!parsed.ok) return fulfillmentResultResponse(parsed, () => ({}));
+  if (!ACTIONS.has(parsed.value.action)) return fail("malformed");
+  const opened = await openFulfillment(context, parsed.value.tenantId ?? null);
+  if (!opened.ok) return opened.response;
+  const { service, actor } = opened;
+  const options: FulfillmentCommandOptions = {
+    ...(parsed.value.expectedVersion !== undefined ? { expectedVersion: parsed.value.expectedVersion } : {}),
+    ...(parsed.value.scope !== undefined ? { scope: parsed.value.scope } : {}),
+    ...(parsed.value.carrier !== undefined ? { carrier: parsed.value.carrier } : {}),
+    ...(parsed.value.lines !== undefined ? { lines: parsed.value.lines } : {}),
+  };
+  switch (parsed.value.action) {
+    case "pick":
+      return fulfillmentResultResponse(await service.pick(actor, orderId, options), (view) => view);
+    case "pack":
+      return fulfillmentResultResponse(await service.pack(actor, orderId, options), (view) => view);
+    case "release":
+      return fulfillmentResultResponse(await service.release(actor, orderId, options), (view) => view);
+    case "hold":
+      return fulfillmentResultResponse(await service.hold(actor, orderId, options), (view) => view);
+    case "clear-hold":
+      return fulfillmentResultResponse(await service.clearOperatorHold(actor, orderId, options), (view) => view);
+    case "cancel":
+      return fulfillmentResultResponse(await service.requestCancel(actor, orderId, options), (view) => view);
+    case "refund":
+      return fulfillmentResultResponse(await service.requestRefund(actor, orderId, options), (view) => view);
+    case "hand-off":
+      return fulfillmentResultResponse(await service.handOff(actor, orderId, options), (view) => view);
+    case "return":
+      return fulfillmentResultResponse(service.createReturn(actor, orderId), () => ({}));
+    case "label-outcome": {
+      const outcome = parsed.value.outcome;
+      const adultSignature = parsed.value.adultSignature;
+      if (outcome !== "purchased" && outcome !== "unknown" && outcome !== "voided") return fail("malformed");
+      if (adultSignature !== "accepted" && adultSignature !== "refused" && adultSignature !== "absent") return fail("malformed");
+      const input: LabelOutcomeInput = {
+        outcome,
+        adultSignature,
+        ...(parsed.value.carrier !== undefined ? { carrier: parsed.value.carrier } : {}),
+        ...(parsed.value.expectedVersion !== undefined ? { expectedVersion: parsed.value.expectedVersion } : {}),
+      };
+      return fulfillmentResultResponse(await service.applyLabelOutcome(actor, orderId, input), (view) => view);
+    }
+    default:
+      return fail("malformed");
+  }
+}

package/package.json

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