punchout-simulator 0.1.5 → 0.3.0

package/README.md

@@ -30,12 +30,15 @@ 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 → built-in supplier** connection.
+1. Open the **Demo Buyer → Demo Supplier** connection.
 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. **Send the OrderRequest** (optionally with attachments, optionally with the
-   dangling-`cid` test) and inspect the supplier's response.
+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.
 
 Every document — inbound and outbound — is validated and logged.
 
@@ -46,8 +49,10 @@ npm i -g punchout-simulator && punchout-simulator   # persistent install
 ```
 
 ```bash
-# Docker
-docker run -p 8080:8080 -v "$PWD/data:/data" punchout-simulator
+# Docker (binds 0.0.0.0 inside the container ⇒ counts as "exposed" ⇒ /api needs a
+# token). Set your own, or read the auto-generated ?token= URL from the logs:
+docker run -p 127.0.0.1:8080:8080 -e POS_TOKEN=mysecret -v "$PWD/data:/data" punchout-simulator
+# then open http://localhost:8080/?token=mysecret
 ```
 
 ### CLI options
@@ -57,12 +62,25 @@ docker run -p 8080:8080 -v "$PWD/data:/data" punchout-simulator
 -d, --data-dir <path>  Where to store config + logs (default ./data)
     --public-url <url> Externally reachable base URL (default http://localhost:<port>)
                        Set this when fronting the tool with ngrok/cloudflared.
+    --host <addr>      Bind address (default 127.0.0.1; use 0.0.0.0 to expose on the LAN)
+    --token <secret>   Require this token on /api (auto-generated when exposed; or set POS_TOKEN)
     --no-open          Do not open a browser on start
-    --no-seed          Do not seed the built-in demo connections on first run
+    --no-seed          Do not seed the built-in demo buyer/supplier/connection on first run
     --dev              Dev mode (do not serve the SPA, do not open a browser)
 -h, --help             Show help
 ```
 
+### Exposure & the admin API
+
+The control plane (`/api/*` — config CRUD, logs, the live stream) is **bound to
+`127.0.0.1` by default** and is unauthenticated only for that loopback case. The
+moment the tool is **exposed** — a non-loopback `--public-url` (ngrok/cloudflared)
+or `--host 0.0.0.0` — it **requires a token** on `/api/*`: one is auto-generated
+(or pass `--token`/`POS_TOKEN`) and printed as a `…/?token=…` URL to open the UI
+with. The **inbound buyer surface stays open** (`/sim/*`, `/punchout/return`) so a
+real buyer system can still reach Mode B. Shared secrets are **write-only** over
+the API (masked on read) and **redacted from all logs**.
+
 ---
 
 ## What it checks (validation / linting)
@@ -73,7 +91,8 @@ document in both directions, and results are surfaced per message in the UI
 emit correct cXML?"* linter as a transport driver.
 
 General checks: well-formedness, `payloadID`/`timestamp` presence, and
-`From`/`To`/`Sender` credential + `SharedSecret` consistency with the connection.
+`From`/`To`/`Sender` credentials + `SharedSecret` consistency with the
+connection's buyer/supplier identities.
 
 Document-specific:
 
@@ -97,6 +116,30 @@ receiver detects the missing attachment. `<Comments>` (and therefore
 `<Attachment>`) is scanned at **both** levels: `OrderRequestHeader` and each
 `ItemOut`.
 
+### Editing the OrderRequest, attachments & retry
+
+- The OrderRequest is built from the returned cart into an editable Monaco view.
+  **Edit it before sending** — `<Comments>`, addresses, attachment references,
+  anything; the exact document you see is what gets sent.
+- **Attachments are scoped per item or per order**, so the `cid` reference lands
+  in the right `ItemOut/Comments` or `OrderRequestHeader/Comments`.
+- **Transfer encoding is a per-connection setting** (`attachmentEncoding`):
+  `binary` writes the raw bytes into each MIME part (valid over HTTP and more
+  compact), while `base64` is the `Content-Transfer-Encoding` most real
+  Ariba/Coupa receivers expect. Switch it in the connection editor to exercise
+  either ingestion path; the built-in mock supplier (Mode B) decodes whichever
+  it receives. Defaults to `binary`.
+- The flow is a **persistent per-connection session**: switching between the
+  Flow and Settings tabs (or connections) keeps your in-progress order, and you
+  can **edit and re-send** after a supplier rejection. "New session" starts a
+  fresh `BuyerCookie`.
+- Every logged message has a **cXML / Raw toggle**. "Raw" shows the full wire
+  message — headers plus, for an order with attachments, the reassembled
+  `multipart/related` envelope (boundaries, part headers, `Content-ID`, the cXML
+  and each attachment part) — with a one-click **Copy**. The raw body is
+  reconstructed on demand from the document + the attachments on disk, so the
+  log stays free of inlined base64.
+
 ---
 
 ## Network reachability
@@ -124,7 +167,7 @@ backend, so there is no CORS between them).
 | XML parsing | `fast-xml-parser` |
 | cXML building | template literals (full control over shape/ordering/`xml:lang`) |
 | multipart/related | hand-assembled (`Buffer` + boundary) |
-| Storage | `lowdb` (`config.json`) for connections · append-only JSONL per session for logs · separate files for attachments |
+| Storage | `lowdb` (`config.json`) for buyers/suppliers/connections/profiles · append-only JSONL per session for logs · separate files for attachments |
 
 ```
 src/
@@ -133,14 +176,54 @@ src/
    └─ cxml/  build · parse · validate · multipart · types
 ```
 
+### Data model
+
+The config is normalized into four entities:
+
+- **Buyer** — a reusable party holding its own cXML identity (the `From` credential) and an optional **platform profile** reference (see below).
+- **Supplier** — a reusable party holding its cXML identity (`To`) plus its **endpoints** (PunchOut URL, Order URL) and an optional mock catalog. Endpoints are intrinsic to the supplier — defined once, not per relationship.
+- **Connection** — the edge pairing one Buyer with one Supplier. It holds only what is specific to that pair: which side the tool simulates (`mode`), the `sharedSecret`, an optional per-pair Sender identity override (defaults to the buyer's identity), `authStyle`, `deploymentMode`, and `attachmentEncoding`.
+- **Profile** — a reusable **procurement-platform profile** (Ariba/Coupa/Jaggaer/…) referenced by a Buyer. See below.
+
+At send time: `From` = buyer identity, `To` = supplier identity, `Sender` = the connection's override (or the buyer), and the request targets the supplier's endpoints. The mock-supplier endpoints are keyed by supplier id (`/sim/<supplierId>/…`).
+
+### Simulating different procurement platforms (Buyer profiles)
+
+Real procurement systems emit cXML differently. A **Profile** captures a platform's
+emission behavior and is assigned to a Buyer, so you can drive a supplier as if it were
+Ariba, Coupa, Jaggaer, Oracle, SAP, or Workday:
+
+| Profile field | Effect on the documents the buyer emits |
+|---|---|
+| `dtdVersions` | The `<!DOCTYPE … cXML/<version>/cXML.dtd>` **per document type** (e.g. Coupa: SetupRequest `1.2.014`, PunchOutOrderMessage `1.2.023`). |
+| `userAgent` | The `<UserAgent>` in the Sender. |
+| `setupOperation` | `PunchOutSetupRequest@operation` (`create`/`edit`/`inspect`). |
+| `attachmentEncoding` | Default `Content-Transfer-Encoding` for OrderRequest attachments (`binary`/`base64`). |
+| `cartReturnTransport` | How the punchback is returned in Mode B: `cxml-urlencoded`, `cxml-base64`, or `raw`. |
+| `extrinsics` | `<Extrinsic>` templates injected into the setup/order documents (values may use `${buyerCookie}` / `${orderId}`). |
+
+Built-in presets (Ariba, Coupa, Jaggaer, Oracle, SAP, Workday, Generic) ship out of the box
+and can be **loaded into the editor** as a starting point, then customized. A Profile holds
+the *defaults*; a Connection's own `attachmentEncoding` overrides it per pair. A Buyer with no
+profile uses the **Generic** defaults (`1.2.045` / `punchout-simulator` / binary /
+cxml-urlencoded) — i.e. the tool's original behavior.
+
+> Authentication is **SharedSecret** only. (MAC / `CredentialMac` — used by network-routed
+> Ariba/SAP flows — is intentionally out of scope for now.)
+>
+> SAP SRM in reality speaks **OCI** (form parameters), which this cXML-only tool cannot emit;
+> the SAP profile models the cXML/Business-Network side (base64 attachments + cart return).
+
 ### Endpoints
 
-- `*/api/connections` — CRUD for connection configs
-- `POST /api/connections/:id/setup` — send the SetupRequest, capture + validate the response
-- `POST /api/connections/:id/order` — send the OrderRequest (multipart if attachments), capture + validate
+- `*/api/buyers`, `*/api/suppliers` — CRUD for the reusable parties
+- `*/api/profiles` — CRUD for procurement-platform profiles · `GET /api/profile-presets` — the built-in preset library
+- `*/api/connections` — CRUD for connection edges (reference a buyer + supplier)
+- `GET /api/connections/:id/setup/preview` · `POST …/setup` — preview / send the SetupRequest
+- `POST /api/connections/:id/order/preview` · `POST …/order` — preview / send the OrderRequest (multipart if attachments)
 - `POST /punchout/return` — callback receiving the punchback auto-submit
 - `GET /api/stream` — SSE live log
-- `/sim/:id/*` — Mode B mock supplier (punchout · catalog · checkout · order)
+- `/sim/:supplierId/*` — Mode B mock supplier (punchout · catalog · checkout · order)
 
 ---