punchout-simulator 0.5.2 → 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" });
@@ -2402,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);
@@ -2580,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-BNnlXFNU.js → cssMode-DipgJtey.js}

@@ -1,4 +1,4 @@
-import{m as et}from"./index-CR8XUPcx.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-BuNAmJWP.js → freemarker2-Broesno_.js}

@@ -1,4 +1,4 @@
-import{m as f}from"./index-CR8XUPcx.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-BJ-VFQ5X.js → handlebars-CjP6B5LA.js}

@@ -1,4 +1,4 @@
-import{m as l}from"./index-CR8XUPcx.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-BkFoYEs4.js → html-DRw6NWlS.js}

@@ -1,4 +1,4 @@
-import{m as s}from"./index-CR8XUPcx.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-DamCYXd_.js → htmlMode-CRd2lx43.js}

@@ -1,4 +1,4 @@
-import{m as lt}from"./index-CR8XUPcx.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