@tokenoftrust/storefront-runner 4.7.7 → 4.7.8

package/apps/storefront/src/lib/checkout/commerce/commerceAdmission.ts

@@ -51,9 +51,39 @@ export async function readCommerceAdmission(
     stage,
     authorizationId,
   );
-  if (!row) return null;
+  return row ? parseCommerceAdmission(row.snapshot_json, tenantId, stage, authorizationId) : null;
+}
+
+/** Every admission snapshot one tenant and stage holds, keyed by authorization id. A snapshot that fails its own checks is absent. */
+export async function readCommerceAdmissions(
+  db: Queryable,
+  tenantId: string,
+  stage: CommerceStage,
+  authorizationIds: ReadonlySet<string>,
+): Promise<Map<string, CommerceAdmissionSnapshot>> {
+  const admissions = new Map<string, CommerceAdmissionSnapshot>();
+  if (authorizationIds.size === 0) return admissions;
+  const rows = await db.all<{ authorization_id: string; snapshot_json: string }>(
+    `SELECT authorization_id,snapshot_json FROM commerce_admission_snapshots WHERE tenant_id=? AND stage=?`,
+    tenantId,
+    stage,
+  );
+  for (const row of rows) {
+    if (!authorizationIds.has(row.authorization_id)) continue;
+    const admission = parseCommerceAdmission(row.snapshot_json, tenantId, stage, row.authorization_id);
+    if (admission) admissions.set(row.authorization_id, admission);
+  }
+  return admissions;
+}
+
+function parseCommerceAdmission(
+  snapshotJson: string,
+  tenantId: string,
+  stage: CommerceStage,
+  authorizationId: string,
+): CommerceAdmissionSnapshot | null {
   try {
-    const snapshot = JSON.parse(row.snapshot_json) as CommerceAdmissionSnapshot;
+    const snapshot = JSON.parse(snapshotJson) as CommerceAdmissionSnapshot;
     if (
       snapshot.tenantId !== tenantId ||
       snapshot.stage !== stage ||
@@ -106,3 +136,63 @@ export function admissionMatches(
     canonicalJson(sort(event.lines)) === canonicalJson(sort(snapshot.lines))
   );
 }
+
+/** The fields of a provider order event that bind it to a final-cart admission. */
+export interface AdmissionBoundEvent {
+  command: "observe" | "capture" | "refund" | "cancel";
+  eventVersion: number;
+  sourceEventId: string;
+  source: string;
+  sourceOrderId: string;
+  placedAt: string;
+  lines?: readonly { sku: string; quantity: number; unitMinor: number }[];
+  admissionReference?: string;
+  providerCartDigest?: string;
+  destinationDigest?: string;
+}
+
+const COMMAND_RANK = { observe: 0, capture: 1, refund: 2, cancel: 3 } as const;
+
+/**
+ * The newest event that owns the order's cart binding. A paid or cart snapshot owns its lines,
+ * provider cart digest, destination digest and admission reference together; a status-only update
+ * keeps those facts but never replaces them.
+ */
+export function currentCartEvent<E extends AdmissionBoundEvent>(events: readonly E[]): E | undefined {
+  return [...events]
+    .sort(
+      (a, b) =>
+        b.eventVersion - a.eventVersion ||
+        COMMAND_RANK[b.command] - COMMAND_RANK[a.command] ||
+        b.sourceEventId.localeCompare(a.sourceEventId),
+    )
+    .find(
+      (event) =>
+        event.command === "capture" ||
+        event.lines !== undefined ||
+        event.admissionReference !== undefined ||
+        event.providerCartDigest !== undefined ||
+        event.destinationDigest !== undefined,
+    );
+}
+
+/** True when this admission is the one the order's paid events were placed against: same cart, same totals, placed before it expired. */
+export function admissionBindsOrder(
+  admission: CommerceAdmissionSnapshot,
+  events: readonly AdmissionBoundEvent[],
+  order: { source: string; sourceOrderId: string; currency: string; totals: MinorTotals },
+): boolean {
+  const cart = currentCartEvent(events);
+  if (!cart) return false;
+  return (
+    events.every((event) => event.source === order.source && event.sourceOrderId === order.sourceOrderId) &&
+    admissionMatches(admission, {
+      currency: order.currency,
+      totals: order.totals,
+      lines: cart.lines ?? [],
+      providerCartDigest: cart.providerCartDigest,
+      destinationDigest: cart.destinationDigest,
+    }) &&
+    Date.parse(cart.placedAt) <= Date.parse(admission.expiresAt)
+  );
+}

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

@@ -2,7 +2,7 @@
 import { type CommerceEvidence, type CommerceStage } from "@tot/public-runtime";
 import type { Queryable } from "../catalog/d1/catalog.js";
 import { foldCommerceEvents, type StoredCommercePayload } from "../orders/data/orderMapper.js";
-import { admissionMatches, readCommerceAdmission } from "../checkout/commerce/commerceAdmission.js";
+import { admissionBindsOrder, currentCartEvent, readCommerceAdmission } from "../checkout/commerce/commerceAdmission.js";
 import { FulfillmentService } from "./fulfillmentService.js";
 import { fulfillmentDbFromQueryable } from "./store.js";
 const UNKNOWN: CommerceEvidence = { verification: "UNKNOWN", tax: "UNKNOWN", risk: "UNKNOWN", stock: "UNKNOWN" };
@@ -20,44 +20,13 @@ export async function projectCommerceOrder(
   const events = rows.map((row) => (JSON.parse(row.payload) as StoredCommercePayload).source);
   if (!events.length) throw new Error("source-unavailable");
   const snapshot = foldCommerceEvents(events);
-  const commandRank = { observe: 0, capture: 1, refund: 2, cancel: 3 };
-  const sorted = [...events].sort(
-    (a, b) =>
-      b.eventVersion - a.eventVersion ||
-      commandRank[b.command] - commandRank[a.command] ||
-      b.sourceEventId.localeCompare(a.sourceEventId),
-  );
-  // A paid/cart snapshot owns all of its binding fields together. A status-only
-  // update can retain those immutable facts, but cannot replace any of them.
-  const currentCart = sorted.find(
-    (event) =>
-      event.command === "capture" ||
-      event.lines !== undefined ||
-      event.admissionReference !== undefined ||
-      event.providerCartDigest !== undefined ||
-      event.destinationDigest !== undefined,
-  );
+  const currentCart = currentCartEvent(events);
   const lines = currentCart?.lines ?? [];
   const admission = currentCart?.admissionReference
     ? await readCommerceAdmission(db, input.tenantId, input.stage, currentCart.admissionReference)
     : null;
-  const sameSourceOrder = events.every(
-    (event) => event.source === snapshot.source && event.sourceOrderId === snapshot.sourceOrderId,
-  );
   let trusted = false;
-  if (
-    admission &&
-    currentCart &&
-    sameSourceOrder &&
-    admissionMatches(admission, {
-      currency: snapshot.currency,
-      totals: snapshot.totals,
-      lines,
-      providerCartDigest: currentCart.providerCartDigest,
-      destinationDigest: currentCart.destinationDigest,
-    }) &&
-    Date.parse(currentCart.placedAt) <= Date.parse(admission.expiresAt)
-  ) {
+  if (admission && currentCart && admissionBindsOrder(admission, events, snapshot)) {
     if (!db.batchResults) throw new Error("transaction-required");
     const results = await db.batchResults([
       {

package/apps/storefront/src/lib/orders/admin/orderActions.ts

@@ -0,0 +1,196 @@
+/**
+ * Orders workspace actions. Every button in the order detail answers: it opens the part of the
+ * order it names, moves to the tab that resolves it, loads the owner-only address, or says why
+ * nothing can be done from here. `planOrderAction` decides on the server; `mountOrderActions`
+ * carries the plan out in the browser. Neither ever leaves a click without a visible result.
+ */
+
+export type OrderActionKind = "reveal" | "tab" | "address" | "explain";
+
+export interface OrderActionPlan {
+  kind: OrderActionKind;
+  /** `reveal`: selector of the section inside the order record. `tab`: the admin tab id. */
+  target: string;
+  message: string;
+}
+
+export interface OrderActionInput {
+  /** The readiness check key, or `blocker` for the order-level Resolve hold / next-step buttons. */
+  check: string;
+  /** The state the check reports, e.g. `captured`, `UNKNOWN`, `fresh`. */
+  state: string;
+  /** The order's blocker label when the order is held. */
+  blocker?: string | null;
+}
+
+const CLEAR_STATES = new Set(["fresh", "not-required"]);
+
+function evidenceMessage(label: string, state: string): string {
+  if (CLEAR_STATES.has(state)) return `${label} evidence is ${state}. Activity and evidence below shows how this order got here.`;
+  return `${label} evidence is ${state}, so this order stays held. Evidence is recorded when the shopper passes final cart; an order whose final cart is not on record cannot be cleared from admin.`;
+}
+
+export function planOrderAction(input: OrderActionInput): OrderActionPlan {
+  switch (input.check) {
+    case "payment_capture":
+      return {
+        kind: "explain",
+        target: "",
+        message:
+          input.state === "captured" || input.state === "Captured"
+            ? "Payment is captured."
+            : "Payment is captured by the checkout provider and recorded here when it confirms. Admin cannot capture it; check the transaction at the provider.",
+      };
+    case "tax_and_fees":
+      return { kind: "reveal", target: "[data-orders-totals]", message: "Items and totals are open below." };
+    case "identity_and_age":
+      return { kind: "reveal", target: "[data-orders-evidence]", message: evidenceMessage("Identity and age", input.state) };
+    case "risk":
+      return { kind: "reveal", target: "[data-orders-evidence]", message: evidenceMessage("Risk", input.state) };
+    case "address":
+      return { kind: "address", target: "[data-orders-address]", message: "" };
+    case "stock":
+      return {
+        kind: "explain",
+        target: "",
+        message:
+          input.state === "confirmed"
+            ? "Stock is confirmed for this order."
+            : `Stock is ${input.state} for this order. Stock is confirmed when the final-cart reservation matches the paid order.`,
+      };
+    case "fulfillment":
+      return { kind: "tab", target: "fulfillment", message: "Fulfillment holds are worked in the Fulfillment tab." };
+    case "blocker":
+      return blockerPlan(input);
+    default:
+      return { kind: "explain", target: "", message: "Nothing can be done for this check from here." };
+  }
+}
+
+function blockerPlan(input: OrderActionInput): OrderActionPlan {
+  if (!input.blocker) {
+    return { kind: "explain", target: "", message: "This order has no hold." };
+  }
+  if (input.blocker === "Payment capture") return planOrderAction({ check: "payment_capture", state: input.state });
+  if (input.blocker === "Evidence review" || input.blocker === "Age verification hold" || input.blocker === "Verification unknown") {
+    return planOrderAction({ check: "identity_and_age", state: input.state });
+  }
+  return { kind: "tab", target: "fulfillment", message: `${input.blocker}: holds are worked in the Fulfillment tab.` };
+}
+
+/** Owner address response, as stored. Only these fields are shown, in this order. */
+const ADDRESS_FIELDS = ["name", "line1", "line2", "city", "region", "postalCode", "country"] as const;
+
+export function addressLines(address: unknown): string[] {
+  if (address === null || typeof address !== "object" || Array.isArray(address)) return [];
+  const record = address as Record<string, unknown>;
+  const lines: string[] = [];
+  for (const key of ADDRESS_FIELDS) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") lines.push(value.trim());
+  }
+  return lines;
+}
+
+export const ADDRESS_NONE =
+  "No ship-to address is stored for this order. The checkout confirmation carries none and the order ledger keeps no customer data.";
+export const ADDRESS_DENIED = "Only the store owner can view a ship-to address.";
+export const ADDRESS_FAILED = "The address could not be loaded. Try again.";
+
+export interface OrderActionDeps {
+  fetch: typeof fetch;
+  /** The fulfillment API root for the selected store, or null when this page cannot reach it. */
+  api: string | null;
+  navigate: (tab: string) => boolean;
+}
+
+function show(note: HTMLElement | null, lines: readonly string[]): void {
+  if (!note) return;
+  note.replaceChildren(...lines.map((line) => Object.assign(document.createElement("span"), { textContent: line })));
+  note.hidden = false;
+}
+
+async function loadAddress(orderId: string, note: HTMLElement | null, deps: OrderActionDeps): Promise<void> {
+  if (!deps.api) {
+    show(note, [ADDRESS_FAILED]);
+    return;
+  }
+  show(note, ["Loading address…"]);
+  try {
+    const response = await deps.fetch(`${deps.api}/orders/${encodeURIComponent(orderId)}/address`, {
+      credentials: "same-origin",
+      cache: "no-store",
+    });
+    if (response.status === 404) return show(note, [ADDRESS_NONE]);
+    if (response.status === 401 || response.status === 403) return show(note, [ADDRESS_DENIED]);
+    if (!response.ok) return show(note, [ADDRESS_FAILED]);
+    const lines = addressLines(await response.json());
+    show(note, lines.length ? lines : [ADDRESS_NONE]);
+  } catch {
+    show(note, [ADDRESS_FAILED]);
+  }
+}
+
+/**
+ * Wire every `[data-orders-action]` button under `root`. The button carries its plan as
+ * `data-orders-action-kind|target|message`; its note is the nearest `[data-orders-action-note]` in
+ * the same record. Order-level buttons (`data-orders-resolve-hold`) act through the selected record's
+ * `[data-orders-blocker-action]`.
+ */
+export function mountOrderActions(root: HTMLElement, deps: OrderActionDeps): void {
+  const run = (button: HTMLElement, record: HTMLElement): void => {
+    const kind = button.dataset.ordersActionKind as OrderActionKind | undefined;
+    const target = button.dataset.ordersActionTarget ?? "";
+    const message = button.dataset.ordersActionMessage ?? "";
+    const orderId = record.dataset.ordersDetailRecord ?? "";
+    const scope = button.closest<HTMLElement>("[data-orders-action-scope]");
+    const note = scope
+      ? scope.querySelector<HTMLElement>("[data-orders-action-note]")
+      : record.querySelector<HTMLElement>("[data-orders-record-note]");
+    if (kind === "reveal") {
+      const section = record.querySelector<HTMLDetailsElement>(target);
+      if (section) {
+        section.open = true;
+        section.scrollIntoView?.({ block: "nearest" });
+      }
+      show(note, [message]);
+    } else if (kind === "tab") {
+      show(note, [deps.navigate(target) ? message : `${message} The ${target} tab is not available to this account.`]);
+    } else if (kind === "address") {
+      void loadAddress(orderId, record.querySelector<HTMLElement>(target) ?? note, deps);
+    } else {
+      show(note, [message || "Nothing can be done from here."]);
+    }
+  };
+
+  root.addEventListener("click", (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    const button = origin?.closest<HTMLElement>("[data-orders-action]");
+    if (button && root.contains(button)) {
+      const record = button.closest<HTMLElement>("[data-orders-detail-record]");
+      if (record) run(button, record);
+      return;
+    }
+    const orderLevel = origin?.closest<HTMLElement>("[data-orders-resolve-hold], [data-orders-next-step]");
+    if (!orderLevel || !root.contains(orderLevel)) return;
+    const selected = orderLevel.dataset.ordersNextStep ?? root.querySelector<HTMLElement>("[data-orders-detail-root]")?.dataset.adminSelectedId ?? "";
+    const record = Array.from(root.querySelectorAll<HTMLElement>("[data-orders-detail-record]")).find(
+      (item) => item.dataset.ordersDetailRecord === selected,
+    );
+    const action = record?.querySelector<HTMLElement>("[data-orders-blocker-action]");
+    if (!record || !action) {
+      show(root.querySelector<HTMLElement>("[data-orders-root-note]"), ["Select an order first."]);
+      return;
+    }
+    record.hidden = false;
+    record.scrollIntoView?.({ block: "nearest" });
+    run(action, record);
+  });
+}
+
+/** Switch the admin shell to a tab by id; false when the tab is not in this page. */
+export function navigateAdminTab(tab: string): boolean {
+  if (!document.getElementById(tab)) return false;
+  window.location.hash = `#${tab}`;
+  return true;
+}

package/apps/storefront/src/lib/orders/admin/orderSource.ts

@@ -19,6 +19,7 @@ import type {
   CheckoutOrderListResponse,
   CheckoutOrderPayment,
   CheckoutOrderSummary,
+  CommerceEvidence,
   CommerceScope,
   CommerceStage,
   CustomizationEnv,
@@ -193,9 +194,10 @@ interface LedgerOrder {
 function ledgerOrder(entry: CommerceOrderBookEntry): LedgerOrder {
   const placedAt = isoInstant(entry.placedAt);
   const snapshot = entry.events.length > 0 ? foldCommerceEvents(entry.events) : null;
-  const payment = snapshot?.payment ?? entry.payment;
-  const fulfillment = snapshot?.fulfillment ?? entry.fulfillment;
-  const evidence = snapshot?.verificationDetail ?? { verification: "UNKNOWN", tax: "UNKNOWN", risk: "UNKNOWN", stock: "UNKNOWN" };
+  // The order row is the state of record: provider events and fulfillment commands both write it.
+  const { payment, fulfillment } = entry;
+  const evidence: CommerceEvidence =
+    entry.admitted?.evidence ?? snapshot?.verificationDetail ?? { verification: "UNKNOWN", tax: "UNKNOWN", risk: "UNKNOWN", stock: "UNKNOWN" };
   const totals = snapshot?.totals ?? { subtotalMinor: entry.amountMinor, shippingMinor: 0, taxMinor: 0, totalMinor: entry.amountMinor };
   const lines =
     [...entry.events].sort((a, b) => b.eventVersion - a.eventVersion).find((event) => event.lines?.length)?.lines ?? [];
@@ -217,10 +219,10 @@ function ledgerOrder(entry: CommerceOrderBookEntry): LedgerOrder {
   const itemCount = lines.reduce((sum, line) => sum + line.quantity, 0);
   const itemsSummary =
     lines.length === 0 ? "Items not recorded" : lines.length === 1 ? lines[0]!.sku : `${lines[0]!.sku} +${lines.length - 1} more`;
-  const verification: Record<string, string> = {};
+  const verification: Record<string, string> = { stockState: entry.stock };
   for (const key of ["verification", "tax", "risk", "stock"] as const) {
     verification[key] = evidence[key];
-    verification[`${key}Source`] = "commerce-ledger";
+    verification[`${key}Source`] = entry.admitted?.provenance[key].source ?? "commerce-ledger";
     verification[`${key}AsOf`] = placedAt;
   }
 

package/apps/storefront/src/lib/orders/admin/services/orders.ts

@@ -34,6 +34,7 @@ import {
   paymentIsCaptured,
   publicCommerceEvent,
   readOwnerAddress,
+  STOCK_STATES,
   sumMinor,
   totalsMatch,
 } from "@tot/public-runtime";
@@ -209,6 +210,21 @@ function readSourcedEvidence(
   };
 }
 
+/** Stock allocation state the order source recorded, never inferred from stock evidence. */
+function readStockState(verification: CheckoutOrderVerification | null): SourcedState<StockState> {
+  const state = verification?.stockState;
+  if (typeof state !== "string" || !(STOCK_STATES as readonly string[]).includes(state)) {
+    return { state: "UNKNOWN", source: "absent", asOf: null };
+  }
+  const source = verification?.stockSource;
+  const asOf = verification?.stockAsOf;
+  return {
+    state: state as StockState,
+    source: typeof source === "string" && source.length > 0 ? source : "absent",
+    asOf: typeof asOf === "string" ? asOf : null,
+  };
+}
+
 export function readinessColumns(order: ScrappyOrderRecord): OrderReadinessColumn[] {
   return [
     { key: "payment", state: order.payment.state, source: order.payment.source, asOf: order.payment.asOf },
@@ -279,7 +295,7 @@ function checkoutRecord(order: CheckoutOrderSummary, scope: CommerceScope): Scra
     tax: readSourcedEvidence(order.verification, "tax"),
     verification: readSourcedEvidence(order.verification, "verification"),
     risk: readSourcedEvidence(order.verification, "risk"),
-    stock: { state: "UNKNOWN", source: "absent", asOf: null },
+    stock: readStockState(order.verification),
     stockEvidence: readSourcedEvidence(order.verification, "stock"),
     fulfillment: {
       state: fulfillmentFromCheckout(order.fulfillment),

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

@@ -17,9 +17,12 @@ import {
   idempotencyKey,
   paginateOrders,
   sha256Hex,
+  type CommerceEvidence,
+  type CommerceEvidenceProvenance,
   type CommerceStage,
   type PaymentState,
 } from "@tot/public-runtime";
+import { admissionBindsOrder, currentCartEvent, readCommerceAdmissions } from "../../checkout/commerce/commerceAdmission.js";
 import {
   foldCommerceEvents,
   packCommercePayload,
@@ -230,8 +233,15 @@ export interface CommerceOrderBookEntry {
   currency: string;
   payment: PaymentState;
   fulfillment: CommerceSnapshot["fulfillment"];
+  stock: CommerceSnapshot["stock"];
   amountMinor: number;
   events: CommerceSourceEvent[];
+  /**
+   * The final-cart evidence this order was placed against, present only when the admission the paid
+   * events name is the same cart, totals and destination and had not expired at placement. The paid
+   * events carry no evidence of their own.
+   */
+  admitted: { evidence: CommerceEvidence; provenance: CommerceEvidenceProvenance } | null;
 }
 
 export interface CommerceAggregate {
@@ -504,16 +514,33 @@ export class ScrappyOrderLedger {
       list.push(parsed.source);
       events.set(row.order_id, list);
     }
-    return rows.map((row) => ({
-      orderId: row.order_id,
-      source: row.source,
-      placedAt: row.placed_at,
-      currency: row.currency,
-      payment: row.payment_state,
-      fulfillment: row.fulfillment_state,
-      amountMinor: row.amount_minor,
-      events: events.get(row.order_id) ?? [],
-    }));
+    const references = new Set<string>();
+    for (const list of events.values()) {
+      const reference = currentCartEvent(list)?.admissionReference;
+      if (reference) references.add(reference);
+    }
+    const admissions = await readCommerceAdmissions(this.db, tenantId, stage, references);
+    return rows.map((row) => {
+      const orderEvents = events.get(row.order_id) ?? [];
+      const reference = currentCartEvent(orderEvents)?.admissionReference;
+      const admission = reference ? admissions.get(reference) : undefined;
+      const bound =
+        admission !== undefined &&
+        orderEvents.length > 0 &&
+        admissionBindsOrder(admission, orderEvents, foldCommerceEvents(orderEvents));
+      return {
+        orderId: row.order_id,
+        source: row.source,
+        placedAt: row.placed_at,
+        currency: row.currency,
+        payment: row.payment_state,
+        fulfillment: row.fulfillment_state,
+        stock: row.stock_state,
+        amountMinor: row.amount_minor,
+        events: orderEvents,
+        admitted: bound ? { evidence: admission.evidence, provenance: admission.provenance } : null,
+      };
+    });
   }
 
   /** Reset one outbox row for this tenant and stage. Does not write another order. */

package/package.json

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