@tokenoftrust/storefront-runner 2.4.56 → 2.4.57

package/apps/storefront/src/pages/api/admin/commerce-readiness.ts

@@ -0,0 +1,145 @@
+/**
+ * GET/POST /api/admin/commerce-readiness
+ *
+ * Phase 1: the client fulfills in their own carrier account. This route reports
+ * whether order and payment reconcile has been exercised. It does not read an
+ * order row, write a payment, or call a carrier. Postage is not a result.
+ *
+ * The exercised comparison is scripts/commerce/scrappy-reconcile.mjs. This
+ * surface has no ledger, so configured, absent, and unreadable stay unhealthy.
+ */
+import type { APIContext } from "astro";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
+import { workerCommit } from "@/lib/activity/workerCommit";
+import { readEnv } from "@/lib/env";
+import {
+  COMMERCE_SCHEDULER,
+  actorMayCommand,
+  decideCommerceCommand,
+  type CommerceEvidence,
+  type CommerceStage,
+} from "@tot/public-runtime";
+
+export const prerender = false;
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+const READINESS = ["configured-only", "exercised", "stale", "failed", "absent", "unreadable"] as const;
+type Readiness = (typeof READINESS)[number];
+
+export interface CommerceReadinessReport {
+  schema: "scrappy-reconcile-v1";
+  readiness: Readiness;
+  healthy: boolean;
+  sourceSha: string | null;
+  deployedSha: string | null;
+  watermark: { asOf: string; source: { cursor: string | null }; tot: { cursor: string | null } } | null;
+  orderCount: number | null;
+  capturedMinor: number | null;
+  refundedMinor: number | null;
+  labelAndPostageCompared: false;
+  discrepancies: { code: string; id: string; owner: string }[] | null;
+  owner: "owner";
+}
+
+const EVIDENCE: CommerceEvidence = { verification: "UNKNOWN", tax: "UNKNOWN", risk: "UNKNOWN", stock: "UNKNOWN" };
+const REPLAY_KEYS = new Set(["kind", "orderId", "sourceEventId", "stage"]);
+const OPAQUE = /^[A-Za-z0-9:_-]{1,80}$/;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+
+export function projectAdminReadiness(input: {
+  scheduler: string | undefined;
+  deployedSha: string;
+}): CommerceReadinessReport {
+  const configured = input.scheduler === COMMERCE_SCHEDULER;
+  const deployedSha = input.deployedSha.length > 0 ? input.deployedSha : null;
+  const readiness: Readiness = deployedSha === null ? "unreadable" : configured ? "configured-only" : "absent";
+  return {
+    schema: "scrappy-reconcile-v1",
+    readiness,
+    healthy: false,
+    sourceSha: null,
+    deployedSha,
+    watermark: null,
+    orderCount: null,
+    capturedMinor: null,
+    refundedMinor: null,
+    labelAndPostageCompared: false,
+    discrepancies: readiness === "unreadable" ? null : [],
+    owner: "owner",
+  };
+}
+
+function replayStage(value: unknown): CommerceStage | null {
+  return value === "preview" || value === "publication" ? value : null;
+}
+
+export function admitAdminReplay(input: {
+  tenantId: string;
+  stage: CommerceStage;
+  kind: "order" | "refund";
+}): { admitted: boolean; reason: "admitted" | "denied" | "refused" } {
+  const actor = { role: "owner" as const, tenantId: input.tenantId, stage: input.stage };
+  const resource = { tenantId: input.tenantId, stage: input.stage };
+  if (!actorMayCommand(actor, resource)) return { admitted: false, reason: "denied" };
+  const decision = decideCommerceCommand({
+    command: "reconcile",
+    payment: input.kind === "refund" ? "refund_unknown" : "captured",
+    stock: "UNKNOWN",
+    fulfillment: "UNKNOWN",
+    label: "none",
+    evidence: EVIDENCE,
+    providerOutcome: null,
+  });
+  if (!decision.admit || decision.restock !== false || decision.blindRepurchase !== false) {
+    return { admitted: false, reason: "refused" };
+  }
+  return { admitted: true, reason: "admitted" };
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const access = await requireAdminApiEntry(context, { requireOwner: true });
+  if (!access.ok) return json({ ok: false, reason: access.reason }, access.status);
+  const scheduler = await readEnv("SCRAPPY_COMMERCE_SCHEDULER");
+  return json({ ok: true, report: projectAdminReadiness({ scheduler, deployedSha: workerCommit() }) });
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const access = await requireAdminApiEntry(context, { requireOwner: true });
+  if (!access.ok) return json({ ok: false, reason: access.reason }, access.status);
+  const text = await context.request.text();
+  if (text.length > 2000) return json({ ok: false, reason: "refused" }, 400);
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return json({ ok: false, reason: "refused" }, 400);
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return json({ ok: false, reason: "refused" }, 400);
+  const record = body as Record<string, unknown>;
+  if (Object.keys(record).some((key) => !REPLAY_KEYS.has(key))) return json({ ok: false, reason: "refused" }, 400);
+  const stage = replayStage(record.stage);
+  const kind = record.kind === "order" || record.kind === "refund" ? record.kind : null;
+  if (!stage || !kind || typeof record.orderId !== "string" || typeof record.sourceEventId !== "string") {
+    return json({ ok: false, reason: "refused" }, 400);
+  }
+  if (!OPAQUE.test(record.orderId) || !OPAQUE.test(record.sourceEventId)) return json({ ok: false, reason: "refused" }, 400);
+  const decision = admitAdminReplay({ tenantId: context.locals.tenant.tenant_id, stage, kind });
+  if (!decision.admitted) return json({ ok: false, reason: decision.reason }, 403);
+  const scheduler = await readEnv("SCRAPPY_COMMERCE_SCHEDULER");
+  return json({
+    ok: true,
+    admitted: true,
+    durableWrite: false,
+    command: "reconcile",
+    reason: decision.reason,
+    report: projectAdminReadiness({ scheduler, deployedSha: workerCommit() }),
+  });
+}

package/package.json

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