punchout-simulator 0.5.1 → 0.6.0

package/README.md

@@ -18,6 +18,11 @@ It is role-neutral and runs in two modes (mirror images of each other):
 
 Protocol scope: **cXML only**.
 
+> **New to PunchOut, or want the full picture?** See the in-depth reports in
+> [`docs/`](docs/): the [PunchOut business primer](docs/punchout-business-primer_en.html),
+> the [Architecture reference](docs/architecture_en.html), and the
+> [Operations & usage guide](docs/operations-guide_en.html).
+
 ---
 
 ## Quick start
@@ -30,15 +35,17 @@ That's it — no install, no build. It boots a local server, opens your browser,
 and seeds a **built-in demo**: a virtual buyer wired to a built-in mock supplier,
 so you can run the entire roundtrip immediately:
 
-1. Open the **Demo Buyer → Demo Supplier** connection.
+1. On the **Sessions** tab, click **+ New session**, pick the **Demo Buyer → Demo
+   Supplier** connection and the **create** operation.
 2. **Send SetupRequest** → the mock supplier replies with a StartPage.
 3. **Open the catalog**, set quantities, **return the cart** — the punchback
    lands back in the app live.
 4. **Build the OrderRequest**, edit the cXML if you want (tweak `<Comments>`,
    addresses, attachment refs), optionally attach files at the **order or item
    level**, optionally flip on the **dangling-`cid` test**, then **send it** and
-   inspect the supplier's response.
-5. If validation fails, **edit and re-send** — the flow session and cart persist.
+   inspect the supplier's response. (A **Validate** button lints the cXML before
+   you send.)
+5. If validation fails, **edit and re-send** — the session keeps its log and cart.
 
 Every document — inbound and outbound — is validated and logged.
 
@@ -142,6 +149,27 @@ receiver detects the missing attachment. `<Comments>` (and therefore
 
 ---
 
+## Sessions
+
+A **session** is one PunchOut conversation, keyed by its `BuyerCookie`:
+SetupRequest → catalog → cart → OrderRequest → OrderResponse. The **Sessions** tab
+(under **Run**, separate from the **Configure** sections) is the workspace:
+
+- A live **session list** — Mode-A sessions you start *and* Mode-B sessions an
+  external buyer initiates against the tool's endpoints (those show as **inbound**).
+- A per-session **message log** (each session keeps its own; no global firehose).
+- **+ New session** picks a connection and the SetupRequest **operation**:
+  - **create** — a fresh, empty cart (the default).
+  - **edit** — reopen a previous session's returned cart for modification; its
+    items are sent as `ItemOut` inside the SetupRequest (`operation="edit"`).
+  - **inspect** — view a previously ordered item read-only (`operation="inspect"`),
+    carrying that item (or the whole source cart) as `ItemOut`.
+
+Connections/Buyers/Suppliers/Products/Profiles remain under **Configure** — you set
+them up there, then run them from **Sessions**.
+
+---
+
 ## Network reachability
 
 - **Mode A rarely needs a tunnel.** The punchback is a browser auto-submit from
@@ -176,6 +204,15 @@ src/
    └─ cxml/  build · parse · validate · multipart · types
 ```
 
+For a deeper treatment — component breakdown, the full data model, and Mode A /
+Mode B sequence diagrams — see the
+[**Architecture reference**](docs/architecture_en.html) in [`docs/`](docs/).
+The same folder holds a [**PunchOut business primer**](docs/punchout-business-primer_en.html)
+(the business process and where this tool fits) and an
+[**Operations & usage guide**](docs/operations-guide_en.html) (sessions,
+operations, profiles, product lists, validation). The reports are self-contained
+HTML; their canonical Markdown sources sit alongside them.
+
 ### Data model
 
 The config is normalized into five entities:

package/dist/server/cli.js

@@ -869,7 +869,8 @@ import { Hono as Hono5 } from "hono";
 import { nanoid as nanoid5 } from "nanoid";
 
 // src/server/store/log.ts
-import { appendFileSync, existsSync, readdirSync, readFileSync } from "fs";
+import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync } from "fs";
+import { resolve as resolve2, sep } from "path";
 import { nanoid as nanoid2 } from "nanoid";
 
 // src/server/bus.ts
@@ -917,6 +918,13 @@ function readSession(sessionId) {
     }
   }).filter((r) => r !== null);
 }
+function deleteSession(sessionId) {
+  const file = resolve2(sessionFile(sessionId));
+  if (!file.startsWith(resolve2(sessionsDir()) + sep)) return false;
+  if (!existsSync(file)) return false;
+  rmSync(file);
+  return true;
+}
 function listSessions() {
   ensureDirs();
   const files = readdirSync(sessionsDir()).filter((f) => f.endsWith(".jsonl"));
@@ -925,6 +933,8 @@ function listSessions() {
     const sessionId = file.replace(/\.jsonl$/, "");
     const records = readSession(sessionId);
     if (records.length === 0) continue;
+    const setup = records.find((r) => r.docType === "SetupRequest");
+    const operation = setup ? /<PunchOutSetupRequest[^>]*\boperation="([^"]+)"/.exec(setup.body)?.[1] : void 0;
     summaries.push({
       sessionId: records[0].sessionId ?? sessionId,
       connectionId: records[0].connectionId,
@@ -932,7 +942,8 @@ function listSessions() {
       firstTs: records[0].ts,
       lastTs: records[records.length - 1].ts,
       docTypes: [...new Set(records.map((r) => r.docType))],
-      hasErrors: records.some((r) => r.validation && !r.validation.ok)
+      hasErrors: records.some((r) => r.validation && !r.validation.ok),
+      operation
     });
   }
   return summaries.sort((a, b) => (b.lastTs ?? "").localeCompare(a.lastTs ?? ""));
@@ -944,7 +955,7 @@ function readAllRecent(limit = 200) {
 // src/server/store/attachments.ts
 import { createHash } from "crypto";
 import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 
 // src/server/cxml/multipart.ts
 import { nanoid as nanoid3 } from "nanoid";
@@ -1082,7 +1093,7 @@ function findHeaderBodySplit(buf) {
 function saveAttachment(data, meta) {
   ensureDirs();
   const hash = createHash("sha256").update(data).digest("hex");
-  const path = resolve2(attachmentsDir(), hash);
+  const path = resolve3(attachmentsDir(), hash);
   if (!existsSync2(path)) writeFileSync(path, data, { mode: 384 });
   return {
     contentId: normalizeContentId(meta.contentId),
@@ -1096,7 +1107,7 @@ function saveAttachment(data, meta) {
 function readAttachment(hash) {
   const safe = hash.replace(/[^a-f0-9]/gi, "");
   if (!safe) return void 0;
-  const path = resolve2(attachmentsDir(), safe);
+  const path = resolve3(attachmentsDir(), safe);
   if (!existsSync2(path)) return void 0;
   return readFileSync2(path);
 }
@@ -1116,6 +1127,10 @@ function rememberSessionConnection(sessionId, connectionId) {
 function connectionForSession(sessionId) {
   return connectionBySession.get(sessionId);
 }
+function forgetSession(sessionId) {
+  carts.delete(sessionId);
+  connectionBySession.delete(sessionId);
+}
 
 // src/server/http.ts
 function assertSafeOutboundUrl(url) {
@@ -1229,6 +1244,22 @@ function extrinsicBlock(items, indent) {
   if (!items || items.length === 0) return "";
   return "\n" + items.map((e) => `${indent}<Extrinsic name="${escapeXml(e.name)}">${escapeXml(e.value)}</Extrinsic>`).join("\n");
 }
+function setupItemOut(it, idx) {
+  return `      <ItemOut quantity="${escapeXml(it.quantity)}" lineNumber="${idx}">
+        <ItemID>
+          <SupplierPartID>${escapeXml(it.supplierPartId ?? "")}</SupplierPartID>${it.supplierPartAuxiliaryId ? `
+          <SupplierPartAuxiliaryID>${escapeXml(it.supplierPartAuxiliaryId)}</SupplierPartAuxiliaryID>` : ""}
+        </ItemID>
+        <ItemDetail>
+          <UnitPrice>
+            <Money currency="${escapeXml(it.currency ?? "USD")}">${escapeXml(it.unitPriceAmount ?? 0)}</Money>
+          </UnitPrice>
+          <Description xml:lang="en">${escapeXml(it.description ?? "")}</Description>
+          <UnitOfMeasure>${escapeXml(it.uom ?? "EA")}</UnitOfMeasure>
+${classificationBlock(it, "          ")}
+        </ItemDetail>
+      </ItemOut>`;
+}
 function buildSetupRequest(o) {
   const lang = o.lang ?? "en-US";
   const deployment = o.deploymentMode ? ` deploymentMode="${escapeXml(o.deploymentMode)}"` : "";
@@ -1237,6 +1268,8 @@ function buildSetupRequest(o) {
 ${addressBlock("ShipTo", o.shipTo, mode)}` : "";
   const contact2 = o.contact ? `
 ${contactBlock(o.contact, mode, "      ")}` : "";
+  const items = o.items && o.items.length > 0 ? `
+${o.items.map((it, i) => setupItemOut(it, i + 1)).join("\n")}` : "";
   const inner = `${header({
     from: o.from,
     to: o.to,
@@ -1249,7 +1282,7 @@ ${contactBlock(o.contact, mode, "      ")}` : "";
       <BuyerCookie>${escapeXml(o.buyerCookie)}</BuyerCookie>
       <BrowserFormPost>
         <URL>${escapeXml(o.browserFormPostUrl)}</URL>
-      </BrowserFormPost>${extrinsicBlock(o.extrinsics, "      ")}${shipTo}${contact2}
+      </BrowserFormPost>${extrinsicBlock(o.extrinsics, "      ")}${shipTo}${contact2}${items}
     </PunchOutSetupRequest>
   </Request>`;
   return envelope(o.payloadId, o.timestamp, lang, inner, o.dtdVersion);
@@ -1971,12 +2004,22 @@ function validateDocument(raw, ctx = {}) {
   const docType = ctx.forceDocType ?? getDocType(doc);
   checkGeneral(doc, ctx, issues, docType);
   switch (docType) {
-    case "SetupRequest":
+    case "SetupRequest": {
       checkSharedSecret(doc, ctx, issues);
-      if (!root(doc)?.Request?.PunchOutSetupRequest?.BrowserFormPost?.URL) {
+      const setup = root(doc)?.Request?.PunchOutSetupRequest;
+      if (!setup?.BrowserFormPost?.URL) {
         issues.warn("missing-browserformpost", "PunchOutSetupRequest/BrowserFormPost/URL is missing", "cXML/.../PunchOutSetupRequest/BrowserFormPost/URL");
       }
+      const op = attr(setup, "operation") ?? "create";
+      const hasItems = asArray(setup?.ItemOut).length > 0;
+      if ((op === "edit" || op === "inspect") && !hasItems) {
+        issues.warn("setup-missing-items", `operation="${op}" usually carries the prior item(s) as ItemOut, but none are present`, "cXML/.../PunchOutSetupRequest");
+      }
+      if (op === "create" && hasItems) {
+        issues.warn("setup-unexpected-items", 'operation="create" starts an empty cart, but ItemOut elements are present', "cXML/.../PunchOutSetupRequest");
+      }
       break;
+    }
     case "SetupResponse":
       checkSetupResponse(doc, issues);
       break;
@@ -1998,6 +2041,8 @@ function validateDocument(raw, ctx = {}) {
 }
 
 // src/server/routes/flow.ts
+var coerceOperation = (v) => v === "create" || v === "edit" || v === "inspect" ? v : void 0;
+var setupItems = (body) => Array.isArray(body?.items) && body.items.length > 0 ? body.items : void 0;
 var flowRoute = new Hono5();
 function host() {
   try {
@@ -2049,11 +2094,12 @@ function resolveVirtualBuyer(id) {
   if (r.connection.mode !== "virtual-buyer") return { error: "connection is not in virtual-buyer mode" };
   return { ctx: buyerContext(r) };
 }
-flowRoute.get("/:id/setup/preview", (c) => {
+flowRoute.post("/:id/setup/preview", async (c) => {
   const r = resolveVirtualBuyer(c.req.param("id"));
   if ("error" in r) return c.json({ error: r.error }, 400);
   const { ctx } = r;
-  const buyerCookie = c.req.query("buyerCookie") || `pos-${nanoid5(16)}`;
+  const body = await c.req.json().catch(() => ({}));
+  const buyerCookie = body.buyerCookie || `pos-${nanoid5(16)}`;
   const xml = buildSetupRequest({
     from: ctx.from,
     to: ctx.to,
@@ -2064,11 +2110,12 @@ flowRoute.get("/:id/setup/preview", (c) => {
     payloadId: makePayloadId(host(), (/* @__PURE__ */ new Date()).toISOString()),
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     deploymentMode: ctx.deploymentMode,
-    operation: ctx.eff.setupOperation,
+    operation: coerceOperation(body.operation) ?? ctx.eff.setupOperation,
     dtdVersion: dtdVersionFor(ctx.eff, "SetupRequest"),
     userAgent: ctx.eff.userAgent,
     extrinsics: setupExtrinsics(ctx, buyerCookie),
-    ...setupAddresses(ctx)
+    ...setupAddresses(ctx),
+    items: setupItems(body)
   });
   return c.json({ buyerCookie, xml, browserFormPostUrl: browserFormPostUrl() });
 });
@@ -2088,11 +2135,12 @@ flowRoute.post("/:id/setup", async (c) => {
     payloadId: makePayloadId(host(), (/* @__PURE__ */ new Date()).toISOString()),
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     deploymentMode: ctx.deploymentMode,
-    operation: ctx.eff.setupOperation,
+    operation: coerceOperation(body.operation) ?? ctx.eff.setupOperation,
     dtdVersion: dtdVersionFor(ctx.eff, "SetupRequest"),
     userAgent: ctx.eff.userAgent,
     extrinsics: setupExtrinsics(ctx, buyerCookie),
-    ...setupAddresses(ctx)
+    ...setupAddresses(ctx),
+    items: setupItems(body)
   });
   rememberSessionConnection(buyerCookie, ctx.connectionId);
   const reqValidation = validateDocument(xml, { expected: ctx.expected, forceDocType: "SetupRequest" });
@@ -2132,6 +2180,21 @@ flowRoute.post("/:id/setup", async (c) => {
     response: respLog
   });
 });
+flowRoute.post("/:id/validate", async (c) => {
+  const r = resolveVirtualBuyer(c.req.param("id"));
+  if ("error" in r) return c.json({ error: r.error }, 400);
+  const { ctx } = r;
+  const body = await c.req.json().catch(() => ({}));
+  const xml = String(body.xml ?? "");
+  const docType = body.docType ?? "Unknown";
+  return c.json(
+    validateDocument(xml, {
+      expected: ctx.expected,
+      forceDocType: docType,
+      allowMixedCurrency: ctx.allowMixedCurrency
+    })
+  );
+});
 function buildOrderXml(ctx, body) {
   const items = body.items ?? [];
   const currency = body.currency || items[0]?.currency || "USD";
@@ -2387,8 +2450,37 @@ dataRoute.get(
   "/runtime",
   (c) => c.json({ publicUrl: getPublicUrl(), callbackUrl: `${getPublicUrl()}/punchout/return`, version: getVersion() })
 );
-dataRoute.get("/sessions", (c) => c.json(listSessions()));
+dataRoute.get("/sessions", (c) => {
+  const enriched = listSessions().map((s) => {
+    const conn = s.connectionId ? getConnection(s.connectionId) : void 0;
+    if (conn) {
+      return {
+        ...s,
+        connectionName: conn.name,
+        mode: conn.mode,
+        buyerName: getBuyer(conn.buyerId)?.name,
+        supplierName: getSupplier(conn.supplierId)?.name,
+        inbound: false
+      };
+    }
+    const supplier = s.connectionId ? getSupplier(s.connectionId) : void 0;
+    return {
+      ...s,
+      supplierName: supplier?.name,
+      mode: supplier ? "virtual-supplier" : void 0,
+      inbound: !!supplier
+      // an external buyer hit our /sim
+    };
+  });
+  return c.json(enriched);
+});
 dataRoute.get("/sessions/:id", (c) => c.json(readSession(c.req.param("id"))));
+dataRoute.delete("/sessions/:id", (c) => {
+  const id = c.req.param("id");
+  const removed = deleteSession(id);
+  forgetSession(id);
+  return removed ? c.json({ ok: true }) : c.json({ error: "not found" }, 404);
+});
 dataRoute.get("/sessions/:sessionId/records/:recordId/raw", (c) => {
   const record = readSession(c.req.param("sessionId")).find((r) => r.id === c.req.param("recordId"));
   if (!record) return c.json({ error: "not found" }, 404);
@@ -2518,17 +2610,35 @@ simRoute.get("/:id/catalog", (c) => {
   return c.html(`<!doctype html><html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeXml(supplier.name)} \u2014 mock catalog</title>
+<script>
+  // Match the main app's theme. The app appends ?theme= to the catalog link
+  // (works even when the SPA is on a different origin, e.g. the Vite dev server);
+  // otherwise fall back to a same-origin 'pos-theme' in localStorage, then the OS
+  // preference. Set before paint to avoid a flash.
+  (function () {
+    try {
+      var q = new URLSearchParams(location.search).get("theme");
+      var t = (q === "light" || q === "dark") ? q : localStorage.getItem("pos-theme");
+      if (t !== "light" && t !== "dark") {
+        t = (window.matchMedia && matchMedia("(prefers-color-scheme: light)").matches) ? "light" : "dark";
+      }
+      document.documentElement.dataset.theme = t;
+    } catch (e) {}
+  })();
+</script>
 <style>
-  body{font-family:system-ui,sans-serif;background:#0f172a;color:#e2e8f0;margin:0;padding:2rem}
+  :root{--bg:#0f172a;--text:#e2e8f0;--muted:#94a3b8;--panel:#1e293b;--th:#0b1220;--border:#334155;--field:#0b1220;--price:#fbbf24;--accent:#6366f1;--accent-hover:#4f46e5}
+  :root[data-theme="light"]{--bg:#f5f7fb;--text:#1e293b;--muted:#4b5a73;--panel:#ffffff;--th:#eef1f7;--border:#d4dae8;--field:#ffffff;--price:#b45309;--accent:#6366f1;--accent-hover:#4f46e5}
+  body{font-family:system-ui,sans-serif;background:var(--bg);color:var(--text);margin:0;padding:2rem}
   .wrap{max-width:720px;margin:0 auto}
-  h1{font-size:1.4rem}.sub{color:#94a3b8;margin-bottom:1.5rem}
-  table{width:100%;border-collapse:collapse;background:#1e293b;border-radius:12px;overflow:hidden}
-  th,td{padding:.75rem 1rem;text-align:left;border-bottom:1px solid #334155}
-  th{background:#0b1220;font-size:.8rem;text-transform:uppercase;letter-spacing:.05em;color:#94a3b8}
-  .price{white-space:nowrap;color:#fbbf24}
-  input[type=number]{width:5rem;background:#0b1220;border:1px solid #334155;color:#e2e8f0;border-radius:6px;padding:.35rem .5rem}
-  button{margin-top:1.5rem;background:#6366f1;color:#fff;border:0;border-radius:8px;padding:.7rem 1.4rem;font-size:1rem;cursor:pointer}
-  button:hover{background:#4f46e5}
+  h1{font-size:1.4rem}.sub{color:var(--muted);margin-bottom:1.5rem}
+  table{width:100%;border-collapse:collapse;background:var(--panel);border-radius:12px;overflow:hidden}
+  th,td{padding:.75rem 1rem;text-align:left;border-bottom:1px solid var(--border)}
+  th{background:var(--th);font-size:.8rem;text-transform:uppercase;letter-spacing:.05em;color:var(--muted)}
+  .price{white-space:nowrap;color:var(--price)}
+  input[type=number]{width:5rem;background:var(--field);border:1px solid var(--border);color:var(--text);border-radius:6px;padding:.35rem .5rem}
+  button{margin-top:1.5rem;background:var(--accent);color:#fff;border:0;border-radius:8px;padding:.7rem 1.4rem;font-size:1rem;cursor:pointer}
+  button:hover{background:var(--accent-hover)}
 </style></head><body><div class="wrap">
   <h1>${escapeXml(supplier.name)} <small>(virtual supplier)</small></h1>
   <div class="sub">Mock catalog served by punchout-simulator. Set quantities and return the cart.</div>
@@ -2547,7 +2657,10 @@ simRoute.post("/:id/checkout", async (c) => {
   const supplier = getSupplier(c.req.param("id"));
   if (!supplier) return c.text("supplier not found", 404);
   const form = await c.req.parseBody();
-  const cookie = String(form.cookie ?? `pos-${nanoid6(16)}`);
+  const cookie = typeof form.cookie === "string" ? form.cookie.trim() : "";
+  if (!cookie) {
+    return c.text("missing BuyerCookie \u2014 open the catalog from a SetupResponse StartPage", 400);
+  }
   const formpost = safeHttpUrl(String(form.formpost ?? ""));
   const buyerCred = { domain: String(form.bd ?? ""), identity: String(form.bi ?? "") };
   const catalog = catalogOf(supplier);

package/dist/web/assets/{cssMode-BbEnQNgt.js → cssMode-DipgJtey.js}

@@ -1,4 +1,4 @@
-import{m as et}from"./index-DRD_fRQi.js";/*!-----------------------------------------------------------------------------
+import{m as et}from"./index-ByIxIbJu.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license

package/dist/web/assets/{freemarker2-B66AqaBn.js → freemarker2-Broesno_.js}

@@ -1,4 +1,4 @@
-import{m as f}from"./index-DRD_fRQi.js";/*!-----------------------------------------------------------------------------
+import{m as f}from"./index-ByIxIbJu.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license

package/dist/web/assets/{handlebars-VHNJA3L3.js → handlebars-CjP6B5LA.js}

@@ -1,4 +1,4 @@
-import{m as l}from"./index-DRD_fRQi.js";/*!-----------------------------------------------------------------------------
+import{m as l}from"./index-ByIxIbJu.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license

package/dist/web/assets/{html-DKhtq5mU.js → html-DRw6NWlS.js}

@@ -1,4 +1,4 @@
-import{m as s}from"./index-DRD_fRQi.js";/*!-----------------------------------------------------------------------------
+import{m as s}from"./index-ByIxIbJu.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license

package/dist/web/assets/{htmlMode-DTvp4_of.js → htmlMode-CRd2lx43.js}

@@ -1,4 +1,4 @@
-import{m as lt}from"./index-DRD_fRQi.js";/*!-----------------------------------------------------------------------------
+import{m as lt}from"./index-ByIxIbJu.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license