# Pizza x402 Public API Documentation

This folder contains documentation intended for **external consumers** of the Pizza x402 API, including LLM agents, integration partners, and developers building on top of the API.

## Contents

- **[AGENTS.md](../../AGENTS.md)** - LLM/Agent integration guide (root for easy discovery)
- **[openapi.yaml](../../openapi.yaml)** - OpenAPI 3.1 specification for the public `/v1/*` and partner `/partner/*` HTTP surface
- **[contract-parity.md](contract-parity.md)** - Runtime/OpenAPI/AGENTS parity matrix and guardrails
- **[merchant-context-parity-checklist.md](merchant-context-parity-checklist.md)** - Canonical merchant identifier and shared configuration parity gate for API, MCP, and storefront work
- **[reference/](reference/README.md)** - Generated versioned endpoint reference derived from `openapi.yaml`
- **[ia.json](ia.json)** - Canonical information architecture manifest for `docs/public/**`
- **[search-index.json](search-index.json)** - Deterministic static search artifact for public docs consumers
- **[llms.txt](llms.txt)** - Stable high-value docs path index for LLM ingestion
- **[llms-full.md](llms-full.md)** - Concatenated full docs bundle with per-source delimiters
- **[skills.md](skills.md)** - Agent-agnostic `SKILL.md` bundles and usage guidance
- **[mcp.md](mcp.md)** - Official `pizzax402-mcp` repo path plus MCP tool mapping and maintainer notes
- **[a2a.md](a2a.md)** - A2A gateway MVP (Agent Card + REST task lifecycle)
- **[sdk-js package](../../packages/sdk-js/README.md)** - Typed JavaScript/TypeScript HTTP client scaffold for core ordering operations
- **[trustless-agents.md](trustless-agents.md)** - ERC-8004-aligned off-chain bridge exports (metadata, feedback, validation)
- **[quickstarts/](quickstarts/README.md)** - Agent-specific quickstarts plus canonical 5-minute first paid order path
- **[compatibility-matrix.md](compatibility-matrix.md)** - Supported agent interfaces and transport maturity
- **[examples/](examples/)** - Example API flows and curl commands

## Quick Start

```bash
# Get the menu
curl http://localhost:3000/v1/menu

# Create a quote
curl -X POST http://localhost:3000/v1/orders/quote \
  -H "Content-Type: application/json" \
  -d '{"items":[{"sku":"PZ-MAR","qty":1}],"fulfillment":{"type":"pickup"},"contact":{"name":"Test","phone":"+33600000000"}}'

# Confirm order (will return 402 for payment)
curl -X POST http://localhost:3000/v1/orders/confirm \
  -H "Content-Type: application/json" \
  -d '{"quoteId":"YOUR_QUOTE_ID"}'
```

## API Categories

| Prefix | Audience | Auth Required | Description |
|--------|----------|---------------|-------------|
| `/v1/*` | PUBLIC_AGENT | No by default; optional scoped `X-API-Key` when hardened mode is enabled | LLM-friendly ordering endpoints |
| `/partner/*` | PARTNER_RESTRICTED | Yes (X-API-Key) | Kitchen/admin operations |

Operational `/internal/*` routes remain intentionally undocumented in the public OpenAPI, LLM bundle, and website export.

## Optional Public API Key Mode

Production-facing deployments can harden `/v1/*` routes with scoped public API keys:

```bash
PUBLIC_API_AUTH_MODE=api-key
PUBLIC_API_KEYS='[{"id":"public-order-client","merchantId":"merchant-demo-001","scopes":["menu:read","wallet-setup:read","quote:create","confirm:create","order:read"],"key":"replace-with-long-random-public-api-key"}]'
```

When enabled:
- Send `X-API-Key` on every `/v1/*` request.
- Keys are merchant-bound and scope-limited instead of reusing the partner/admin key.
- Missing, invalid, or out-of-scope keys return deterministic `401 UNAUTHORIZED` payloads.

Default behavior remains unchanged when `PUBLIC_API_AUTH_MODE` is unset or `open`.

## IA Manifest

`docs/public/ia.json` is the machine-readable index of public docs pages. It is generated by:

```bash
node scripts/docs/build-ia-manifest.mjs
```

Check mode (for CI and local validation):

```bash
node scripts/docs/build-ia-manifest.mjs --check
```

Each page entry includes:
- `path`
- `category`
- `audience`
- `canonicalSource`

## Static Search Index

`docs/public/search-index.json` is the deterministic search artifact derived from the public docs IA manifest. Each entry includes:
- `path`
- `title`
- `headings`
- `excerpt`

Generate the search index:

```bash
node scripts/docs/build-search-index.mjs
```

Check committed index freshness:

```bash
node scripts/docs/build-search-index.mjs --check
```

Consumption notes:
- Prefer matching query terms against `title`, `headings`, `excerpt`, and `path`.
- The website export bundle carries `docs/public/search-index.json` unchanged under `artifacts/docs-site/`.

The manifest-level `canonicalSourceMap` records contract roots used downstream:
- `AGENTS.md`
- `openapi.yaml`
- `docs/public/contract-parity.md`

Merchant-context rule:
- `docs/public/merchant-context-parity-checklist.md` owns the canonical shared merchant configuration field list and the API/MCP/storefront parity checklist.

## Docs QA Commands

Run docs preview build:

```bash
npm run docs:preview
```

Run docs link integrity checks:

```bash
npm run docs:check-links
```

Notes:
- Local markdown links are validated for all pages listed in `docs/public/ia.json`.
- External canonical links are validated with bounded retries/timeouts and require no secrets.

## LLM Bundle Generation

Generate `llms.txt` and `llms-full.md`:

```bash
node scripts/docs/generate-llms-bundle.mjs
```

Check committed bundle freshness:

```bash
node scripts/docs/generate-llms-bundle.mjs --check
```

## Generated API Reference

Generate the versioned endpoint reference from `openapi.yaml`:

```bash
node scripts/docs/generate-api-reference.mjs
```

Check mode (for CI and local validation):

```bash
node scripts/docs/generate-api-reference.mjs --check
```

## Website Export Bundle

Generate the self-contained website ingestion bundle for `pizza-x402-site`:

```bash
node scripts/docs/export-site-bundle.mjs
```

Check committed bundle freshness:

```bash
node scripts/docs/export-site-bundle.mjs --check
```

The bundle is written to `artifacts/docs-site/` and includes:
- Core contract roots: `AGENTS.md`, `openapi.yaml`, `packages/sdk-js/README.md`
- Public docs artifacts under `docs/public/**` (including generated reference and llms outputs)
- Search metadata at `docs/public/search-index.json`
- Website-oriented metadata: `metadata/navigation.json`, `metadata/quickstarts.json`
- `manifest.json` with the source commit SHA, deterministic generation timestamp, and exported file inventory

## Public Docs Endpoint Verifier

Verify deployed `sitemap.xml`, `robots.txt`, and `llms.txt` endpoints for the configured public docs target:

```bash
PUBLIC_DOC_ENDPOINT_PRODUCTION_URL=https://docs.example.com \
node scripts/check-public-doc-endpoints.mjs --mode strict
```

For ad hoc checks against a single target (including local or mocked endpoints), use `PUBLIC_DOC_ENDPOINT_TARGETS` with `LABEL=URL` entries:

```bash
PUBLIC_DOC_ENDPOINT_TARGETS="mock=http://127.0.0.1:4173" \
node scripts/check-public-doc-endpoints.mjs --mode strict
```

Notes:
- `--mode strict` exits non-zero on missing endpoints, content-type mismatches, or missing endpoint content markers.
- `--mode warn` reports the same failures but exits zero so CI can surface external flakiness without blocking the whole job.
- CI reads `PUBLIC_DOC_ENDPOINT_PRODUCTION_URL` when it is configured in repository variables.

## Resources

- [OpenAPI Spec](../../openapi.yaml)
- Runtime endpoint: `GET /v1/openapi.yaml`
- [AGENTS.md](../../AGENTS.md) - Complete LLM integration guide