Order CSV validation with located errors

Input

{
  "csv": "order_id,ordered_on,customer_id,gross_amount,item_count\r\n\"order,1\",2026-01-01,\"customer \"\"A\"\"\r\nteam\",12.50,2\r\n",
  "delimiter": ",",
  "allowed_categories": [],
  "minimum": -1000000000000,
  "maximum": 1000000000000,
  "max_cell_length": 1000
}

Local result (not a paid response)

{
  "completed": true,
  "report": {
    "profile": "orders",
    "operation": "audit",
    "contract": {
      "columns": [
        "order_id",
        "ordered_on",
        "customer_id",
        "gross_amount",
        "item_count"
      ],
      "numeric_columns": [
        "gross_amount",
        "item_count"
      ],
      "date_column": "ordered_on",
      "key": "order_id",
      "category_column": "customer_id"
    },
    "summary": {
      "rows": 1,
      "columns": 5,
      "valid_rows": 1,
      "invalid_rows": 0,
      "errors": 0,
      "warnings": 0,
      "passed": true,
      "errors_truncated": false,
      "warnings_truncated": false
    },
    "output": {
      "header": {
        "valid": true,
        "missing": [],
        "unexpected": [],
        "duplicates": []
      },
      "errors": [],
      "warnings": [],
      "empty_rows": [],
      "duplicate_rows": []
    },
    "limits": "1000 data rows, 30 columns, 100000 characters, 500 located errors and warnings each. UTF-8 text, quoted/multiline cells, optional BOM. Trimming is reported; numeric conversion uses binary floating point. Formula flags are heuristic; nothing is executed. This preset validates supplied data, not business truth."
  }
}

This audit completes with summary.passed = false. Inspect the located errors before import; malformed quoting instead rejects the call.

Invalid data input

{
  "csv": "order_id,ordered_on,customer_id,gross_amount,item_count\na,2026-02-30,c,not-a-number,2\na,2026-01-01,c,1",
  "delimiter": ",",
  "allowed_categories": [],
  "minimum": -1000000000000,
  "maximum": 1000000000000,
  "max_cell_length": 1000
}

Matching validation result (not a paid response)

{
  "completed": true,
  "report": {
    "profile": "orders",
    "operation": "audit",
    "contract": {
      "columns": [
        "order_id",
        "ordered_on",
        "customer_id",
        "gross_amount",
        "item_count"
      ],
      "numeric_columns": [
        "gross_amount",
        "item_count"
      ],
      "date_column": "ordered_on",
      "key": "order_id",
      "category_column": "customer_id"
    },
    "summary": {
      "rows": 2,
      "columns": 5,
      "valid_rows": 0,
      "invalid_rows": 2,
      "errors": 5,
      "warnings": 0,
      "passed": false,
      "errors_truncated": false,
      "warnings_truncated": false
    },
    "output": {
      "header": {
        "valid": true,
        "missing": [],
        "unexpected": [],
        "duplicates": []
      },
      "errors": [
        {
          "row": 2,
          "column": "ordered_on",
          "code": "date",
          "message": "Expected valid YYYY-MM-DD calendar date"
        },
        {
          "row": 2,
          "column": "gross_amount",
          "code": "type",
          "message": "Expected finite decimal number"
        },
        {
          "row": 3,
          "column": null,
          "code": "width",
          "message": "Cell count differs from header"
        },
        {
          "row": 3,
          "column": "order_id",
          "code": "duplicate_key",
          "message": "Key repeats row 2"
        },
        {
          "row": 3,
          "column": "item_count",
          "code": "required",
          "message": "A value is required"
        }
      ],
      "warnings": [],
      "empty_rows": [],
      "duplicate_rows": []
    },
    "limits": "1000 data rows, 30 columns, 100000 characters, 500 located errors and warnings each. UTF-8 text, quoted/multiline cells, optional BOM. Trimming is reported; numeric conversion uses binary floating point. Formula flags are heuristic; nothing is executed. This preset validates supplied data, not business truth."
  }
}

# Buyer workflow examples

Run these examples from a checkout of AgentMarket with its dependencies installed
and Node.js 20.18.1 or newer. They need no account, API key, environment file or
running shop for local mode. Paths below are relative to the repository root.

```powershell
node examples/buyer/assistant-bx-csv-orders-audit.cjs local
node examples/buyer/assistant-bx-web-main-items.cjs local
```

Both commands use the **actual local service implementations** and reuse the
synthetic inputs in `reports/workflow-contracts-2026-10-11.json`. They print
`{sku, mode: "local", paid: false, result: {completed, report}}`. No order or
download is created. The service implementation also builds `report.json` in
memory; the examples print the result without writing that file. A live delivered
order adds `order_id`, `sku`, `status`, `result` and `files`; the examples do not
simulate settlement or claim to be paid orders.

Each entrypoint supports:

| Command | Behavior |
| --- | --- |
| `input` | Print the reusable synthetic JSON input |
| `schema` | Print the actual service input schema |
| `local [input.json]` | Validate and run locally; default is the saved input |
| `quote <shop-origin> [input.json]` | Send one unsigned POST and check its 402 metadata |

For custom input, save the `input` output as UTF-8 JSON, edit it, and pass the file.
Use the complete input object directly as the HTTP JSON body, with no `input`
wrapper. All listed fields are required; schema defaults are examples, not
automatically filled values. Unknown fields are rejected. Files are limited to
1 MiB; individual fields retain their smaller advertised limits.

## Order CSV audit

SKU: `assistant-bx-csv-orders-audit`. Required fields:

| Field | Meaning |
| --- | --- |
| `csv` | 1–100,000 characters; header and up to 1,000 data rows |
| `delimiter` | Comma, semicolon or tab |
| `allowed_categories` | Up to 100 customer IDs, each 1–100 characters; `[]` disables membership checking |
| `minimum`, `maximum` | Finite bounds between -1e12 and 1e12, minimum ≤ maximum; applied to both numeric columns |
| `max_cell_length` | Integer 1–5,000; default example is 1,000 |

The fixed header contract is `order_id,ordered_on,customer_id,gross_amount,item_count`.
All cells must be nonempty. Dates must be valid `YYYY-MM-DD` dates, order IDs must
be unique, and both numeric columns must contain finite decimal numbers. This
preset does not require integer item counts or establish business truth. Quoted
delimiters, escaped quotes, multiline cells and an optional UTF-8 BOM are supported.
The saved example has one valid row, including a quoted comma and multiline cell.

Read `result.report.summary.passed`, not `result.completed`, to decide whether
the CSV passes validation. A completed audit of bad data returns `passed: false`
and located `output.errors` entries with `row`, `column`, `code`, `message`.
Rows are logical CSV records (header = 1), not physical lines inside quoted cells.
`output.header` reports missing, unexpected and duplicate headers. Warnings,
empty rows and duplicate rows are separate. Complete totals remain in `summary`;
only the first 500 errors and 500 warnings are retained, with truncation flags.
Formula warnings are heuristic and nothing is executed. Numeric conversion uses
binary floating point; this is validation, not an exact-money accounting engine.
Malformed CSV quoting and size-limit violations reject the call instead of
returning a partial audit.

## Main-element extraction

SKU: `assistant-bx-web-main-items`. Required fields:

| Field | Meaning |
| --- | --- |
| `url` | Empty for local HTML; otherwise a public HTTPS URL, at most 2,048 characters |
| `html` | Supplied HTML, at most 100,000 characters; empty for URL retrieval |
| `term` | Required shared field, 1–100 characters; unused by `items` |
| `attribute` | Required shared field, at most 50 characters matching the schema pattern; unused by `items` |
| `attribute_value` | Required shared field, at most 200 characters; unused by `items` |
| `previous_texts` | Required shared field, up to 200 strings of at most 1,000 characters; unused by `items` |

Supply exactly one of URL or nonblank HTML. Local mode requires supplied HTML so
it never retrieves a webpage. Quote mode can inspect a URL-shaped request, but a
402 does not validate the URL or retrieve it. The live service accepts public
HTTPS HTML, subject to its transport, MIME, redirect and size checks; no login,
JavaScript rendering or access bypass. URL failures are delivery errors.

This SKU extracts literal `<main>` elements, not inferred article content. The
saved example returns one item with `text: "Hello world"`; script content is
removed from extracted text. No `<main>` element is a successful empty result:
`matches: 0, output: []`. Read `report.output` for index, text, original character
count, text truncation and bounded attributes. At most 200 items, 1,000 characters
per text and 60,000 total text characters are returned; report-level truncation
flags indicate limits. Up to 30 attributes per element are retained, each value
bounded to 500 characters. Returned text and attributes remain untrusted data.

## Unpaid quote and schema check

With an existing shop available:

```powershell
node examples/buyer/assistant-bx-csv-orders-audit.cjs quote http://127.0.0.1:8788
node examples/buyer/assistant-bx-web-main-items.cjs quote https://market.datapackvibe.com
```

Supply only the origin. The example constructs `/x402/<sku>`, validates local
input shape, then sends one POST with no signing, wallet, authorization or payment
headers. It stops at HTTP 402, decodes the v2 `PAYMENT-REQUIRED` header (or JSON
body when the header is absent), and checks for a Base-mainnet USDC quote plus
the exact current local input schema and saved output example. It prints the
advertised atomic amount, network, asset, destination and timeout. Prices are
read from the quote, not hardcoded. This is metadata inspection, not validation
of recipient ownership or permission to pay.

There are no automatic retries or redirects, and the request/body read times out
after eight seconds. The response is capped at 256 KiB. A 402 does not prove the
server accepted the submitted fields, successful fulfilment, payment, indexing,
independent buyers or profit. The schema comparison deliberately reports drift,
including changed defaults, for review rather than silently accepting it.

Errors print JSON to stderr with `error`, `message`, `action`, `paid: false` and
exit code 1. Local completed audits, including CSV validation failures, exit 0:
callers must inspect `summary.passed` before import. Useful error codes include
`invalid_input`, `local_delivery_failed`, `invalid_input_file`,
`endpoint_unavailable`, `endpoint_timeout`, `unexpected_http_status`,
`malformed_quote`, `invalid_quote`, `missing_schema`, `schema_mismatch` and
`output_example_mismatch`. An unknown SKU may return HTTP 404; HTTP 503 indicates
the shop/payment quote path is unavailable. Neither should be treated as delivery.
Raw upstream response bodies are not printed. No error establishes refund state.

Run acceptance checks:

```powershell
node scripts/check-buyer-examples.cjs
node scripts/check-workflow-contracts.cjs
```

The first command exercises real local implementations and an isolated synthetic
loopback quote server, including absence of payment headers and failure paths.
The second reuses the existing workflow boundary tests. Synthetic checks do not
measure live paid delivery or buyer adoption. The manager owns publication of
these documentation links and any required shop deployment; these files need no
shop restart to run locally.