punchout-simulator 0.3.1 → 0.5.0

package/README.md

@@ -99,8 +99,8 @@ Document-specific:
 | Document | Checks |
 |---|---|
 | **PunchOutSetupResponse** | `Status` present & `200`; valid `StartPage/URL` |
-| **PunchOutOrderMessage** (punchback) | `BuyerCookie` matches the session; header `Total`/`Money`+currency; each `ItemIn` has quantity, `SupplierPartID`, `UnitPrice`+currency, `Description`, `UnitOfMeasure`, `Classification`@domain; **Total consistency** (sum of line totals) |
-| **OrderRequest** | `orderID`/`orderDate`/`Total`; `ShipTo`/`BillTo`; each `ItemOut`; **attachment `cid:` resolution** (see below) |
+| **PunchOutOrderMessage** (punchback) | `BuyerCookie` matches the session; header `Total`/`Money`+currency; each `ItemIn` has quantity, `SupplierPartID`, `UnitPrice`+currency, `Description`, `UnitOfMeasure`, `Classification`@domain; **single currency** (mixed-currency is an error unless the supplier allows it); **Total consistency** (sum of line totals) |
+| **OrderRequest** | `orderID`/`orderDate`/`Total`; `ShipTo`/`BillTo` present **and complete** (an `addressID` or a postal Street/City — an empty block is flagged); `Contact@role`; each `ItemOut`; **single currency** (as above); **attachment `cid:` resolution** (see below) |
 | **OrderResponse** | `Status` code present / not an error |
 
 > Note: full cXML DTD validation would require a native validating XML parser,
@@ -167,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 buyers/suppliers/connections/profiles · append-only JSONL per session for logs · separate files for attachments |
+| Storage | `lowdb` (`config.json`) for buyers/suppliers/connections/product-lists/profiles · append-only JSONL per session for logs · separate files for attachments |
 
 ```
 src/
@@ -178,15 +178,51 @@ src/
 
 ### Data model
 
-The config is normalized into four entities:
+The config is normalized into five 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`.
+- **Buyer** — a reusable party holding its own cXML identity (the `From` credential), an optional **platform profile** reference (see below), and optional default **ShipTo / BillTo addresses** and an end-user **Contact** (see below).
+- **Supplier** — a reusable party holding its cXML identity (`To`) plus its **endpoints** (PunchOut URL, Order URL) and the **product lists** it serves as its Mode-B catalog. Endpoints are intrinsic to the supplier — defined once, not per relationship. An optional `allowMixedCurrency` flag relaxes the multi-currency check for this supplier (see below).
+- **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), `deploymentMode`, and `attachmentEncoding`.
+- **Product List** — a reusable, named set of catalog products. Assigned to one or more Suppliers; each supplier serves the **union** of its lists as its mock catalog. See below.
 - **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>/…`).
 
+### Product lists (Mode-B catalogs)
+
+A **Product List** is a named set of catalog items, edited on its own and assigned to one or
+more Suppliers from the **Products** tab. In Mode B a supplier serves the union of its assigned
+lists; a supplier with no lists falls back to a small built-in demo catalog. A built-in
+**Sample assortment** (~20 office/industrial items) ships out of the box and can be **loaded
+into the editor** as a starting point. You can also **import a CSV** (a header row, any column
+order; `SupplierPartID` required) to bulk-load a real catalog — a template is downloadable from
+the editor. Recognized columns: `SupplierPartID`, `SupplierPartAuxiliaryID`, `Description`,
+`UnitPrice`, `Currency`, `UoM`, `UNSPSC` (or a `Classifications` column as
+`UNSPSC:31161500;eCl@ss:27-06`), `ManufacturerPartID`, `ManufacturerName`, `AllowFractional`.
+
+Each product carries a `SupplierPartID`, an optional `SupplierPartAuxiliaryID`, description, unit
+price + currency, unit of measure, manufacturer info, and **one or more `Classification`** entries
+(each with its own `domain`, e.g. `UNSPSC` plus a supplier scheme like `eCl@ss`). A product may opt
+into **fractional order quantities** (e.g. `1.5` m of cable) via its `allowFractional` flag — the
+Mode-B catalog then accepts decimals for that item; all other items stay whole-number. These fields
+flow through to the punchback (`ItemIn`) and the resulting OrderRequest (`ItemOut`).
+
+**Currency.** A cXML `Total` is a single `Money`, so a document is expected to be single-currency.
+If a cart/order spans more than one currency the mock supplier emits `Total` `0` (rather than a
+meaningless cross-currency sum) and validation raises a `mixed-currency` **error**. A supplier that
+genuinely handles multi-currency orders can set **`allowMixedCurrency`**, which downgrades that to a
+non-blocking **warning** (the per-line `Money` currencies are always preserved either way).
+
+### Addresses & contact
+
+A **Buyer** holds default **ShipTo** / **BillTo** addresses and an end-user **Contact** (name, email,
+phone). They pre-fill the OrderRequest (which stays fully editable as cXML before sending) and, when the
+buyer's profile enables it, are also carried in the **PunchOutSetupRequest** (Ariba-style). Each address
+supports a postal block and/or an `addressID` (+ `addressIDDomain`) reference; the **profile's
+`addressMode`** decides which is emitted (`full` / `id-only` / `both`) — matching how platforms differ
+(Jaggaer/Workday send full postal, SAP is plant-code/`addressID`-centric, Ariba sends both and includes
+ShipTo in setup). An emitted `ShipTo`/`BillTo` with neither an `addressID` nor a Street/City is flagged.
+
 ### Simulating different procurement platforms (Buyer profiles)
 
 Real procurement systems emit cXML differently. A **Profile** captures a platform's
@@ -201,6 +237,8 @@ Ariba, Coupa, Jaggaer, Oracle, SAP, or Workday:
 | `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}`). |
+| `addressMode` | How `ShipTo`/`BillTo`/`Contact` are emitted: `full` (PostalAddress), `id-only` (just `addressID`), or `both`. |
+| `shipToInSetup` / `contactInSetup` | Carry the buyer's `ShipTo` / `Contact` already in the **PunchOutSetupRequest** (Ariba-style), so the supplier can price/personalize per ship-to. |
 
 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
@@ -218,6 +256,7 @@ cxml-urlencoded) — i.e. the tool's original behavior.
 
 - `*/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/product-lists` — CRUD for product lists · `GET /api/product-list-presets` — the built-in sample 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)