@devlab.group/agent-commerce 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Full text: https://www.apache.org/licenses/LICENSE-2.0.txt

package/README.md

@@ -0,0 +1,324 @@
+<h1 align="center">Agent Commerce Gateway</h1>
+
+<p align="center">
+  <strong>One backend. Agent-commerce protocols on the front. No proprietary middleman.</strong>
+</p>
+
+<p align="center">
+  <a href="#quickstart"><img alt="Quickstart" src="https://img.shields.io/badge/quickstart-5%20minutes-2ea44f"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6">
+  <img alt="MCP" src="https://img.shields.io/badge/MCP-supported-6b4fbb">
+  <img alt="x402" src="https://img.shields.io/badge/x402-supported-0052ff">
+  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange">
+</p>
+
+> **Alpha.** `v0.1.0-alpha` is experimental. Do not use it with production funds
+> without an independent review. See [SECURITY.md](SECURITY.md).
+
+---
+
+## What it is, in ten seconds
+
+You already have an HTTP API. AI agents want to **discover** it, **call** it and
+**pay** for it — over protocols you did not write and do not want to maintain.
+
+Agent Commerce Gateway sits in front of your existing API, in **your**
+infrastructure, and does that for you. You describe an endpoint in a YAML file;
+agents get an MCP tool and an x402 paywall. The money goes straight to your
+wallet — the gateway never holds it, and never holds your keys.
+
+```text
+Your existing API → Agent Commerce Gateway → AI Agent
+                        MCP · x402 · receipts · doctor
+```
+
+## Demo
+
+<!-- TODO(release): 15–30s GIF — left: buyer agent terminal, right: dashboard,
+     overlay: on-chain settlement. Replace this block before tagging. -->
+
+```text
+[agent] Discovering resources over MCP...
+[agent] Found: market_report — Premium Market Report (0.01 USDC)
+[agent] Requesting resource...
+
+[gateway] Payment required: 0.01 USDC → 0x7099…79C8
+[buyer] Signing x402 authorisation...
+[gateway] Payment verified
+[gateway] Payment settled tx 0x4f2c…9ab1
+[gateway] Calling merchant backend...
+[gateway] Resource delivered
+
+[receipt] payment: settled
+[receipt] amount: 0.01 USDC
+[receipt] merchant: 0x7099…79C8
+[receipt] buyer balance 100.00 → 99.99 mUSDC
+[receipt] merchant balance 0.00 → 0.01 mUSDC
+```
+
+The dashboard at <http://localhost:5173> shows the same request as it happens.
+It polls the authenticated events route on a short interval rather than
+streaming: a browser `EventSource` cannot send the admin token, and the operator
+routes are closed without one — so the SSE endpoint is reachable by a
+header-capable client, never by a browser. Polling is the dashboard's intended
+path, not a degraded mode.
+
+## Install
+
+```bash
+npx @devlab.group/agent-commerce --help # no install needed
+npm install -g @devlab.group/agent-commerce # or install the `agent-commerce` binary
+agent-commerce doctor
+```
+
+Requires **Node >= 22**. One package ships two things: the `agent-commerce`
+CLI (`init`, `validate`, `doctor`, `demo`) and a library for embedding the
+gateway in your own process. A default install is ~49 MB and pulls no
+blockchain or wallet dependencies at all.
+
+```ts
+import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';
+
+const config = await loadConfig({ path: 'config.yaml' });
+const gateway = await createGateway({
+  config,
+  store: receipts({ path: './receipts.sqlite' }),
+  paymentProviders: [],
+  protocolAdapters: [],
+});
+const { url } = await gateway.listen;
+```
+
+### Optional peers — install only the rails you use
+
+The MCP adapter and the x402 provider live on their own subpaths, because each
+needs a dependency the rest of the package does not. x402 alone pulls a browser
+wallet stack (wagmi, WalletConnect, Reown) worth ~572 MB, which a gateway
+serving a free HTTP resource has no business installing.
+
+| You want                       | Install                        | Import                                     |
+| ------------------------------ | ------------------------------ | ------------------------------------------ |
+| gateway, config, receipts, CLI | `@devlab.group/agent-commerce` | `from '@devlab.group/agent-commerce'`      |
+| expose resources as MCP tools  | `+ @modelcontextprotocol/sdk`  | `from '@devlab.group/agent-commerce/mcp'`  |
+| accept x402 payments           | `+ x402 viem`                  | `from '@devlab.group/agent-commerce/x402'` |
+
+```bash
+npm install @devlab.group/agent-commerce @modelcontextprotocol/sdk x402 viem
+```
+
+```ts
+import { mcp } from '@devlab.group/agent-commerce/mcp';
+import { x402 } from '@devlab.group/agent-commerce/x402';
+```
+
+Peers are pinned exactly: x402's
+schemas and EIP-712 domains cross this boundary, so a version skew is a
+correctness problem rather than a convenience one. Import a subpath without its
+peer installed and Node fails at load naming the missing package — deliberately,
+rather than starting a gateway that silently serves nothing.
+
+## Quickstart
+
+Requirements: **Node >= 22**, **npm 10**, **Docker**. Nothing else — no API
+keys, no real money, no manual blockchain setup.
+
+```bash
+git clone <repo> && cd agent-commerce
+npm install
+docker compose up
+```
+
+Then, in a second terminal:
+
+```bash
+npm run agent-commerce -- doctor --config config-demo.yaml # verify the whole stack
+npm run demo:agent # watch an agent buy something
+```
+
+<sub><b>Linux only</b>, and only if your user is not UID/GID 1000 (check with
+<code>id -u && id -g</code>): export <code>DOCKER_UID=$(id -u) DOCKER_GID=$(id -g)</code>
+before <code>docker compose up</code>. The chain-deploy step runs as that user so the
+deployment manifest it writes stays host-writable rather than root-owned. Docker
+Desktop on macOS and Windows translates permissions through its VM and does not
+need this.</sub>
+
+That is the whole thing. The stack is a private Anvil chain, a mock USDC token,
+a demo merchant API, the gateway and a dashboard — all local and disposable.
+
+To stop and wipe state: `docker compose down -v`.
+
+## How it works
+
+```text
+        ┌──────────────────────────────────────────────────────┐
+        │ AI Agent │
+        └──────────────┬───────────────────────────────────────┘
+                       │ MCP · HTTP + X-PAYMENT
+        ┌──────────────▼───────────────────────────────────────┐
+        │ Agent Commerce Gateway (yours) │
+        │ │
+        │ protocol adapters → ExecutionPipeline → … │
+        │ │ │
+        │ ┌─────────────────────┼──────────────┐ │
+        │ ▼ ▼ ▼ │
+        │ PaymentProvider BackendExecutor ReceiptStore │
+        │ (x402) (bounded HTTP) (SQLite) │
+        └────────┬─────────────────────┬───────────────────────┘
+                 │ │
+        buyer → merchant ┌──────▼───────────────┐
+        (never through us) │ Your backend API │
+                                └───────────────────────┘
+```
+
+Every protocol adapter converges on **one execution pipeline**. That is what
+makes payment enforcement a property of the system rather than something each
+adapter has to remember. Full detail in
+[docs/architecture.md](docs/architecture.md).
+
+## Configure a resource
+
+```yaml
+resources:
+  market_report:
+    name: Premium Market Report
+    backend:
+      type: http
+      method: GET
+      url: ${MERCHANT_API_BASE_URL}/api/report
+      timeoutMs: 10000
+    pricing:
+      type: fixed
+      amount: "0.01"
+      currency: USDC
+    expose: [http, mcp]
+    payments: [x402]
+```
+
+That is the integration. No SDK in your backend, no rewrite.
+
+```bash
+npm run agent-commerce -- init # generate a config interactively
+npm run agent-commerce -- validate # fails loudly, exits non-zero
+```
+
+See [docs/configuration.md](docs/configuration.md).
+
+## Protocol support
+
+| Protocol              | Status    | Pinned revision                    |
+| --------------------- | --------- | ---------------------------------- |
+| **MCP**               | Supported | `@modelcontextprotocol/sdk@1.30.0` |
+| **x402**              | Supported | `x402@1.2.0`, scheme `exact`, EVM  |
+| **HTTP**              | Supported | native routes                      |
+| UCP                   | Planned   | —                                  |
+| ACP · MPP · A2A · AP2 | Planned   | —                                  |
+
+"Planned" means **no code ships for it**. Each adapter reports its own
+`supportedSpec`, `capabilities` and `unsupported` list at runtime via
+`GET /.well-known/agent-commerce` and `agent-commerce doctor` — so the claim is
+checkable, not marketing. Detail: [docs/protocols.md](docs/protocols.md).
+
+## Payment model
+
+- **Non-custodial.** The gateway never holds funds, and never asks for a
+  merchant or buyer private key. `payTo` is your address.
+- **Fail closed.** Missing, malformed, expired, replayed, wrong-amount,
+  wrong-recipient, wrong-network and wrong-asset payments all fail — each with a
+  test.
+- **Replay-safe twice over.** EIP-3009 stops a double spend on-chain; the
+  gateway additionally reserves a `replayKey` derived from the authorisation
+  before it settles anything.
+- **Real settlement in CI.** The end-to-end test asserts the buyer's balance
+  falls and the merchant's rises by exactly the price, with a real transaction
+  hash in the receipt. A log line saying "payment successful" would not count.
+
+Detail: [docs/payment-flow.md](docs/payment-flow.md).
+
+## Diagnostics
+
+```console
+$ npm run agent-commerce -- doctor --config config-demo.yaml
+
+PASS Config valid — 2 resource(s), merchant "Demo Data Store"
+PASS Gateway healthy and ready at http://127.0.0.1:8080
+PASS Backend 2/2 backend host(s) reachable
+PASS Protocols http=on mcp=on (/mcp)
+PASS Payments x402 enabled — network=base-sepolia, destination=0x7099…79C8, facilitator=local
+INFO Payments (MPP) planned — not implemented in v0.1
+PASS Storage sqlite schema v1 writable; receipts=2
+PASS Protocol versions reported by gateway /.well-known/agent-commerce
+
+Score: 7/7 checks passed
+```
+
+That is real output, not an illustration. `doctor` also cross-checks the
+gateway's *live* settlement configuration against what your local config
+resolves to, and fails if they disagree — a diagnostic that passes while the
+system is misconfigured is worse than none.
+
+Exits non-zero if anything fails. `--json` for machines.
+
+## Exposure and access
+
+The demo binds everything to `127.0.0.1`. Before putting the gateway anywhere
+reachable by anyone else, know the split:
+
+- **Agent routes** (`/api/resources/:id/invoke`, `/mcp`) are unauthenticated by
+  design — paid resources are protected by payment, not by a password.
+- **Operator routes** (`/api/receipts`, `/api/events`, `/api/events/stream`) are
+  the merchant's commerce ledger: payer addresses, amounts, settlement hashes.
+  They require `server.adminToken`, and return **404** if none is configured.
+- **Browsers** are governed by `server.allowedOrigins`, an explicit allowlist
+  that defaults to empty.
+- **There is no rate limiting.** A free resource is an unauthenticated proxy to
+  your backend at whatever rate a caller chooses. Quotas and abuse controls
+  belong in your API or your edge.
+
+[SECURITY.md](SECURITY.md) states plainly what this does and does not protect.
+
+## Live settlement — not in this release
+
+**v0.1.0-alpha settles only against the local deterministic chain** (Anvil +
+MockUSDC). There is no live mode, no flag to enable one, and no partial path
+toward one: `facilitator.mode: "remote"` is rejected at config load, and the
+x402 provider's health check requires an Anvil-only RPC method, so `/ready`
+returns 503 against a real network. Settling real value is **planned**, not
+shipped — see [docs/payment-flow.md](docs/payment-flow.md).
+
+## Development
+
+```bash
+npm run verify # contract + lint + typecheck + test
+npm run test:e2e # deterministic end-to-end, boots its own chain
+```
+
+Foundry (`anvil`, `forge`, `cast`) is needed for the chain work.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Roadmap
+
+**Now (v0.1.0-alpha)** — MCP, x402, receipts, doctor, deterministic demo.
+
+**Next** — OpenAPI import · a stronger conformance suite · a `doctor` GitHub
+Action · UCP · MPP · ACP · A2A · AP2 · Shopify and WooCommerce examples ·
+PostgreSQL · richer observability.
+
+New protocols land only after the adapter model survives real use. Scope
+discipline is a release requirement, not a mood.
+
+## Documentation
+
+|                                                |                                             |
+| ---------------------------------------------- | ------------------------------------------- |
+| [Architecture](docs/architecture.md)           | how the pieces fit                          |
+| [Payment flow](docs/payment-flow.md)           | the paid round trip, and every way it fails |
+| [Protocols](docs/protocols.md)                 | exactly what is and is not supported        |
+| [Configuration](docs/configuration.md)         | `config.yaml` reference                     |
+| [Security model](docs/security.md)             | trust boundaries, and what we do not defend |
+| [Contracts](docs/contracts.md)                 | the frozen cross-package contract           |
+| [Adapter guide](docs/contributing-adapters.md) | add a protocol or a payment rail            |
+
+## Licence
+
+[Apache-2.0](LICENSE).

package/dist/chunk-CZ6ZDAYD.js

@@ -0,0 +1,192 @@
+import 'module';
+
+// src/core/domain/event.ts
+var COMMERCE_EVENT_TYPES = [
+  "resource.discovered",
+  "resource.requested",
+  "payment.required",
+  "payment.rejected",
+  "payment.verified",
+  "payment.settled",
+  "backend.called",
+  "backend.failed",
+  "resource.delivered"
+];
+
+// src/core/domain/resource.ts
+var DEFAULT_BACKEND_TIMEOUT_MS = 1e4;
+
+// src/core/domain/wire.ts
+var PAYMENT_INPUT_FIELD = "_payment";
+var PAYMENT_HEADER = "x-payment";
+var PAYMENT_RESPONSE_HEADER = "x-payment-response";
+var DELIVERY_SUMMARY_META_KEY = "agent-commerce/delivery";
+function toDeliverySummary(outcome) {
+  const p = outcome.payment;
+  return {
+    requestId: outcome.requestId,
+    resourceId: outcome.resourceId,
+    receiptId: outcome.receipt.id,
+    deliveredAt: outcome.receipt.deliveredAt,
+    ...p !== void 0 ? {
+      payment: {
+        status: p.status,
+        amount: p.amount,
+        currency: p.currency,
+        ...p.externalReference !== void 0 ? { externalReference: p.externalReference } : {},
+        ...p.network !== void 0 ? { network: p.network } : {}
+      }
+    } : {}
+  };
+}
+function toPaymentRequiredEnvelope(outcome) {
+  const r = outcome.requirement;
+  return {
+    status: "payment-required",
+    code: "PAYMENT_REQUIRED",
+    requestId: outcome.requestId,
+    resourceId: outcome.resourceId,
+    message: `Payment of ${r.amount} ${r.currency} is required for resource "${outcome.resourceId}". Retry with a ${r.provider} payment proof.`,
+    payment: {
+      provider: r.provider,
+      version: r.challenge.version,
+      amount: r.amount,
+      currency: r.currency,
+      destination: r.destination,
+      ...r.network !== void 0 ? { network: r.network } : {},
+      ...r.asset !== void 0 ? { asset: r.asset } : {},
+      ...r.expiresAt !== void 0 ? { expiresAt: r.expiresAt } : {},
+      accepts: r.challenge.accepts
+    }
+  };
+}
+function toErrorEnvelope(error) {
+  const info = error.toInfo();
+  return {
+    status: "error",
+    code: info.code,
+    message: info.message,
+    retryable: info.retryable,
+    ...info.requestId !== void 0 ? { requestId: info.requestId } : {},
+    ...info.resourceId !== void 0 ? { resourceId: info.resourceId } : {},
+    ...info.details !== void 0 ? { details: info.details } : {}
+  };
+}
+function isPaymentRequiredEnvelope(value) {
+  return typeof value === "object" && value !== null && value.status === "payment-required" && typeof value.payment === "object";
+}
+
+// src/core/errors/codes.ts
+var COMMERCE_ERROR_CODES = [
+  "CONFIG_INVALID",
+  "RESOURCE_NOT_FOUND",
+  "INPUT_INVALID",
+  "PAYMENT_REQUIRED",
+  "PAYMENT_INVALID",
+  "PAYMENT_REPLAYED",
+  "PAYMENT_PROVIDER_UNAVAILABLE",
+  "PAYMENT_SETTLEMENT_FAILED",
+  "BACKEND_TIMEOUT",
+  "BACKEND_ERROR",
+  "PROTOCOL_UNSUPPORTED",
+  "GATEWAY_BUSY",
+  "STORAGE_ERROR",
+  "INTERNAL_ERROR"
+];
+var COMMERCE_ERROR_HTTP_STATUS = {
+  CONFIG_INVALID: 500,
+  RESOURCE_NOT_FOUND: 404,
+  INPUT_INVALID: 400,
+  PAYMENT_REQUIRED: 402,
+  PAYMENT_INVALID: 402,
+  PAYMENT_REPLAYED: 409,
+  PAYMENT_PROVIDER_UNAVAILABLE: 503,
+  PAYMENT_SETTLEMENT_FAILED: 502,
+  BACKEND_TIMEOUT: 504,
+  BACKEND_ERROR: 502,
+  PROTOCOL_UNSUPPORTED: 501,
+  GATEWAY_BUSY: 503,
+  STORAGE_ERROR: 500,
+  INTERNAL_ERROR: 500
+};
+var RETRYABLE_ERROR_CODES = /* @__PURE__ */ new Set([
+  "PAYMENT_PROVIDER_UNAVAILABLE",
+  "BACKEND_TIMEOUT",
+  // Load shedding is transient by definition: the caller should back off and
+  // try again. Before this code existed the MCP adapter's queue-full path threw
+  // PROTOCOL_UNSUPPORTED — HTTP 501, retryable:false — so an agent framework
+  // keyed on the machine-readable flag (which exists precisely so clients need
+  // not parse prose) would read a momentary throttle as a permanent capability
+  // gap and stop calling the tool.
+  "GATEWAY_BUSY"
+]);
+
+// src/core/errors/commerce-error.ts
+var CommerceError = class _CommerceError extends Error {
+  code;
+  httpStatus;
+  retryable;
+  details;
+  requestId;
+  resourceId;
+  constructor(code, message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "CommerceError";
+    this.code = code;
+    this.httpStatus = options.httpStatus ?? COMMERCE_ERROR_HTTP_STATUS[code];
+    this.retryable = RETRYABLE_ERROR_CODES.has(code);
+    if (options.details !== void 0) this.details = options.details;
+    if (options.requestId !== void 0) this.requestId = options.requestId;
+    if (options.resourceId !== void 0) this.resourceId = options.resourceId;
+    Error.captureStackTrace?.(this, _CommerceError);
+  }
+  /** Non-secret, client-safe representation. */
+  toInfo() {
+    return {
+      code: this.code,
+      message: this.message,
+      httpStatus: this.httpStatus,
+      retryable: this.retryable,
+      ...this.requestId !== void 0 ? { requestId: this.requestId } : {},
+      ...this.resourceId !== void 0 ? { resourceId: this.resourceId } : {},
+      ...this.details !== void 0 ? { details: this.details } : {}
+    };
+  }
+};
+function isCommerceError(value) {
+  return value instanceof CommerceError;
+}
+function toCommerceError(value, fallbackCode = "INTERNAL_ERROR", fallbackMessage = "Unexpected internal error") {
+  if (isCommerceError(value)) return value;
+  return new CommerceError(fallbackCode, fallbackMessage, { cause: value });
+}
+
+// src/core/interfaces/logger.ts
+var NOOP_LOGGER = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  },
+  child: () => NOOP_LOGGER
+};
+
+// src/core/interfaces/protocol-adapter.ts
+function isHttpProtocolAdapter(adapter) {
+  return typeof adapter.handleHttp === "function";
+}
+
+// src/core/interfaces/runtime.ts
+var systemClock = {
+  now: () => /* @__PURE__ */ new Date(),
+  nowIso: () => (/* @__PURE__ */ new Date()).toISOString(),
+  monotonicMs: () => performance.now()
+};
+var PACKAGE_VERSION = "0.1.0-alpha.0" ;
+
+export { COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, NOOP_LOGGER, PACKAGE_VERSION, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_RESPONSE_HEADER, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };
+//# sourceMappingURL=chunk-CZ6ZDAYD.js.map
+//# sourceMappingURL=chunk-CZ6ZDAYD.js.map

package/dist/chunk-CZ6ZDAYD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/domain/event.ts","../src/core/domain/resource.ts","../src/core/domain/wire.ts","../src/core/errors/codes.ts","../src/core/errors/commerce-error.ts","../src/core/interfaces/logger.ts","../src/core/interfaces/protocol-adapter.ts","../src/core/interfaces/runtime.ts","../src/version.ts"],"names":[],"mappings":"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","file":"chunk-CZ6ZDAYD.js","sourcesContent":["/**\n * Canonical commerce events.\n *\n * FROZEN CONTRACT. Every event in a single flow shares one `requestId` so that\n * logs, payment attempts, backend calls and receipts are correlatable\n *.\n */\nimport type { IsoTimestamp } from './common.js';\n\nexport const COMMERCE_EVENT_TYPES = [\n  'resource.discovered',\n  'resource.requested',\n  'payment.required',\n  'payment.rejected',\n  'payment.verified',\n  'payment.settled',\n  'backend.called',\n  'backend.failed',\n  'resource.delivered',\n] as const;\n\nexport type CommerceEventType = (typeof COMMERCE_EVENT_TYPES)[number];\n\nexport interface CommerceEvent {\n  readonly id: string;\n  readonly type: CommerceEventType;\n  readonly requestId: string;\n  readonly resourceId?: string;\n  readonly at: IsoTimestamp;\n  /** Protocol adapter that originated the request, e.g. 'mcp' or 'http'. */\n  readonly adapter?: string;\n  readonly paymentProvider?: string;\n  readonly durationMs?: number;\n  readonly status?: 'ok' | 'error';\n  /** Non-secret, structured detail. Must never contain keys, headers or proofs. */\n  readonly data?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Sink for canonical events.\n *\n * Implementations must be non-throwing from the caller's perspective: an event\n * sink failure must never fail an otherwise successful commerce flow.\n */\nexport interface EventSink {\n  emit(event: CommerceEvent): Promise<void>;\n}\n","/**\n * Canonical resource model.\n *\n * FROZEN CONTRACT.\n */\nimport type { DecimalAmount, JsonSchema, PaymentMethodName, ProtocolName } from './common.js';\n\n/** HTTP methods a backend handler may use. */\nexport type BackendMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n\n/**\n * Describes how the gateway calls the merchant's existing backend.\n *\n * Backend URLs are administrator-controlled configuration only. User- or\n * agent-controlled backend URLs are forbidden (see docs/security.md, SSRF).\n * Secret header values must come from `${ENV_VAR}` placeholders resolved by\n * the config loader, never from plaintext configuration.\n */\nexport interface BackendHandler {\n  readonly type: 'http';\n  readonly method: BackendMethod;\n  readonly url: string;\n  readonly headers?: Readonly<Record<string, string>>;\n  /** Hard upper bound on the backend call. Defaults to DEFAULT_BACKEND_TIMEOUT_MS. */\n  readonly timeoutMs?: number;\n}\n\n/** Default backend timeout when a resource does not specify one. */\nexport const DEFAULT_BACKEND_TIMEOUT_MS = 10_000;\n\n/**\n * Canonical pricing.\n *\n * `dynamic` exists in the type system for forward compatibility but is\n * REJECTED by config validation in v0.1.0-alpha.\n */\nexport type Pricing =\n  | { readonly type: 'free' }\n  | {\n      readonly type: 'fixed';\n      readonly amount: DecimalAmount;\n      readonly currency: string;\n    }\n  | {\n      readonly type: 'dynamic';\n      readonly resolver: string;\n    };\n\n/**\n * A merchant capability exposed to agents.\n *\n * The canonical resource is the single source of truth: protocol adapters map\n * it outward, they never define their own parallel notion of a resource.\n */\nexport interface CommerceResource {\n  readonly id: string;\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: JsonSchema;\n  readonly outputSchema?: JsonSchema;\n  readonly handler: BackendHandler;\n  readonly pricing: Pricing;\n  readonly exposedVia: readonly ProtocolName[];\n  readonly paymentMethods: readonly PaymentMethodName[];\n}\n\n/** Read-only view of every configured resource. */\nexport interface ResourceRegistry {\n  get(id: string): CommerceResource | undefined;\n  list(): readonly CommerceResource[];\n  /** Resources exposed through a given protocol surface. */\n  listExposedVia(protocol: ProtocolName): readonly CommerceResource[];\n  has(id: string): boolean;\n}\n","/**\n * Gateway-defined wire envelopes.\n *\n * FROZEN CONTRACT. These are the *only* representations of \"payment required\"\n * and \"error\" that leave the gateway, whichever protocol carries them. The HTTP\n * routes, the MCP adapter and the demo buyer agent all use these helpers so the\n * three can never drift apart.\n */\n\nimport type { CommerceError, CommerceErrorCode } from '../errors/index.js';\nimport type { DecimalAmount, IsoTimestamp, PaymentMethodName } from './common.js';\nimport type { DeliveredOutcome, PaymentRequiredOutcome } from './request.js';\n\n/**\n * Reserved input property carrying a payment proof on protocols that have no\n * header channel (MCP tool calls). Over HTTP the `X-PAYMENT` header is used.\n */\nexport const PAYMENT_INPUT_FIELD = '_payment';\n\n/** HTTP header carrying the payment proof. */\nexport const PAYMENT_HEADER = 'x-payment';\n\n/** HTTP response header carrying the settlement reference. */\nexport const PAYMENT_RESPONSE_HEADER = 'x-payment-response';\n\n/**\n * Key under which a protocol adapter attaches a {@link DeliverySummary} to its\n * result metadata — MCP's `CallToolResult._meta`, and anywhere else a protocol\n * offers an out-of-band metadata channel.\n *\n * Frozen deliberately. The bug this whole mechanism exists to fix was two\n * surfaces disagreeing about what a payer gets back; a key name enforced only\n * by one side's tests would reintroduce exactly that drift. Producer and\n * consumer both import this constant.\n *\n * Follows MCP's `<namespace>/<name>` convention for `_meta` keys.\n */\nexport const DELIVERY_SUMMARY_META_KEY = 'agent-commerce/delivery';\n\nexport interface PaymentRequiredEnvelope {\n  readonly status: 'payment-required';\n  readonly code: 'PAYMENT_REQUIRED';\n  readonly requestId: string;\n  readonly resourceId: string;\n  readonly message: string;\n  readonly payment: {\n    readonly provider: PaymentMethodName;\n    readonly version: string;\n    readonly amount: DecimalAmount;\n    readonly currency: string;\n    readonly destination: string;\n    readonly network?: string;\n    readonly asset?: string;\n    readonly expiresAt?: IsoTimestamp;\n    /** Provider-native requirement objects, passed through verbatim. */\n    readonly accepts: readonly Readonly<Record<string, unknown>>[];\n  };\n}\n\nexport interface ErrorEnvelope {\n  readonly status: 'error';\n  readonly code: CommerceErrorCode;\n  readonly message: string;\n  readonly retryable: boolean;\n  readonly requestId?: string;\n  readonly resourceId?: string;\n  readonly details?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * What a buyer learns about their own completed purchase.\n *\n * A payer is entitled to the record of their own transaction — the request it\n * belonged to, whether it settled, and the settlement reference they can check\n * on-chain. They are NOT entitled to the merchant's ledger, which is why\n * `/api/receipts` is an operator route behind `server.adminToken`.\n *\n * Before this existed the two surfaces disagreed: HTTP callers received a\n * settlement summary in `X-PAYMENT-RESPONSE` while MCP callers received\n * nothing, so an MCP buyer's only route to their own receipt was the merchant's\n * ledger. Both surfaces now emit this same shape.\n */\nexport interface DeliverySummary {\n  readonly requestId: string;\n  readonly resourceId: string;\n  readonly receiptId: string;\n  readonly deliveredAt: IsoTimestamp;\n  readonly payment?: {\n    readonly status: 'verified' | 'settled' | 'rejected';\n    readonly amount: DecimalAmount;\n    readonly currency: string;\n    /** Settlement reference, e.g. an on-chain transaction hash. */\n    readonly externalReference?: string;\n    readonly network?: string;\n  };\n}\n\n/** Build the payer-facing summary of a delivered outcome. */\nexport function toDeliverySummary(outcome: DeliveredOutcome): DeliverySummary {\n  const p = outcome.payment;\n  return {\n    requestId: outcome.requestId,\n    resourceId: outcome.resourceId,\n    receiptId: outcome.receipt.id,\n    deliveredAt: outcome.receipt.deliveredAt,\n    ...(p !== undefined\n      ? {\n          payment: {\n            status: p.status,\n            amount: p.amount,\n            currency: p.currency,\n            ...(p.externalReference !== undefined\n              ? { externalReference: p.externalReference }\n              : {}),\n            ...(p.network !== undefined ? { network: p.network } : {}),\n          },\n        }\n      : {}),\n  };\n}\n\nexport function toPaymentRequiredEnvelope(\n  outcome: PaymentRequiredOutcome,\n): PaymentRequiredEnvelope {\n  const r = outcome.requirement;\n  return {\n    status: 'payment-required',\n    code: 'PAYMENT_REQUIRED',\n    requestId: outcome.requestId,\n    resourceId: outcome.resourceId,\n    message: `Payment of ${r.amount} ${r.currency} is required for resource \"${outcome.resourceId}\". Retry with a ${r.provider} payment proof.`,\n    payment: {\n      provider: r.provider,\n      version: r.challenge.version,\n      amount: r.amount,\n      currency: r.currency,\n      destination: r.destination,\n      ...(r.network !== undefined ? { network: r.network } : {}),\n      ...(r.asset !== undefined ? { asset: r.asset } : {}),\n      ...(r.expiresAt !== undefined ? { expiresAt: r.expiresAt } : {}),\n      accepts: r.challenge.accepts,\n    },\n  };\n}\n\nexport function toErrorEnvelope(error: CommerceError): ErrorEnvelope {\n  const info = error.toInfo();\n  return {\n    status: 'error',\n    code: info.code,\n    message: info.message,\n    retryable: info.retryable,\n    ...(info.requestId !== undefined ? { requestId: info.requestId } : {}),\n    ...(info.resourceId !== undefined ? { resourceId: info.resourceId } : {}),\n    ...(info.details !== undefined ? { details: info.details } : {}),\n  };\n}\n\nexport function isPaymentRequiredEnvelope(value: unknown): value is PaymentRequiredEnvelope {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as PaymentRequiredEnvelope).status === 'payment-required' &&\n    typeof (value as PaymentRequiredEnvelope).payment === 'object'\n  );\n}\n","/**\n * Typed domain error codes.\n *\n * FROZEN CONTRACT. Protocol adapters map these codes into their own response\n * format. Never throw a bare string or untyped Error across a package boundary.\n */\nexport const COMMERCE_ERROR_CODES = [\n  'CONFIG_INVALID',\n  'RESOURCE_NOT_FOUND',\n  'INPUT_INVALID',\n  'PAYMENT_REQUIRED',\n  'PAYMENT_INVALID',\n  'PAYMENT_REPLAYED',\n  'PAYMENT_PROVIDER_UNAVAILABLE',\n  'PAYMENT_SETTLEMENT_FAILED',\n  'BACKEND_TIMEOUT',\n  'BACKEND_ERROR',\n  'PROTOCOL_UNSUPPORTED',\n  'GATEWAY_BUSY',\n  'STORAGE_ERROR',\n  'INTERNAL_ERROR',\n] as const;\n\nexport type CommerceErrorCode = (typeof COMMERCE_ERROR_CODES)[number];\n\n/**\n * Canonical HTTP status for each error code.\n *\n * Paid resources fail closed: every payment failure maps to a 4xx/5xx status\n * and never to a successful delivery.\n */\nexport const COMMERCE_ERROR_HTTP_STATUS: Readonly<Record<CommerceErrorCode, number>> = {\n  CONFIG_INVALID: 500,\n  RESOURCE_NOT_FOUND: 404,\n  INPUT_INVALID: 400,\n  PAYMENT_REQUIRED: 402,\n  PAYMENT_INVALID: 402,\n  PAYMENT_REPLAYED: 409,\n  PAYMENT_PROVIDER_UNAVAILABLE: 503,\n  PAYMENT_SETTLEMENT_FAILED: 502,\n  BACKEND_TIMEOUT: 504,\n  BACKEND_ERROR: 502,\n  PROTOCOL_UNSUPPORTED: 501,\n  GATEWAY_BUSY: 503,\n  STORAGE_ERROR: 500,\n  INTERNAL_ERROR: 500,\n};\n\n/** Codes for which a client may reasonably retry the same request. */\nexport const RETRYABLE_ERROR_CODES: ReadonlySet<CommerceErrorCode> = new Set([\n  'PAYMENT_PROVIDER_UNAVAILABLE',\n  'BACKEND_TIMEOUT',\n  // Load shedding is transient by definition: the caller should back off and\n  // try again. Before this code existed the MCP adapter's queue-full path threw\n  // PROTOCOL_UNSUPPORTED — HTTP 501, retryable:false — so an agent framework\n  // keyed on the machine-readable flag (which exists precisely so clients need\n  // not parse prose) would read a momentary throttle as a permanent capability\n  // gap and stop calling the tool.\n  'GATEWAY_BUSY',\n]);\n","/**\n * The single error type crossing package boundaries.\n *\n * FROZEN CONTRACT.\n */\nimport {\n  COMMERCE_ERROR_HTTP_STATUS,\n  type CommerceErrorCode,\n  RETRYABLE_ERROR_CODES,\n} from './codes.js';\n\nexport interface CommerceErrorOptions {\n  /** Structured, non-secret detail safe to return to a client. */\n  readonly details?: Readonly<Record<string, unknown>>;\n  readonly cause?: unknown;\n  readonly requestId?: string;\n  readonly resourceId?: string;\n  /** Override the default HTTP status for this code. */\n  readonly httpStatus?: number;\n}\n\n/** Serialisable wire form of a CommerceError. */\nexport interface CommerceErrorInfo {\n  readonly code: CommerceErrorCode;\n  readonly message: string;\n  readonly httpStatus: number;\n  readonly retryable: boolean;\n  readonly requestId?: string;\n  readonly resourceId?: string;\n  readonly details?: Readonly<Record<string, unknown>>;\n}\n\nexport class CommerceError extends Error {\n  readonly code: CommerceErrorCode;\n  readonly httpStatus: number;\n  readonly retryable: boolean;\n  readonly details?: Readonly<Record<string, unknown>>;\n  readonly requestId?: string;\n  readonly resourceId?: string;\n\n  constructor(code: CommerceErrorCode, message: string, options: CommerceErrorOptions = {}) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.name = 'CommerceError';\n    this.code = code;\n    this.httpStatus = options.httpStatus ?? COMMERCE_ERROR_HTTP_STATUS[code];\n    this.retryable = RETRYABLE_ERROR_CODES.has(code);\n    if (options.details !== undefined) this.details = options.details;\n    if (options.requestId !== undefined) this.requestId = options.requestId;\n    if (options.resourceId !== undefined) this.resourceId = options.resourceId;\n    Error.captureStackTrace?.(this, CommerceError);\n  }\n\n  /** Non-secret, client-safe representation. */\n  toInfo(): CommerceErrorInfo {\n    return {\n      code: this.code,\n      message: this.message,\n      httpStatus: this.httpStatus,\n      retryable: this.retryable,\n      ...(this.requestId !== undefined ? { requestId: this.requestId } : {}),\n      ...(this.resourceId !== undefined ? { resourceId: this.resourceId } : {}),\n      ...(this.details !== undefined ? { details: this.details } : {}),\n    };\n  }\n}\n\nexport function isCommerceError(value: unknown): value is CommerceError {\n  return value instanceof CommerceError;\n}\n\n/**\n * Normalise any thrown value into a CommerceError.\n *\n * Used at package boundaries so an unexpected failure never escapes untyped.\n *\n * SECURITY — do not \"improve\" this by propagating `value.message`.\n * `CommerceError.message` is client-visible: it is serialised by `toInfo()`\n * and `toErrorEnvelope()` and returned over HTTP and MCP. An arbitrary thrown\n * Error's message routinely carries internal detail — database connection\n * strings, internal hostnames, filesystem paths, backend URLs. Copying it into\n * a client-facing field turns every unexpected exception into an information\n * disclosure.\n *\n * The original value is preserved on `cause`, which is never serialised, so\n * logs and diagnostics keep the full detail while clients get only the\n * caller's deliberate, reviewed `fallbackMessage`.\n *\n * A caller that *wants* a specific client-facing message passes one:\n * toCommerceError(err, 'BACKEND_ERROR', 'Backend call failed')\n */\nexport function toCommerceError(\n  value: unknown,\n  fallbackCode: CommerceErrorCode = 'INTERNAL_ERROR',\n  fallbackMessage = 'Unexpected internal error',\n): CommerceError {\n  if (isCommerceError(value)) return value;\n  return new CommerceError(fallbackCode, fallbackMessage, { cause: value });\n}\n","/**\n * Minimal structural logger interface.\n *\n * Core must not depend on pino directly; the gateway injects a pino instance\n * that satisfies this shape. Never log secrets: private keys, seed phrases,\n * Authorization headers or payment authorisation payloads.\n */\nexport interface Logger {\n  debug(obj: Record<string, unknown>, msg?: string): void;\n  info(obj: Record<string, unknown>, msg?: string): void;\n  warn(obj: Record<string, unknown>, msg?: string): void;\n  error(obj: Record<string, unknown>, msg?: string): void;\n  child(bindings: Record<string, unknown>): Logger;\n}\n\n/** A logger that discards everything. Useful in unit tests. */\nexport const NOOP_LOGGER: Logger = {\n  debug: () => {},\n  info: () => {},\n  warn: () => {},\n  error: () => {},\n  child: () => NOOP_LOGGER,\n};\n","/**\n * Protocol adapter boundary.\n *\n * FROZEN CONTRACT. An adapter translates a protocol's wire format into a\n * `CanonicalRequest`, hands it to the execution pipeline and maps the outcome\n * back. It must not call merchant backends, implement payment logic, or hold\n * its own copy of the canonical model.\n *\n * Adapter isolation: a failure while starting or serving one adapter must not\n * prevent the others from operating.\n */\nimport type { IncomingMessage, ServerResponse } from 'node:http';\nimport type { AdapterDescriptor, AdapterHealth, ProtocolName } from '../domain/common.js';\nimport type { EventSink } from '../domain/event.js';\nimport type { ExecutionPipeline } from '../domain/request.js';\nimport type { ResourceRegistry } from '../domain/resource.js';\nimport type { Logger } from './logger.js';\nimport type { Clock, IdGenerator } from './runtime.js';\n\n/** Everything an adapter is given. Nothing else is available to it. */\nexport interface ProtocolAdapterContext {\n  readonly pipeline: ExecutionPipeline;\n  readonly resources: ResourceRegistry;\n  readonly events: EventSink;\n  readonly logger: Logger;\n  readonly clock: Clock;\n  readonly ids: IdGenerator;\n  /** Externally reachable base URL of the gateway, from config. */\n  readonly publicBaseUrl: string;\n}\n\nexport interface ProtocolAdapter {\n  readonly name: ProtocolName;\n  readonly descriptor: AdapterDescriptor;\n\n  start(context: ProtocolAdapterContext): Promise<void>;\n  health(): Promise<AdapterHealth>;\n  stop(): Promise<void>;\n}\n\n/**\n * A protocol adapter served over HTTP.\n *\n * The gateway mounts `handleHttp` at `mountPath` using raw Node request and\n * response objects, so adapters stay independent of the HTTP framework.\n *\n * GUARANTEE — the request body is **unconsumed**.\n *\n * `req` is handed over with its stream unread: the gateway suppresses every\n * body parser on this mount, so an adapter whose SDK reads the body itself\n * (MCP's Streamable HTTP transport does) can do so. The adapter owns reading,\n * size-limiting beyond the gateway's own cap, and parsing.\n *\n * This is load-bearing and easy to break silently. Fastify pre-registers\n * exact-match parsers for `application/json` and `text/plain` and prefers them\n * over a `'*'` wildcard, so registering only a wildcard no-op leaves the\n * built-in JSON parser draining the body first — the adapter then reads an\n * empty stream and every request fails to parse. That exact regression shipped\n * once and no unit test caught it, because adapter conformance suites drive\n * `handleHttp` over a bare `node:http` server and never traverse the gateway.\n *\n * Any change to how adapters are mounted must be covered by a test that POSTs\n * a real JSON body through the real gateway and asserts the adapter received\n * it intact.\n */\nexport interface HttpProtocolAdapter extends ProtocolAdapter {\n  /** Path prefix the gateway mounts this adapter at, e.g. '/mcp'. */\n  readonly mountPath: string;\n  handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void>;\n}\n\nexport function isHttpProtocolAdapter(adapter: ProtocolAdapter): adapter is HttpProtocolAdapter {\n  return typeof (adapter as HttpProtocolAdapter).handleHttp === 'function';\n}\n","/**\n * Injected runtime primitives.\n *\n * Everything non-deterministic (time, ids) is injected so tests can be exact.\n */\nimport type { IsoTimestamp } from '../domain/common.js';\n\nexport interface Clock {\n  now(): Date;\n  nowIso(): IsoTimestamp;\n  /** Milliseconds since an arbitrary origin; use for durations only. */\n  monotonicMs(): number;\n}\n\nexport interface IdGenerator {\n  /** Opaque, collision-resistant identifier. */\n  next(prefix?: string): string;\n}\n\nexport const systemClock: Clock = {\n  now: () => new Date(),\n  nowIso: () => new Date().toISOString(),\n  monotonicMs: () => performance.now(),\n};\n","/**\n * The package version, resolved once for the whole package.\n *\n * Two paths, deliberately:\n *\n * - **Development** reads the root manifest, so the number is always live.\n * - **The published bundle cannot.** tsup collapses `src/**` into\n * `dist/index.js` and `dist/cli/index.js`, so any `require('../../package.json')`\n * written against a source path resolves from the wrong depth once bundled —\n * which is exactly how this broke during the single-package refactor, and how\n * it earlier produced a CLI reporting `v0.0.0-unknown`. The build injects\n * `__OAC_PACKAGE_VERSION__` instead (see tsup.config.ts).\n *\n * `typeof` on an undeclared identifier is safe in JS, so the dev path is\n * unaffected by the constant not existing.\n */\nimport { createRequire } from 'node:module';\n\ndeclare const __OAC_PACKAGE_VERSION__: string | undefined;\n\nfunction readFromManifest(): string {\n  try {\n    const require = createRequire(import.meta.url);\n    // src/version.ts -> repository root\n    return (require('../package.json') as { version?: string }).version ?? '0.0.0-unknown';\n  } catch {\n    return '0.0.0-unknown';\n  }\n}\n\nexport const PACKAGE_VERSION: string =\n  typeof __OAC_PACKAGE_VERSION__ === 'string' ? __OAC_PACKAGE_VERSION__ : readFromManifest();\n"]}