@tokenoftrust/storefront-runner 4.4.0 → 4.6.0

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

@@ -0,0 +1,342 @@
+/**
+ * Where a tenant's admin reads its orders. Resolved once per request, so the Orders tab, the
+ * `/api/admin/orders` routes and the sidebar status always describe the same connection.
+ *
+ * A tenant admitted to the shared ToT checkout store (checkout's `admitSharedStoreTenant`, the
+ * same admission the signed order intake applies) has its paid orders forwarded into the platform
+ * ledger (`STOREFRONT_APPS_DB`, `scrappy_commerce_orders`) under this Worker's `COMMERCE_STAGE`.
+ * The shared store's partner API returns every tenant's transactions unfiltered, so the ledger is
+ * the only per-tenant record for that tenant. A tenant on its own FoxyCart store reads that
+ * store's partner API with `FOXY_ORDER_API_KEY`.
+ *
+ * The ledger carries no customer identity and no address (the intake refuses both), so a ledger
+ * order names no customer and has no shipping address here.
+ */
+import type {
+  CheckoutOrderDetail,
+  CheckoutOrderFulfillment,
+  CheckoutOrderListFilters,
+  CheckoutOrderListResponse,
+  CheckoutOrderPayment,
+  CheckoutOrderSummary,
+  CommerceScope,
+  CommerceStage,
+  CustomizationEnv,
+  PaymentState,
+} from "@tot/public-runtime";
+import { evidencePermitsRelease, paginateOrders } from "@tot/public-runtime";
+import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
+import { readD1, readEnv } from "@/lib/publication/shared/env";
+import { fromD1, type Queryable } from "@/lib/catalog/d1/catalog.js";
+import { ScrappyOrderLedger, type CommerceOrderBookEntry } from "../data/ordersStore.js";
+import { foldCommerceEvents, type CommerceSourceEvent } from "../data/orderMapper.js";
+import {
+  OrderApiError,
+  createCheckoutOrderClient,
+  orderApiBaseUrl,
+  type CheckoutOrderClient,
+} from "./orderClient";
+
+/** Why a tenant has no order source. Each names what connects it. */
+export type OrderSourceGap = "no-tenant" | "stage-unknown" | "ledger-unavailable" | "partner-key-missing";
+
+/** Ledger health: when the last paid order arrived, and reservations no payment has confirmed. */
+export interface LedgerSyncStatus {
+  orders: number;
+  lastOrderAt: string | null;
+  unconfirmed: { count: number; oldestAt: string | null };
+}
+
+/** Which FoxyCart store takes this tenant's payments, or null when no store is selected. */
+export type CheckoutStore = "shared-test-store" | "own-store" | null;
+
+export type OrderSource =
+  | {
+      kind: "ledger";
+      checkout: "shared-test-store";
+      scope: CommerceScope;
+      client: CheckoutOrderClient;
+      status: (now?: Date) => Promise<LedgerSyncStatus>;
+    }
+  | { kind: "partner-api"; checkout: "own-store"; scope: CommerceScope; client: CheckoutOrderClient }
+  | { kind: "not-connected"; checkout: CheckoutStore; gap: OrderSourceGap };
+
+export interface OrderSourceDeps {
+  admitSharedStoreTenant: (tenantId: string) => Promise<{ ok: boolean }>;
+  readEnv: (name: string) => Promise<string | undefined>;
+  readLedgerDb: () => Promise<Queryable | null>;
+}
+
+/**
+ * Worker deps. The caller passes checkout's `admitSharedStoreTenant`, the same admission the
+ * signed order intake applies, so reading and writing the ledger cannot disagree on who is in it.
+ */
+export function workerOrderSourceDeps(
+  admitSharedStoreTenant: OrderSourceDeps["admitSharedStoreTenant"],
+): OrderSourceDeps {
+  return {
+    admitSharedStoreTenant,
+    readEnv: async (name) => (await readEnv(name)) ?? undefined,
+    readLedgerDb: async () => {
+      const d1 = await readD1("STOREFRONT_APPS_DB");
+      return d1 ? fromD1(d1) : null;
+    },
+  };
+}
+
+export async function resolveOrderSource(
+  input: { tenantId: string; customizationEnv: CustomizationEnv | undefined },
+  deps: OrderSourceDeps,
+): Promise<OrderSource> {
+  const tenantId = input.tenantId.trim();
+  if (!tenantId) return { kind: "not-connected", checkout: null, gap: "no-tenant" };
+
+  if ((await deps.admitSharedStoreTenant(tenantId)).ok) {
+    const checkout = "shared-test-store";
+    const stage = await deps.readEnv("COMMERCE_STAGE");
+    if (stage !== "preview" && stage !== "publication") return { kind: "not-connected", checkout, gap: "stage-unknown" };
+    const db = await deps.readLedgerDb();
+    if (!db) return { kind: "not-connected", checkout, gap: "ledger-unavailable" };
+    const book = ledgerOrderBook(new ScrappyOrderLedger(db), { tenantId, stage });
+    return { kind: "ledger", checkout, scope: { tenantId, stage }, client: book.client, status: book.status };
+  }
+
+  const checkout = "own-store";
+  const stage = commerceStageForEnv(input.customizationEnv);
+  if (!stage) return { kind: "not-connected", checkout, gap: "stage-unknown" };
+  const bearer = await deps.readEnv("FOXY_ORDER_API_KEY");
+  if (!bearer) return { kind: "not-connected", checkout, gap: "partner-key-missing" };
+  return {
+    kind: "partner-api",
+    checkout,
+    scope: { tenantId, stage },
+    client: createCheckoutOrderClient({
+      baseUrl: orderApiBaseUrl(input.customizationEnv ?? "test"),
+      appDomain: tenantId,
+      bearer,
+    }),
+  };
+}
+
+/** Merchant copy for a gap: what is missing and who connects it. */
+export function orderSourceGapMessage(gap: OrderSourceGap): string {
+  switch (gap) {
+    case "no-tenant":
+      return "No store is selected.";
+    case "stage-unknown":
+      return "This environment does not declare a commerce stage, so it has no order record to read. Token of Trust support connects it.";
+    case "ledger-unavailable":
+      return "The platform order ledger is not bound in this environment. Token of Trust support connects it.";
+    case "partner-key-missing":
+      return "This store checks out on its own FoxyCart store, and its partner API key is not provisioned on the platform. Token of Trust support provisions it.";
+  }
+}
+
+export interface OrderSyncHealth {
+  value: "Not connected" | "Connected" | "Check";
+  detail: string;
+}
+
+/** The sidebar's order-sync row, from the same source the Orders tab reads. */
+export function orderSyncHealth(source: OrderSource, status: LedgerSyncStatus | null): OrderSyncHealth {
+  if (source.kind === "not-connected") return { value: "Not connected", detail: orderSourceGapMessage(source.gap) };
+  if (source.kind === "partner-api" || !status) return { value: "Connected", detail: "Reads this store's checkout orders." };
+  if (status.unconfirmed.count > 0) {
+    const n = status.unconfirmed.count;
+    return {
+      value: "Check",
+      detail: `${n} checkout${n === 1 ? "" : "s"} in the last 7 days passed final cart with no payment confirmation received.`,
+    };
+  }
+  return {
+    value: "Connected",
+    detail: status.lastOrderAt ? `Last paid order ${status.lastOrderAt}.` : "No paid orders yet.",
+  };
+}
+
+/** The sidebar's checkout row: which store takes this tenant's payments. */
+export function checkoutStoreLabel(checkout: CheckoutStore): string {
+  if (checkout === "shared-test-store") return "Test store";
+  if (checkout === "own-store") return "Own store";
+  return "Not connected";
+}
+
+/** The ledger's money is integer minor units of a two-decimal currency. */
+function toMajor(minor: number): number {
+  return minor / 100;
+}
+
+/** Provider timestamps arrive with a colonless offset; compare and page on one ISO form. */
+function isoInstant(value: string): string {
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+}
+
+function paymentOf(payment: PaymentState): CheckoutOrderPayment {
+  if (payment === "captured") return "captured";
+  if (payment === "refunded" || payment === "refund_requested" || payment === "refund_unknown" || payment === "voided") {
+    return "refunded";
+  }
+  return "authorized";
+}
+
+interface LedgerOrder {
+  summary: CheckoutOrderSummary;
+  detail: CheckoutOrderDetail;
+}
+
+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" };
+  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 ?? [];
+
+  const releasable = payment === "captured" && evidencePermitsRelease(evidence);
+  let state: CheckoutOrderFulfillment;
+  let blocker: string | null = null;
+  if (fulfillment === "handed_off") state = "completed";
+  else if (fulfillment === "cancelled") {
+    state = "completed";
+    blocker = "Cancelled";
+  } else if (fulfillment === "UNKNOWN") state = "unfulfilled";
+  else if (fulfillment === "ready" && releasable) state = "ready_to_ship";
+  else {
+    state = "hold_review_required";
+    blocker = payment !== "captured" ? "Payment capture" : evidencePermitsRelease(evidence) ? "Manual review" : "Evidence review";
+  }
+
+  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> = {};
+  for (const key of ["verification", "tax", "risk", "stock"] as const) {
+    verification[key] = evidence[key];
+    verification[`${key}Source`] = "commerce-ledger";
+    verification[`${key}AsOf`] = placedAt;
+  }
+
+  const summary: CheckoutOrderSummary = {
+    id: entry.orderId,
+    placedAt,
+    currency: entry.currency,
+    customer: { id: null, name: "Checkout customer" },
+    itemsSummary,
+    itemCount,
+    total: toMajor(totals.totalMinor),
+    payment: paymentOf(payment),
+    fulfillment: state,
+    blocker,
+    verification,
+  };
+  return {
+    summary,
+    detail: {
+      ...summary,
+      lineItems: lines.map((line) => ({ sku: line.sku, name: line.sku, quantity: line.quantity, unitPrice: toMajor(line.unitMinor) })),
+      totals: {
+        subtotal: toMajor(totals.subtotalMinor),
+        shipping: toMajor(totals.shippingMinor),
+        estimatedTax: toMajor(totals.taxMinor),
+        taxesAndFees: 0,
+        total: toMajor(totals.totalMinor),
+      },
+      shippingAddress: null,
+      verificationDetail: { readinessChecks: [], evidenceTimeline: [] },
+    },
+  };
+}
+
+function matchesQueue(order: CheckoutOrderSummary, queue: string | undefined): boolean {
+  switch (queue) {
+    case undefined:
+    case "all":
+      return true;
+    case "needs_attention":
+      return order.fulfillment === "hold_review_required";
+    case "ready_to_ship":
+      return order.fulfillment === "ready_to_ship";
+    case "unfulfilled":
+      return order.fulfillment === "hold_review_required" || order.fulfillment === "ready_to_ship";
+    case "completed":
+      return order.fulfillment === "completed";
+    default:
+      return false;
+  }
+}
+
+function listLimit(limit: number | undefined): number {
+  if (limit === undefined || !Number.isFinite(limit)) return 25;
+  return Math.min(100, Math.max(1, Math.trunc(limit)));
+}
+
+/** A shopper who abandons at payment leaves a reservation too, so only recent ones are reported. */
+export const UNCONFIRMED_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Paid orders and sync status over one tenant's ledger book, read once per request. A `scrappy`
+ * reservation is never listed as an order; one from the last seven days that no provider event
+ * has confirmed is reported as waiting on payment confirmation.
+ */
+export function ledgerOrderBook(
+  ledger: Pick<ScrappyOrderLedger, "readOrderBook">,
+  scope: { tenantId: string; stage: CommerceStage },
+): { client: CheckoutOrderClient; status: (now?: Date) => Promise<LedgerSyncStatus> } {
+  let loaded: Promise<{ orders: LedgerOrder[]; unconfirmed: CommerceOrderBookEntry[] }> | null = null;
+  const load = () =>
+    (loaded ??= ledger.readOrderBook(scope.tenantId, scope.stage).then((book) => {
+      const paid = book.filter((entry) => entry.source !== "scrappy");
+      const confirmed = new Set(
+        paid.flatMap((entry) => entry.events.map((event: CommerceSourceEvent) => event.admissionReference)).filter(Boolean),
+      );
+      return {
+        orders: paid.map(ledgerOrder),
+        unconfirmed: book.filter((entry) => entry.source === "scrappy" && !confirmed.has(entry.orderId)),
+      };
+    }));
+
+  const client: CheckoutOrderClient = {
+    async listOrders(filters?: CheckoutOrderListFilters): Promise<CheckoutOrderListResponse> {
+      const { orders } = await load();
+      const from = filters?.from ? isoInstant(filters.from) : null;
+      const to = filters?.to ? isoInstant(filters.to) : null;
+      const matching = orders
+        .map((order) => order.summary)
+        .filter((order) => matchesQueue(order, filters?.queue))
+        .filter((order) => !filters?.status || order.payment === filters.status)
+        .filter((order) => (!from || order.placedAt >= from) && (!to || order.placedAt < to));
+      const limit = listLimit(filters?.limit);
+      const page = paginateOrders(matching, limit, filters?.cursor ?? null);
+      return {
+        orders: page.orders,
+        page: { limit, cursor: filters?.cursor ?? null, nextCursor: page.nextCursor, total: matching.length },
+      };
+    },
+    async getOrder(orderId: string): Promise<CheckoutOrderDetail> {
+      const { orders } = await load();
+      const found = orders.find((order) => order.summary.id === orderId);
+      if (!found) throw new OrderApiError("order_not_found", 404);
+      return found.detail;
+    },
+  };
+
+  const status = async (now: Date = new Date()): Promise<LedgerSyncStatus> => {
+    const { orders, unconfirmed } = await load();
+    const placed = orders.map((order) => order.summary.placedAt).sort();
+    const since = new Date(now.getTime() - UNCONFIRMED_WINDOW_MS).toISOString();
+    const waiting = unconfirmed
+      .map((entry) => isoInstant(entry.placedAt))
+      .filter((at) => at >= since)
+      .sort();
+    return {
+      orders: orders.length,
+      lastOrderAt: placed[placed.length - 1] ?? null,
+      unconfirmed: { count: waiting.length, oldestAt: waiting[0] ?? null },
+    };
+  };
+
+  return { client, status };
+}

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

@@ -52,7 +52,7 @@ import type {
 } from "../viewmodels/orders";
 import type { CheckoutOrderClient } from "../orderClient";
 
-const EVIDENCE_STATES: readonly EvidenceState[] = ["fresh", "UNKNOWN", "stale", "unreadable", "absent"];
+const EVIDENCE_STATES: readonly EvidenceState[] = ["fresh", "not-required", "UNKNOWN", "stale", "unreadable", "absent"];
 const REFUND_PAYMENTS: ReadonlySet<PaymentState> = new Set(["refunded", "refund_requested", "refund_unknown"]);
 
 export interface SourcedState<T extends string = string> {

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

@@ -8,6 +8,7 @@
  * internals — and never lets a raw customer identifier leave this module:
  * customer identity is always the per-(tenant, install) `customerHash`.
  */
+import { skuFromToken } from "@tot/public-runtime/sku";
 import { customerHash } from "../../integrations/apps/orders/customerHash.js";
 import type { FoxyOrder, FoxyOrderLineItem } from "../providers/foxyOrderClient.js";
 import {
@@ -82,9 +83,10 @@ function toIsoDateTime(foxyDate: string): string {
   return Number.isNaN(parsed.getTime()) ? foxyDate : parsed.toISOString();
 }
 
+/** The provider carries the signed checkout product code; the order names the stored SKU it encodes. */
 function toContractLineItem(item: FoxyOrderLineItem): ContractOrderLineItem {
   return {
-    sku: item.sku,
+    sku: skuFromToken(item.sku) ?? item.sku,
     quantity: item.quantity,
     lineTotal: item.totalPrice,
   };
@@ -264,11 +266,15 @@ export function normalizeCommerceEvent(value: unknown): CommerceSourceEvent | "m
   if (!(STOCK_STATES as readonly string[]).includes(stock)) return "malformed";
   if (!(FULFILLMENT_STATES as readonly string[]).includes(fulfillment)) return "malformed";
   if (!(LABEL_STATES as readonly string[]).includes(label)) return "malformed";
-  const lines = value.lines;
-  if (lines !== undefined && (!Array.isArray(lines) || lines.some(line => !isRecord(line) ||
-      typeof line.sku !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(line.sku) ||
+  // A line's `sku` arrives as the signed checkout product code and is kept as the line key it
+  // encodes, the key the admission record and the stock allocations carry.
+  const rawLines = value.lines;
+  if (rawLines !== undefined && (!Array.isArray(rawLines) || rawLines.some(line => !isRecord(line) ||
+      skuFromToken(line.sku) === null ||
       !Number.isSafeInteger(line.quantity) || Number(line.quantity) < 1 ||
       !Number.isSafeInteger(line.unitMinor) || Number(line.unitMinor) < 0))) return "malformed";
+  const lines = rawLines === undefined ? undefined : (rawLines as Record<string, unknown>[]).map(line =>
+    ({ ...line, sku: skuFromToken(line.sku)! }));
   for (const key of ["admissionReference", "providerCartDigest", "destinationDigest"] as const) {
     if (value[key] !== undefined && (typeof value[key] !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(value[key] as string))) return "malformed";
   }

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

@@ -222,6 +222,18 @@ export interface CommerceOrderQueryRow {
   eventVersion: number;
 }
 
+/** One ledger order row and the source events recorded for it. */
+export interface CommerceOrderBookEntry {
+  orderId: string;
+  source: string;
+  placedAt: string;
+  currency: string;
+  payment: PaymentState;
+  fulfillment: CommerceSnapshot["fulfillment"];
+  amountMinor: number;
+  events: CommerceSourceEvent[];
+}
+
 export interface CommerceAggregate {
   count: number;
   amountMinor: number;
@@ -468,6 +480,42 @@ export class ScrappyOrderLedger {
     return { count, amountMinor, byPayment };
   }
 
+  /**
+   * Every order row for one tenant and stage, each with the source events recorded for it. Two
+   * reads, never one per order. A `scrappy` row is a final-cart reservation, not a paid order: a
+   * provider event names it in `admissionReference` once that payment reaches the ledger.
+   */
+  async readOrderBook(tenantId: string, stage: CommerceStage): Promise<CommerceOrderBookEntry[]> {
+    const rows = await this.db.all<CommerceOrderRow>(
+      `SELECT * FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ?`,
+      tenantId,
+      stage,
+    );
+    const payloads = await this.db.all<{ order_id: string; payload: string }>(
+      `SELECT order_id, payload FROM scrappy_commerce_outbox WHERE tenant_id = ? AND stage = ?`,
+      tenantId,
+      stage,
+    );
+    const events = new Map<string, CommerceSourceEvent[]>();
+    for (const row of payloads) {
+      const parsed = JSON.parse(row.payload) as StoredCommercePayload;
+      if (!parsed.source) continue;
+      const list = events.get(row.order_id) ?? [];
+      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) ?? [],
+    }));
+  }
+
   /** 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 }>(

package/apps/storefront/src/lib/publication/shared/url.ts

@@ -96,6 +96,25 @@ export function buildQueryString(
   return s ? `?${s}` : "";
 }
 
+/** Facet values shown before the nested "Show more" disclosure. */
+export const FACET_VISIBLE_VALUES = 8;
+
+/**
+ * Split a facet group's values into the always-visible head and the collapsed
+ * remainder: the first FACET_VISIBLE_VALUES, plus every selected value wherever
+ * it sits, so a selected value is never hidden in the remainder.
+ */
+export function splitFacetValues<T extends { value: string }>(
+  values: readonly T[],
+  isSelected: (value: string) => boolean,
+  limit: number = FACET_VISIBLE_VALUES,
+): { shown: T[]; rest: T[] } {
+  const shown: T[] = [];
+  const rest: T[] = [];
+  values.forEach((fv, i) => (i < limit || isSelected(fv.value) ? shown : rest).push(fv));
+  return { shown, rest };
+}
+
 /** Toggle a single facet value on/off, returning the new querystring (page reset). */
 export function toggleFacet(
   current: ListProductsQuery,

package/apps/storefront/src/middleware/renderChain.ts

@@ -948,6 +948,9 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     const key = pageKey;
     await timed(timing, "page-cache", () => putCachedPage(cache, key, response));
   }
+  // A preview-token (`test`) render is unpublished content shown to one viewer: no
+  // browser, proxy, or CDN may keep it or hand it to the next visitor of this URL.
+  if (customization.env === "test") response.headers.set("Cache-Control", "private, no-store");
   // MATERIALIZE-ONLY capture (ADR 0013): expose the tenant's resolved route-document
   // Cache-Control so the publish/materialize plane can bake it into the bundle
   // manifest (the same capture pattern as CSP). Gated on the materialize probe

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

@@ -1,23 +1,16 @@
 /**
  * `GET /api/admin/orders/:id` — one order's full detail for the Orders tab.
  *
- * Server-side proxy to checkout `GET /commerce/orders/:orderId` for the
- * resolved tenant + env. Bearer stays server-side. Address is included only
- * for an owner of this tenant and stage. Readiness is assessed, not inferred.
- * Read-only.
+ * Reads one order from the source `resolveOrderSource` picks for the resolved tenant + env.
+ * Any bearer stays server-side. Address is included only for an owner of this tenant and stage.
+ * Readiness is assessed, not inferred. Read-only.
  */
 import type { APIContext } from "astro";
-import { readEnv } from "@/lib/publication/shared/env";
 import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
-import {
-  commerceActorForAdmin,
-  createCheckoutOrderClient,
-  orderApiBaseUrl,
-  OrderApiError,
-  projectCheckoutOrder,
-} from "@/lib/orders/admin/orderClient";
+import { commerceActorForAdmin, OrderApiError, projectCheckoutOrder } from "@/lib/orders/admin/orderClient";
+import { resolveOrderSource, workerOrderSourceDeps } from "@/lib/orders/admin/orderSource";
+import { admitSharedStoreTenant } from "@/lib/checkout/commerce/sharedStoreAdmission";
 import { assessCheckoutOrder } from "@/lib/orders/admin/services/orders";
-import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
 
 export const prerender = false;
 
@@ -43,29 +36,21 @@ export async function GET(context: APIContext): Promise<Response> {
   const orderId = context.params.id;
   if (!orderId) return jsonError("order_not_found", 404);
 
-  const bearer = await readEnv("FOXY_ORDER_API_KEY");
-  if (!bearer) return jsonError("not_provisioned", 503);
-
-  const stage = commerceStageForEnv(customizationEnv);
-  if (!stage) return jsonError("stage-unknown", 409);
-  const tenantId = tenant.appDomain.trim();
-  if (!tenantId) return jsonError("not_provisioned", 503);
-
-  const client = createCheckoutOrderClient({
-    baseUrl: orderApiBaseUrl(customizationEnv),
-    appDomain: tenantId,
-    bearer,
-  });
+  const source = await resolveOrderSource(
+    { tenantId: tenant.appDomain, customizationEnv },
+    workerOrderSourceDeps(admitSharedStoreTenant),
+  );
+  if (source.kind === "not-connected") return jsonError(source.gap, source.gap === "stage-unknown" ? 409 : 503);
 
   try {
-    const scope = { tenantId, stage };
+    const scope = source.scope;
     const actor = commerceActorForAdmin({
-      tenantId,
-      stage,
+      tenantId: scope.tenantId,
+      stage: scope.stage,
       owner: access.entry.isOwnerViewer,
       admitted: access.entry.admitted,
     });
-    const order = projectCheckoutOrder(await client.getOrder(orderId), actor, scope);
+    const order = projectCheckoutOrder(await source.client.getOrder(orderId), actor, scope);
     const readiness = assessCheckoutOrder(order, scope);
     return new Response(JSON.stringify({ order, readiness }), { headers: JSON_HEADERS });
   } catch (err) {

package/apps/storefront/src/pages/api/admin/orders.ts

@@ -1,23 +1,19 @@
 /**
  * `GET /api/admin/orders` — internal admin route backing the Orders tab.
  *
- * Server-side proxy to the checkout order READ API for the resolved tenant +
- * environment. The per-tenant bearer key stays on the Worker (never in the
- * response); the browser only ever sees order DTO JSON. Read-only (scope-locks).
+ * Reads the tenant's orders from the source `resolveOrderSource` picks (the platform ledger for
+ * a shared-checkout tenant, the store's partner API otherwise). Any partner bearer key stays on
+ * the Worker (never in the response); the browser only ever sees order DTO JSON. Read-only.
  * The admin UI consumes this and maps the DTO → OrdersViewModel.
  *
  * Access control matches the rest of the admin surface (owned by the admin
  * host/approver layer) — same posture as `api/evidence.json.ts`; no new gate here.
  */
 import type { APIContext } from "astro";
-import { readEnv } from "@/lib/publication/shared/env";
 import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
-import {
-  createCheckoutOrderClient,
-  orderApiBaseUrl,
-  OrderApiError,
-} from "@/lib/orders/admin/orderClient";
-import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
+import { OrderApiError } from "@/lib/orders/admin/orderClient";
+import { resolveOrderSource, workerOrderSourceDeps } from "@/lib/orders/admin/orderSource";
+import { admitSharedStoreTenant } from "@/lib/checkout/commerce/sharedStoreAdmission";
 import { assessCheckoutOrder, parseOrderFilters } from "@/lib/orders/admin/services/orders";
 
 export const prerender = false;
@@ -43,34 +39,21 @@ export async function GET(context: APIContext): Promise<Response> {
   const access = await requireAdminApiEntry(context);
   if (!access.ok) return jsonError(access.reason, access.status);
 
-  const bearer = await readEnv("FOXY_ORDER_API_KEY");
-  if (!bearer) {
-    // Worker secret not provisioned for this env — a config error, not the
-    // caller's fault. Never echo the (missing) key.
-    return jsonError("not_provisioned", 503);
-  }
-
-  const stage = commerceStageForEnv(customizationEnv);
-  if (!stage) return jsonError("stage-unknown", 409);
-  const tenantId = tenant.appDomain.trim();
-  if (!tenantId) return jsonError("not_provisioned", 503);
-
-  const url = new URL(context.request.url);
   // Tenant comes from the host, never from a query parameter.
-  const filters = parseOrderFilters(url.searchParams);
+  const source = await resolveOrderSource(
+    { tenantId: tenant.appDomain, customizationEnv },
+    workerOrderSourceDeps(admitSharedStoreTenant),
+  );
+  // An unconnected source is a config gap, not the caller's fault. Never echo a key.
+  if (source.kind === "not-connected") return jsonError(source.gap, source.gap === "stage-unknown" ? 409 : 503);
 
-  const client = createCheckoutOrderClient({
-    baseUrl: orderApiBaseUrl(customizationEnv),
-    appDomain: tenantId,
-    bearer,
-  });
+  const filters = parseOrderFilters(new URL(context.request.url).searchParams);
 
   try {
-    const data = await client.listOrders(filters);
-    const scope = { tenantId, stage };
+    const data = await source.client.listOrders(filters);
     const orders = data.orders.map((order) => ({
       ...order,
-      readiness: assessCheckoutOrder(order, scope),
+      readiness: assessCheckoutOrder(order, source.scope),
     }));
     return new Response(JSON.stringify({ ...data, orders }), { headers: JSON_HEADERS });
   } catch (err) {