@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,300 @@
+/**
+ * REAL orders view model (card 8585 / U3) — replaces the deterministic mock as
+ * the Orders tab's data source. Fetches the tenant's orders from tot-foxycart via
+ * U2's order client and maps the frozen DTO (`@tot/public-runtime` foxy-orders)
+ * into the EXISTING `OrdersViewModel` shape, so `OrdersWorkspace.astro` renders
+ * unchanged. Read-only (scope-locks) — no write paths.
+ *
+ * The mapping is a pure function (`mapOrdersToViewModel`) for testability; the
+ * orchestration (`getOrdersViewModel`) lists orders, eagerly fetches each order's
+ * detail (OrdersWorkspace renders `detailsById[row.id]` for every row), and maps.
+ * On ANY upstream failure it returns a valid EMPTY view model so the tab renders
+ * (rich loading/empty/error UX is U5). NOTE: the live "real qa data" path is
+ * gated on ToT-core exposing `GET /api/exciseTax/orders` (see U1/U2 notes); until
+ * then this yields the empty model on qa.
+ *
+ * Identity/age fields (riskLevel, readiness "identity_and_age", evidence) are
+ * derived provisionally from commerce facts here; U4 (the tot20 verification
+ * join) fills them authoritatively via the DTO's null `verification` /
+ * `verificationDetail` slots — no shape change needed.
+ */
+import type {
+  FoxyOrderDetail,
+  FoxyOrderListFilters,
+  FoxyOrderPage,
+  FoxyOrderSummary,
+  FoxyOrderVerification,
+} from "@tot/public-runtime";
+import type {
+  OrderDetail,
+  OrderEvidenceEvent,
+  OrderQueueSummary,
+  OrderReadinessCheck,
+  OrderRow,
+  OrderShipState,
+  OrdersViewModel,
+} from "../viewmodels/orders";
+import type { FoxyOrderClient } from "../orderClient";
+
+/** Next-step label, mirroring the mock's queue semantics. */
+function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): string {
+  if (fulfillment === "hold_review_required") {
+    return blocker === "Payment capture" ? "Capture payment" : "Review risk";
+  }
+  if (fulfillment === "completed") return "View record";
+  return "Create label";
+}
+
+/** Provisional risk until U4 fills `verification`. Prefer a real riskLevel when present. */
+function deriveRisk(
+  verification: FoxyOrderVerification | null,
+  blocker: string | null,
+): OrderRow["riskLevel"] {
+  const r = verification?.riskLevel;
+  if (r === "low" || r === "medium" || r === "high") return r;
+  if (blocker === "Age verification hold") return "high";
+  return blocker ? "medium" : "low";
+}
+
+/** Map a DTO summary to the view model's OrderRow. */
+export function mapSummaryToRow(s: FoxyOrderSummary): OrderRow {
+  return {
+    id: s.id,
+    placedAt: s.placedAt,
+    customerId: s.customer.id ?? "",
+    customerName: s.customer.name,
+    customerNote: "", // not carried by the commerce DTO
+    itemsSummary: s.itemsSummary,
+    productId: "", // not carried by the commerce order summary DTO (mock links by product index)
+    total: s.total,
+    payment: s.payment,
+    shipState: s.fulfillment,
+    blocker: s.blocker,
+    nextStep: deriveNextStep(s.fulfillment, s.blocker),
+    riskLevel: deriveRisk(s.verification, s.blocker),
+  };
+}
+
+/** Commerce-derived readiness checks (U4 enriches the identity dimension). */
+function deriveReadinessChecks(d: FoxyOrderDetail): OrderReadinessCheck[] {
+  const ageHold = d.blocker === "Age verification hold";
+  return [
+    {
+      key: "payment_capture",
+      label: "Payment capture",
+      value: d.payment === "captured" ? "Captured" : "Authorized",
+      detail: "Capture the authorization before creating the shipping label.",
+      tone: d.payment === "captured" ? "green" : "amber",
+      action: "Capture payment",
+      blocking: d.payment !== "captured",
+    },
+    {
+      key: "tax_and_fees",
+      label: "Tax and fees",
+      value: "Collected",
+      detail: "Required amounts are included in the order total.",
+      tone: "blue",
+      action: "View total",
+      blocking: false,
+    },
+    {
+      key: "identity_and_age",
+      label: "Identity and age",
+      value: ageHold ? "Needs review" : "Passed",
+      detail: "Checkout assurance completed before order placement.",
+      tone: ageHold ? "amber" : "green",
+      action: "View evidence",
+      blocking: ageHold,
+    },
+    {
+      key: "address",
+      label: "Address",
+      value: d.shippingAddress ? "Serviceable" : "Unknown",
+      detail: "Destination is deliverable after any hold is resolved.",
+      tone: d.shippingAddress ? "green" : "amber",
+      action: "View address",
+      blocking: false,
+    },
+  ];
+}
+
+/** Base commerce evidence events (U4 replaces with the real verification timeline). */
+function deriveEvidenceTimeline(d: FoxyOrderDetail): OrderEvidenceEvent[] {
+  const events: OrderEvidenceEvent[] = [
+    { title: "Order imported", detail: "Storefront order became available in the admin queue.", at: d.placedAt },
+    { title: "Payment authorized", detail: "The customer completed checkout and payment was authorized.", at: d.placedAt },
+  ];
+  if (d.blocker) {
+    events.push({ title: "Hold added", detail: `${d.blocker} must be resolved before shipment.`, at: d.placedAt });
+  }
+  return events;
+}
+
+/** Map a DTO detail (its summary already mapped to `row`) to the view model's OrderDetail. */
+export function mapDetailToDetail(d: FoxyOrderDetail, row: OrderRow): OrderDetail {
+  return {
+    ...row,
+    lineItems: d.lineItems.map((li) => ({
+      sku: li.sku,
+      name: li.name,
+      quantity: li.quantity,
+      unitPrice: li.unitPrice,
+    })),
+    shipping: d.totals.shipping,
+    estimatedTax: d.totals.estimatedTax,
+    taxesAndFees: d.totals.taxesAndFees,
+    readinessChecks: deriveReadinessChecks(d),
+    evidenceTimeline: deriveEvidenceTimeline(d),
+  };
+}
+
+function buildQueues(rows: OrderRow[]): OrderQueueSummary[] {
+  const needsAttention = rows.filter((r) => r.shipState === "hold_review_required").length;
+  const readyToShip = rows.filter((r) => r.shipState === "ready_to_ship").length;
+  const completed = rows.filter((r) => r.shipState === "completed").length;
+  return [
+    { key: "needs_attention", label: "Needs attention", count: needsAttention, detail: "Hold before shipment" },
+    { key: "ready_to_ship", label: "Ready to ship", count: readyToShip, detail: "Labels available" },
+    { key: "unfulfilled", label: "Unfulfilled", count: readyToShip + needsAttention, detail: "Oldest open order first" },
+    { key: "all", label: "All orders", count: rows.length, detail: "Newest first" },
+    { key: "completed", label: "Completed", count: completed, detail: "Delivered" },
+  ];
+}
+
+/**
+ * PURE map of DTO orders → the OrdersViewModel. `details` supplies the per-order
+ * detail (line items / totals); a row with no matching detail falls back to a
+ * minimal detail built from the row so `detailsById[row.id]` is always present.
+ */
+export function mapOrdersToViewModel(
+  targetTenant: string,
+  summaries: FoxyOrderSummary[],
+  details: Record<string, FoxyOrderDetail>,
+): OrdersViewModel {
+  const rows = summaries.map(mapSummaryToRow);
+
+  const detailsById: Record<string, OrderDetail> = {};
+  for (const row of rows) {
+    const d = details[row.id];
+    detailsById[row.id] = d
+      ? mapDetailToDetail(d, row)
+      : {
+          ...row,
+          lineItems: [],
+          shipping: 0,
+          estimatedTax: 0,
+          taxesAndFees: 0,
+          readinessChecks: [],
+          evidenceTimeline: [],
+        };
+  }
+
+  const paidOrders = rows.filter((r) => r.payment === "captured");
+  const grossSales = paidOrders.reduce((sum, r) => sum + r.total, 0);
+
+  return {
+    targetTenant,
+    queues: buildQueues(rows),
+    rows,
+    detailsById,
+    today: {
+      grossSales,
+      paidOrders: paidOrders.length,
+      averageOrder: paidOrders.length ? Math.round((grossSales / paidOrders.length) * 100) / 100 : 0,
+      refunds: 0,
+      oldestOpenAt: rows.length ? rows[rows.length - 1]!.placedAt : null,
+    },
+  };
+}
+
+/** A valid, empty view model — rendered when nothing is available or a fetch fails. */
+export function emptyOrdersViewModel(targetTenant: string): OrdersViewModel {
+  return mapOrdersToViewModel(targetTenant, [], {});
+}
+
+export interface GetOrdersViewModelOptions {
+  targetTenant: string;
+  client: FoxyOrderClient;
+  /** List filters (queue/status/pagination); passed through to the order client. */
+  filters?: Parameters<FoxyOrderClient["listOrders"]>[0];
+}
+
+/**
+ * Fetch + map the real orders view model. Lists orders, eagerly fetches each
+ * order's detail (bounded by the list page size), and maps. Any upstream error
+ * (incl. the not-yet-available ToT-core endpoint) degrades to the empty model so
+ * the Orders tab always renders.
+ */
+/**
+ * Load outcome for the Orders tab (U5) — lets the UI pick the right state:
+ * `loaded` (rows), `empty` (fetch OK, 0 orders), `error` (upstream failed), and
+ * `not_configured` (produced by the caller when no bearer/client is available —
+ * the service itself never returns it). `page` carries the pagination cursor.
+ */
+export type OrdersLoadStatus = "loaded" | "empty" | "error" | "not_configured";
+
+export interface OrdersLoadResult {
+  status: OrdersLoadStatus;
+  vm: OrdersViewModel;
+  page: FoxyOrderPage | null;
+}
+
+/**
+ * Parse server-backed list filters from a request's query string (U5). `queue`
+ * of `"all"` (or absent) means no server filter. Non-numeric `limit` is ignored.
+ * `payment`/search are NOT here — they are client-side refinements (the DTO list
+ * API has no payment filter, per contract §9).
+ */
+export function parseOrderFilters(params: URLSearchParams): FoxyOrderListFilters {
+  const f: FoxyOrderListFilters = {};
+  const queue = params.get("queue");
+  if (queue && queue !== "all") f.queue = queue;
+  const status = params.get("status");
+  if (status) f.status = status;
+  const from = params.get("from");
+  if (from) f.from = from;
+  const to = params.get("to");
+  if (to) f.to = to;
+  const limit = params.get("limit");
+  if (limit && Number.isFinite(Number(limit))) f.limit = Number(limit);
+  const cursor = params.get("cursor");
+  if (cursor) f.cursor = cursor;
+  return f;
+}
+
+/**
+ * Fetch + map the orders view model AND report the load outcome (U5). Lists,
+ * eagerly fetches per-order detail, maps. Distinguishes empty from error so the
+ * tab can degrade gracefully. Never throws.
+ */
+export async function getOrdersViewModelResult(
+  opts: GetOrdersViewModelOptions,
+): Promise<OrdersLoadResult> {
+  try {
+    const { orders, page } = await opts.client.listOrders(opts.filters);
+    const details: Record<string, FoxyOrderDetail> = {};
+    await Promise.all(
+      orders.map(async (o) => {
+        try {
+          details[o.id] = await opts.client.getOrder(o.id);
+        } catch {
+          /* detail unavailable — row still renders from its summary */
+        }
+      }),
+    );
+    return {
+      status: orders.length ? "loaded" : "empty",
+      vm: mapOrdersToViewModel(opts.targetTenant, orders, details),
+      page,
+    };
+  } catch {
+    return { status: "error", vm: emptyOrdersViewModel(opts.targetTenant), page: null };
+  }
+}
+
+/** Back-compat convenience: just the view model (see getOrdersViewModelResult). */
+export async function getOrdersViewModel(
+  opts: GetOrdersViewModelOptions,
+): Promise<OrdersViewModel> {
+  return (await getOrdersViewModelResult(opts)).vm;
+}

package/apps/storefront/src/lib/admin/viewmodels/aiWorkflows.ts

@@ -0,0 +1,67 @@
+/**
+ * AI Workflows view model (baseline §AI Workflows) — the 8 named recurring
+ * jobs as a control-plane record. No execution: this unit only defines the
+ * read-oriented record shape (ai-workflows-scaffold/operational build the tab
+ * + execution on top of it). `ApprovalMode`/`AuditEvent`/`AiRecommendation`
+ * now come from the ai-evidence-substrate (`lib/admin/ai`), which formalizes
+ * the approval/evidence models this view model originally stubbed.
+ */
+
+import type { ApprovalMode } from "../ai/approvalMode";
+import type { AiRecommendation } from "../ai/recommendation";
+import type { AuditEvent } from "../ai/audit";
+
+export type { ApprovalMode };
+
+export type WorkflowStatus = "scheduled" | "running" | "needs_review" | "paused" | "planned";
+
+export const AI_WORKFLOW_NAMES = [
+  "Performance Regression Guard",
+  "Stockout Forecaster",
+  "Price Sensitivity Planner",
+  "Chargeback Defense Watcher",
+  "AI Channel Readiness Audit",
+  "Fulfillment Exception Analyst",
+  "Compliance Drift Monitor",
+  "Growth Opportunity Digest",
+] as const;
+
+export type AiWorkflowName = (typeof AI_WORKFLOW_NAMES)[number];
+
+/**
+ * The 3 workflows that run end-to-end against mock source data. They are
+ * recommendation flows a human must act on — never an auto-action — so their
+ * `approvalMode` is always `draft_only` or `approval_required`, never
+ * `guarded_automation` (see `ai/approvalMode.ts` + `ai/operationalRuns.ts`).
+ * Defined here (the leaf view-model module) so both the mock service and the
+ * operational runner can import it without a dependency cycle.
+ */
+export const OPERATIONAL_WORKFLOW_KEYS = [
+  "stockout-forecaster",
+  "chargeback-defense-watcher",
+  "ai-channel-readiness-audit",
+] as const;
+
+export type OperationalWorkflowKey = (typeof OPERATIONAL_WORKFLOW_KEYS)[number];
+
+export interface WorkflowRecord {
+  key: string;
+  name: AiWorkflowName;
+  cadence: string;
+  triggerType: string;
+  owner: string;
+  status: WorkflowStatus;
+  approvalMode: ApprovalMode;
+  lastRunAt: string | null;
+  nextRunAt: string | null;
+  sourceData: string[];
+  evidenceLinks: string[];
+  /** Recommendation-shaped: carries its own evidence/confidence/owner/approvalMode/auditTrail (baseline: "Evidence, confidence, owner, approval mode, and audit history attached to recommendations"). */
+  suggestedAction: AiRecommendation | null;
+  auditTrail: AuditEvent[];
+}
+
+export interface AiWorkflowsViewModel {
+  targetTenant: string;
+  workflows: WorkflowRecord[];
+}

package/apps/storefront/src/lib/admin/viewmodels/customers.ts

@@ -0,0 +1,56 @@
+/**
+ * Customers view model (baseline §Customers) — directory + detail, and the
+ * `Valuable But Blocked` first-class reach-out/unblock queue.
+ */
+
+export type VerificationState = "verified" | "pending" | "blocked" | "not_required";
+
+export type CustomerSegment = "new" | "returning" | "vip";
+
+export interface CustomerRow {
+  id: string;
+  name: string;
+  email: string;
+  orderCount: number;
+  lifetimeValue: number;
+  lastOrderAt: string | null;
+  segment: CustomerSegment;
+  supportFlags: string[];
+  verificationState: VerificationState;
+}
+
+export type BlockedReason = "verification" | "destination" | "address" | "support";
+
+export interface CustomerBlockedQueueRow {
+  customerId: string;
+  name: string;
+  recoverableValue: number;
+  blocker: BlockedReason;
+  blockerDetail: string;
+  action: string;
+}
+
+export interface CustomerOrderRef {
+  orderId: string;
+  placedAt: string;
+  total: number;
+}
+
+export interface CustomerActivityEvent {
+  title: string;
+  detail: string;
+  at: string;
+}
+
+export interface CustomerDetail extends CustomerRow {
+  orders: CustomerOrderRef[];
+  activity: CustomerActivityEvent[];
+  notes: string[];
+}
+
+export interface CustomersViewModel {
+  targetTenant: string;
+  directory: CustomerRow[];
+  detailsById: Record<string, CustomerDetail>;
+  valuableButBlocked: CustomerBlockedQueueRow[];
+}

package/apps/storefront/src/lib/admin/viewmodels/fulfillment.ts

@@ -0,0 +1,49 @@
+/**
+ * Fulfillment view model (baseline §Fulfillment) — operational shipment
+ * queues, label locks, SLA age, and carrier/destination readiness. AI here is
+ * intentionally narrow (`Fulfillment Assist` drafts only — see aiWorkflows.ts
+ * / ai-evidence-substrate for the approval-gated substrate this later wires
+ * into).
+ */
+
+export type FulfillmentQueueKey =
+  | "ready_to_ship"
+  | "holds"
+  | "picked"
+  | "packed"
+  | "label_needed"
+  | "shipped"
+  | "exceptions";
+
+export interface FulfillmentQueueSummary {
+  key: FulfillmentQueueKey;
+  label: string;
+  count: number;
+}
+
+export interface ShipmentRow {
+  orderId: string;
+  queue: FulfillmentQueueKey;
+  carrier: string;
+  destination: string;
+  slaAgeHours: number;
+  labelLocked: boolean;
+  labelLockReason: string | null;
+  carrierReady: boolean;
+  destinationReady: boolean;
+}
+
+export type FulfillmentAssistKind = "blocker_explanation" | "customer_update_draft" | "evidence_prep";
+
+export interface FulfillmentAssistDraft {
+  orderId: string;
+  kind: FulfillmentAssistKind;
+  summary: string;
+}
+
+export interface FulfillmentViewModel {
+  targetTenant: string;
+  queues: FulfillmentQueueSummary[];
+  shipments: ShipmentRow[];
+  assistDrafts: FulfillmentAssistDraft[];
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Orders view model (baseline §Orders) — exception-first queue, ready-to-ship
+ * queue, dense table, selected-order detail, and the evidence timeline behind
+ * `Order Assist`. Every field here is read-oriented; write paths do not exist
+ * yet (data-view-contracts is deliberately read-only, per the baseline's
+ * suggested buildout sequence step 3).
+ */
+
+export type OrderPaymentState = "authorized" | "captured" | "refunded";
+
+export type OrderShipState = "ready_to_ship" | "hold_review_required" | "unfulfilled" | "completed";
+
+/** The exact merchant-facing language the shell contract requires. */
+export const ORDER_SHIP_STATE_LABEL: Record<OrderShipState, string> = {
+  ready_to_ship: "Ready to Ship",
+  hold_review_required: "Hold: Review Required",
+  unfulfilled: "Unfulfilled",
+  completed: "Completed",
+};
+
+export interface OrderReadinessCheck {
+  key: string;
+  label: string;
+  value: string;
+  detail: string;
+  tone: "green" | "amber" | "blue" | "red";
+  action: string;
+  blocking: boolean;
+}
+
+export interface OrderEvidenceEvent {
+  title: string;
+  detail: string;
+  at: string;
+}
+
+export interface OrderLineItem {
+  sku: string;
+  name: string;
+  quantity: number;
+  unitPrice: number;
+}
+
+export interface OrderRow {
+  id: string;
+  placedAt: string;
+  customerId: string;
+  customerName: string;
+  customerNote: string;
+  itemsSummary: string;
+  productId: string;
+  total: number;
+  payment: OrderPaymentState;
+  shipState: OrderShipState;
+  blocker: string | null;
+  nextStep: string;
+  riskLevel: "low" | "medium" | "high";
+}
+
+export interface OrderDetail extends OrderRow {
+  readinessChecks: OrderReadinessCheck[];
+  evidenceTimeline: OrderEvidenceEvent[];
+  lineItems: OrderLineItem[];
+  shipping: number;
+  estimatedTax: number;
+  taxesAndFees: number;
+}
+
+export type OrderQueueKey = "needs_attention" | "ready_to_ship" | "unfulfilled" | "all" | "completed";
+
+export interface OrderQueueSummary {
+  key: OrderQueueKey;
+  label: string;
+  count: number;
+  detail: string;
+}
+
+export interface OrdersTodaySummary {
+  grossSales: number;
+  paidOrders: number;
+  averageOrder: number;
+  refunds: number;
+  oldestOpenAt: string | null;
+}
+
+export interface OrdersViewModel {
+  targetTenant: string;
+  queues: OrderQueueSummary[];
+  rows: OrderRow[];
+  detailsById: Record<string, OrderDetail>;
+  today: OrdersTodaySummary;
+}

package/apps/storefront/src/lib/admin/viewmodels/products.ts

@@ -0,0 +1,74 @@
+/**
+ * Products view model (baseline §Products) — catalog readiness and
+ * sellability, including the explicit excise-metadata readiness checks called
+ * out in the baseline doc (tax class, exempt flag, nicotine flag, wholesale
+ * basis, retail price, pack quantity, volume/weight, category).
+ */
+
+export type ExciseCheckKey =
+  | "tax_class"
+  | "exempt_flag"
+  | "nicotine_flag"
+  | "wholesale_basis"
+  | "retail_price"
+  | "pack_quantity"
+  | "volume_or_weight"
+  | "category";
+
+export interface ExciseReadinessCheck {
+  key: ExciseCheckKey;
+  label: string;
+  present: boolean;
+  value: string | null;
+}
+
+export interface ProductVariant {
+  sku: string;
+  name: string;
+  inventory: number;
+  price: number;
+}
+
+export interface ProductMediaAsset {
+  url: string;
+  alt: string;
+  kind: "image" | "video";
+}
+
+export interface ProductActivityEvent {
+  title: string;
+  detail: string;
+  at: string;
+}
+
+export interface ProductRow {
+  id: string;
+  name: string;
+  productType: string;
+  category: string;
+  status: "active" | "draft" | "archived";
+  readinessScore: number;
+  sellable: boolean;
+  aiChannelReady: boolean;
+  missingExciseCount: number;
+}
+
+export interface ProductDetail extends ProductRow {
+  variants: ProductVariant[];
+  media: ProductMediaAsset[];
+  exciseChecks: ExciseReadinessCheck[];
+  activity: ProductActivityEvent[];
+  complianceNotes: string[];
+}
+
+export interface ProductSavedView {
+  key: string;
+  label: string;
+}
+
+export interface ProductsViewModel {
+  targetTenant: string;
+  savedViews: ProductSavedView[];
+  rows: ProductRow[];
+  detailsById: Record<string, ProductDetail>;
+}

package/apps/storefront/src/lib/admin/viewmodels/reporting.ts

@@ -0,0 +1,34 @@
+/**
+ * Reporting view model (baseline §Reporting) — read-only category summaries
+ * that drill back into the owning tab's working rows, plus the `Analysis
+ * Brief`. Reporting depends on the other domains for trustworthy data, so
+ * this stays read-only per the suggested buildout sequence.
+ */
+
+export type ReportingCategory = "sales" | "products" | "customers" | "fulfillment" | "compliance" | "tax" | "risk";
+
+export interface ReportingSummary {
+  category: ReportingCategory;
+  label: string;
+  headline: string;
+  value: string;
+  trend: "up" | "down" | "flat";
+  /** Deep link back to the owning tab's working surface, e.g. "#orders?holdOnly=1". */
+  drilldownHref: string;
+}
+
+export interface AnalysisBriefItem {
+  title: string;
+  detail: string;
+  drilldownHref: string;
+  evidenceRef: string;
+}
+
+export interface ReportingViewModel {
+  targetTenant: string;
+  summaries: ReportingSummary[];
+  analysisBrief: {
+    drivers: AnalysisBriefItem[];
+    watchItems: AnalysisBriefItem[];
+  };
+}