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

package/dist/protocol-adapter-C0goMgLK.d.ts

@@ -0,0 +1,223 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { I as IsoTimestamp, j as PaymentResult, o as ProtocolName, l as PaymentSubmission, i as PaymentRequirement, A as AdapterDescriptor, R as ResourceRegistry, L as Logger, c as Clock, d as IdGenerator, a as AdapterHealth } from './runtime-LCk2TzGN.js';
+
+/**
+ * Canonical commerce events.
+ *
+ * FROZEN CONTRACT. Every event in a single flow shares one `requestId` so that
+ * logs, payment attempts, backend calls and receipts are correlatable
+ *.
+ */
+
+declare const COMMERCE_EVENT_TYPES: readonly ["resource.discovered", "resource.requested", "payment.required", "payment.rejected", "payment.verified", "payment.settled", "backend.called", "backend.failed", "resource.delivered"];
+type CommerceEventType = (typeof COMMERCE_EVENT_TYPES)[number];
+interface CommerceEvent {
+    readonly id: string;
+    readonly type: CommerceEventType;
+    readonly requestId: string;
+    readonly resourceId?: string;
+    readonly at: IsoTimestamp;
+    /** Protocol adapter that originated the request, e.g. 'mcp' or 'http'. */
+    readonly adapter?: string;
+    readonly paymentProvider?: string;
+    readonly durationMs?: number;
+    readonly status?: 'ok' | 'error';
+    /** Non-secret, structured detail. Must never contain keys, headers or proofs. */
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Sink for canonical events.
+ *
+ * Implementations must be non-throwing from the caller's perspective: an event
+ * sink failure must never fail an otherwise successful commerce flow.
+ */
+interface EventSink {
+    emit(event: CommerceEvent): Promise<void>;
+}
+
+/**
+ * Canonical receipt model.
+ *
+ * FROZEN CONTRACT.
+ */
+
+interface CommerceReceipt {
+    readonly id: string;
+    readonly requestId: string;
+    readonly resourceId: string;
+    /** Absent for free resources. */
+    readonly payment?: PaymentResult;
+    readonly deliveredAt: IsoTimestamp;
+    readonly backendStatus: number;
+    readonly durationMs?: number;
+    readonly protocol?: string;
+    /** Non-secret summary only. Never the full backend body if it is sensitive. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Record of a single payment authorisation seen by the gateway. */
+interface PaymentAttempt {
+    readonly id: string;
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly provider: string;
+    /** See PaymentResult.replayKey — unique across the store. */
+    readonly replayKey: string;
+    /**
+     * Terminal state of the authorisation.
+     *
+     * `settlement-uncertain` is deliberately distinct from `failed`: it means the
+     * settlement transaction was broadcast but its outcome could not be
+     * confirmed (RPC timeout, dropped connection). "The RPC did not answer" and
+     * "the transfer did not happen" are different facts, and recording the first
+     * as the second makes the merchant's reconciliation artefact wrong in exactly
+     * the case where reconciliation matters. When this status is set,
+     * `externalReference` carries the broadcast transaction hash so the outcome
+     * can be resolved later.
+     */
+    readonly status: 'reserved' | 'verified' | 'settled' | 'rejected' | 'failed' | 'settlement-uncertain';
+    readonly amount: string;
+    readonly currency: string;
+    readonly payer?: string;
+    readonly payee?: string;
+    readonly externalReference?: string;
+    readonly rejectionReason?: string;
+    readonly createdAt: IsoTimestamp;
+    readonly updatedAt: IsoTimestamp;
+}
+
+/**
+ * Canonical request/response model for the execution pipeline.
+ *
+ * FROZEN CONTRACT. Protocol adapters normalise into `CanonicalRequest` and map
+ * `ExecutionOutcome` (or a thrown `CommerceError`) back into their own wire
+ * format. Adapters must never call merchant backends directly.
+ */
+
+interface CanonicalRequest {
+    /** Correlation id for the entire flow. Generated by the protocol adapter. */
+    readonly requestId: string;
+    readonly resourceId: string;
+    /** Raw, unvalidated resource input. Validated against the resource schema. */
+    readonly input: unknown;
+    readonly protocol: ProtocolName;
+    /** Payment proof, when the client is retrying after a challenge. */
+    readonly payment?: PaymentSubmission;
+    readonly receivedAt: IsoTimestamp;
+    /** Non-secret transport metadata (client id, user agent, …). */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Successful delivery of a resource. */
+interface DeliveredOutcome {
+    readonly kind: 'delivered';
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly backendStatus: number;
+    readonly body: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly payment?: PaymentResult;
+    readonly receipt: CommerceReceipt;
+    readonly durationMs: number;
+}
+/** The resource costs money and no acceptable proof was supplied. */
+interface PaymentRequiredOutcome {
+    readonly kind: 'payment-required';
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly requirement: PaymentRequirement;
+}
+/**
+ * Result of a pipeline execution.
+ *
+ * Every other condition (unknown resource, invalid input, rejected payment,
+ * backend failure, storage failure) is signalled by throwing a `CommerceError`.
+ */
+type ExecutionOutcome = DeliveredOutcome | PaymentRequiredOutcome;
+/**
+ * The single execution path every protocol adapter converges on.
+ *
+ * NOTE — two different signalling styles, deliberately:
+ *
+ * - `payment-required` is a normal RETURN VALUE (`PaymentRequiredOutcome`).
+ * It is an expected step in the protocol, not a failure: the caller is
+ * meant to read the challenge and retry with a proof.
+ * - Everything else that goes wrong — including a *rejected* payment — is a
+ * THROWN `CommerceError`.
+ *
+ * So `payment-required` and `payment-invalid` arrive through different
+ * channels despite sounding symmetrical. Adapters must handle both:
+ *
+ * try {
+ * const outcome = await pipeline.execute(request);
+ * if (outcome.kind === 'payment-required') return toPaymentRequiredEnvelope(outcome);
+ * return renderDelivered(outcome);
+ * } catch (error) {
+ * return toErrorEnvelope(toCommerceError(error));
+ * }
+ */
+interface ExecutionPipeline {
+    execute(request: CanonicalRequest): Promise<ExecutionOutcome>;
+}
+
+/**
+ * Protocol adapter boundary.
+ *
+ * FROZEN CONTRACT. An adapter translates a protocol's wire format into a
+ * `CanonicalRequest`, hands it to the execution pipeline and maps the outcome
+ * back. It must not call merchant backends, implement payment logic, or hold
+ * its own copy of the canonical model.
+ *
+ * Adapter isolation: a failure while starting or serving one adapter must not
+ * prevent the others from operating.
+ */
+
+/** Everything an adapter is given. Nothing else is available to it. */
+interface ProtocolAdapterContext {
+    readonly pipeline: ExecutionPipeline;
+    readonly resources: ResourceRegistry;
+    readonly events: EventSink;
+    readonly logger: Logger;
+    readonly clock: Clock;
+    readonly ids: IdGenerator;
+    /** Externally reachable base URL of the gateway, from config. */
+    readonly publicBaseUrl: string;
+}
+interface ProtocolAdapter {
+    readonly name: ProtocolName;
+    readonly descriptor: AdapterDescriptor;
+    start(context: ProtocolAdapterContext): Promise<void>;
+    health(): Promise<AdapterHealth>;
+    stop(): Promise<void>;
+}
+/**
+ * A protocol adapter served over HTTP.
+ *
+ * The gateway mounts `handleHttp` at `mountPath` using raw Node request and
+ * response objects, so adapters stay independent of the HTTP framework.
+ *
+ * GUARANTEE — the request body is **unconsumed**.
+ *
+ * `req` is handed over with its stream unread: the gateway suppresses every
+ * body parser on this mount, so an adapter whose SDK reads the body itself
+ * (MCP's Streamable HTTP transport does) can do so. The adapter owns reading,
+ * size-limiting beyond the gateway's own cap, and parsing.
+ *
+ * This is load-bearing and easy to break silently. Fastify pre-registers
+ * exact-match parsers for `application/json` and `text/plain` and prefers them
+ * over a `'*'` wildcard, so registering only a wildcard no-op leaves the
+ * built-in JSON parser draining the body first — the adapter then reads an
+ * empty stream and every request fails to parse. That exact regression shipped
+ * once and no unit test caught it, because adapter conformance suites drive
+ * `handleHttp` over a bare `node:http` server and never traverse the gateway.
+ *
+ * Any change to how adapters are mounted must be covered by a test that POSTs
+ * a real JSON body through the real gateway and asserts the adapter received
+ * it intact.
+ */
+interface HttpProtocolAdapter extends ProtocolAdapter {
+    /** Path prefix the gateway mounts this adapter at, e.g. '/mcp'. */
+    readonly mountPath: string;
+    handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+declare function isHttpProtocolAdapter(adapter: ProtocolAdapter): adapter is HttpProtocolAdapter;
+
+export { type CommerceEvent as C, type DeliveredOutcome as D, type ExecutionPipeline as E, type HttpProtocolAdapter as H, type PaymentRequiredOutcome as P, type PaymentAttempt as a, type CommerceReceipt as b, type ProtocolAdapter as c, COMMERCE_EVENT_TYPES as d, type CanonicalRequest as e, type CommerceEventType as f, type EventSink as g, type ExecutionOutcome as h, type ProtocolAdapterContext as i, isHttpProtocolAdapter as j };

package/dist/runtime-LCk2TzGN.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Shared primitive aliases used across the canonical domain model.
+ *
+ * FROZEN CONTRACT. Every consumer codes against these shapes; changing one
+ * is a breaking change.
+ */
+/**
+ * A JSON Schema document (draft 2020-12 subset in practice).
+ *
+ * Deliberately loose: protocol adapters translate this to their own schema
+ * representation, and the gateway only validates structurally at trust
+ * boundaries. Never treat this as trusted input without validation.
+ */
+type JsonSchema = Record<string, unknown>;
+/** Protocol surfaces a resource can be exposed through in v0.1. */
+type ProtocolName = 'http' | 'mcp';
+/** Payment methods a resource can accept in v0.1. */
+type PaymentMethodName = 'x402';
+/** ISO-8601 timestamp string, always UTC with millisecond precision. */
+type IsoTimestamp = string;
+/**
+ * A decimal amount expressed as a string in the *display* unit of the currency
+ * (for example "0.01" USDC), never as a float and never in base units.
+ *
+ * Conversion to on-chain base units is a payment-provider responsibility.
+ */
+type DecimalAmount = string;
+/** Health of an individual adapter or subsystem. */
+interface AdapterHealth {
+    readonly status: 'pass' | 'warn' | 'fail';
+    readonly detail?: string;
+    readonly checkedAt: IsoTimestamp;
+    readonly durationMs?: number;
+}
+/**
+ * Self-description every adapter must expose so diagnostics can report exactly
+ * what is supported instead of implying blanket protocol compatibility.
+ *
+ *
+ */
+interface AdapterDescriptor {
+    readonly name: string;
+    readonly kind: 'protocol' | 'payment' | 'storage';
+    /** Version of this adapter implementation (independent of the spec). */
+    readonly implementationVersion: string;
+    /** Exact pinned specification revision this adapter targets. */
+    readonly supportedSpec: string;
+    readonly capabilities: readonly string[];
+    readonly status: 'stable' | 'experimental' | 'planned';
+    /** Capabilities explicitly NOT implemented, surfaced by `doctor`. */
+    readonly unsupported?: readonly string[];
+}
+
+/**
+ * Canonical resource model.
+ *
+ * FROZEN CONTRACT.
+ */
+
+/** HTTP methods a backend handler may use. */
+type BackendMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Describes how the gateway calls the merchant's existing backend.
+ *
+ * Backend URLs are administrator-controlled configuration only. User- or
+ * agent-controlled backend URLs are forbidden (see docs/security.md, SSRF).
+ * Secret header values must come from `${ENV_VAR}` placeholders resolved by
+ * the config loader, never from plaintext configuration.
+ */
+interface BackendHandler {
+    readonly type: 'http';
+    readonly method: BackendMethod;
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Hard upper bound on the backend call. Defaults to DEFAULT_BACKEND_TIMEOUT_MS. */
+    readonly timeoutMs?: number;
+}
+/** Default backend timeout when a resource does not specify one. */
+declare const DEFAULT_BACKEND_TIMEOUT_MS = 10000;
+/**
+ * Canonical pricing.
+ *
+ * `dynamic` exists in the type system for forward compatibility but is
+ * REJECTED by config validation in v0.1.0-alpha.
+ */
+type Pricing = {
+    readonly type: 'free';
+} | {
+    readonly type: 'fixed';
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+} | {
+    readonly type: 'dynamic';
+    readonly resolver: string;
+};
+/**
+ * A merchant capability exposed to agents.
+ *
+ * The canonical resource is the single source of truth: protocol adapters map
+ * it outward, they never define their own parallel notion of a resource.
+ */
+interface CommerceResource {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: JsonSchema;
+    readonly outputSchema?: JsonSchema;
+    readonly handler: BackendHandler;
+    readonly pricing: Pricing;
+    readonly exposedVia: readonly ProtocolName[];
+    readonly paymentMethods: readonly PaymentMethodName[];
+}
+/** Read-only view of every configured resource. */
+interface ResourceRegistry {
+    get(id: string): CommerceResource | undefined;
+    list(): readonly CommerceResource[];
+    /** Resources exposed through a given protocol surface. */
+    listExposedVia(protocol: ProtocolName): readonly CommerceResource[];
+    has(id: string): boolean;
+}
+
+/**
+ * Canonical payment model.
+ *
+ * FROZEN CONTRACT.
+ *
+ * Core decides *that* a payment is required and for how much.
+ * Payment providers decide *how* the challenge is encoded, verified and settled.
+ * No x402/EVM-specific type may appear in this file.
+ */
+
+/**
+ * Provider-native payment challenge, opaque to core.
+ *
+ * For x402 the `accepts` entries are x402 `PaymentRequirements` objects; core
+ * passes them through to protocol adapters verbatim and never inspects them.
+ */
+interface PaymentChallenge {
+    readonly provider: PaymentMethodName;
+    /** Provider protocol version, e.g. the x402 `x402Version` value as a string. */
+    readonly version: string;
+    readonly accepts: readonly Readonly<Record<string, unknown>>[];
+}
+/**
+ * What the buyer must pay, in canonical terms, plus the provider-native
+ * challenge the buyer's client needs in order to construct a payment.
+ */
+interface PaymentRequirement {
+    readonly id: string;
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly provider: PaymentMethodName;
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+    /** Merchant-controlled settlement destination. Never a gateway-owned wallet. */
+    readonly destination: string;
+    readonly network?: string;
+    readonly asset?: string;
+    readonly expiresAt?: IsoTimestamp;
+    readonly challenge: PaymentChallenge;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Opaque payment proof supplied by the buyer's client.
+ *
+ * For x402 over HTTP this is the base64 `X-PAYMENT` header value; over MCP it
+ * is the same string carried in the tool input's `_payment` field.
+ */
+interface PaymentSubmission {
+    readonly method: PaymentMethodName;
+    readonly payload: string;
+}
+/** Outcome of verification or settlement. */
+interface PaymentResult {
+    readonly status: 'verified' | 'settled' | 'rejected';
+    readonly provider: PaymentMethodName;
+    /** Settlement reference, e.g. an on-chain transaction hash. */
+    readonly externalReference?: string;
+    readonly payer?: string;
+    readonly payee?: string;
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+    readonly network?: string;
+    readonly asset?: string;
+    /**
+     * Stable, provider-computed identity of the payment authorisation itself.
+     *
+     * The gateway reserves this key before settlement and rejects any second
+     * request presenting the same key (see PAYMENT_REPLAYED). Providers MUST
+     * derive it only from the authorisation (payer, nonce, asset, network) so
+     * that the same authorisation always maps to the same key.
+     */
+    readonly replayKey?: string;
+    /** Machine-readable rejection reason when status is `rejected`. */
+    readonly rejectionReason?: string;
+    readonly settledAt?: IsoTimestamp;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Input to {@link PaymentProvider.createRequirement}. */
+interface PaymentContext {
+    readonly requestId: string;
+    readonly resource: CommerceResource;
+    readonly amount: DecimalAmount;
+    readonly currency: string;
+    readonly requestedAt: IsoTimestamp;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Input to {@link PaymentProvider.verify}. */
+interface PaymentVerificationContext {
+    readonly requestId: string;
+    readonly resource: CommerceResource;
+    readonly requirement: PaymentRequirement;
+    readonly submission: PaymentSubmission;
+}
+/** Input to {@link PaymentProvider.settle}. */
+interface PaymentSettlementContext extends PaymentVerificationContext {
+    readonly verification: PaymentResult;
+}
+/**
+ * Contract every payment rail implements.
+ *
+ * Implementations must be non-custodial: they orchestrate an external payment
+ * protocol and must never hold buyer or merchant production signing keys.
+ */
+interface PaymentProvider {
+    readonly name: PaymentMethodName;
+    readonly descriptor: AdapterDescriptor;
+    /** Build the challenge presented to an unpaid request. */
+    createRequirement(context: PaymentContext): Promise<PaymentRequirement>;
+    /**
+     * Validate a submitted proof against the requirement.
+     *
+     * Must return `rejected` (or throw a CommerceError) rather than throwing an
+     * untyped error. Must never have side effects that move funds.
+     */
+    verify(context: PaymentVerificationContext): Promise<PaymentResult>;
+    /** Execute settlement. Called only after `verify` returned `verified`. */
+    settle(context: PaymentSettlementContext): Promise<PaymentResult>;
+    health(): Promise<AdapterHealth>;
+}
+
+/**
+ * Minimal structural logger interface.
+ *
+ * Core must not depend on pino directly; the gateway injects a pino instance
+ * that satisfies this shape. Never log secrets: private keys, seed phrases,
+ * Authorization headers or payment authorisation payloads.
+ */
+interface Logger {
+    debug(obj: Record<string, unknown>, msg?: string): void;
+    info(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+    error(obj: Record<string, unknown>, msg?: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+/** A logger that discards everything. Useful in unit tests. */
+declare const NOOP_LOGGER: Logger;
+
+/**
+ * Injected runtime primitives.
+ *
+ * Everything non-deterministic (time, ids) is injected so tests can be exact.
+ */
+
+interface Clock {
+    now(): Date;
+    nowIso(): IsoTimestamp;
+    /** Milliseconds since an arbitrary origin; use for durations only. */
+    monotonicMs(): number;
+}
+interface IdGenerator {
+    /** Opaque, collision-resistant identifier. */
+    next(prefix?: string): string;
+}
+declare const systemClock: Clock;
+
+export { type AdapterDescriptor as A, type BackendHandler as B, type CommerceResource as C, type DecimalAmount as D, type IsoTimestamp as I, type JsonSchema as J, type Logger as L, NOOP_LOGGER as N, type PaymentMethodName as P, type ResourceRegistry as R, type AdapterHealth as a, type PaymentProvider as b, type Clock as c, type IdGenerator as d, type BackendMethod as e, DEFAULT_BACKEND_TIMEOUT_MS as f, type PaymentChallenge as g, type PaymentContext as h, type PaymentRequirement as i, type PaymentResult as j, type PaymentSettlementContext as k, type PaymentSubmission as l, type PaymentVerificationContext as m, type Pricing as n, type ProtocolName as o, systemClock as s };

package/dist/x402.d.ts

@@ -0,0 +1,77 @@
+import { L as Logger, c as Clock, d as IdGenerator, b as PaymentProvider } from './runtime-LCk2TzGN.js';
+
+/**
+ * CLIENT-SIDE payment helper.
+ *
+ * This module is used by the demo buyer agent (`demo/agent`) and by the
+ * payment E2E test suite to build and EIP-712-sign an x402 `exact`/EVM
+ * payment authorisation, entirely on the buyer's side.
+ *
+ * The gateway NEVER calls this module and NEVER holds a buyer private key.
+ * `buyerPrivateKey` here is always an Anvil well-known
+ * development key (LOCAL DEVELOPMENT ONLY — DO NOT FUND) supplied by whoever
+ * is driving the demo/test, not something the provider or gateway manages.
+ */
+interface CreatePaymentProofOptions {
+    /** Buyer's dev-only private key. LOCAL DEVELOPMENT ONLY — DO NOT FUND. */
+    readonly buyerPrivateKey: `0x${string}`;
+    readonly rpcUrl: string;
+    /** One entry from PaymentRequiredEnvelope.payment.accepts, verbatim. */
+    readonly accepts: Readonly<Record<string, unknown>>;
+    /** Overrides used only by negative tests (wrong amount/recipient/nonce…). */
+    readonly overrides?: {
+        readonly value?: string;
+        readonly payTo?: string;
+        readonly nonce?: `0x${string}`;
+        readonly validBefore?: number;
+        readonly validAfter?: number;
+    };
+}
+/** Returns the base64 `X-PAYMENT` value to send back to the gateway. */
+declare function createPaymentProof(options: CreatePaymentProofOptions): Promise<string>;
+
+/**
+ * x402 payment provider — `exact` scheme, EVM, EIP-3009 `transferWithAuthorization`.
+ *
+ * Implements the frozen `PaymentProvider` interface (src/core/domain/payment.ts).
+ * `verify()` never moves funds; only `settle()` does, and only after a
+ * successful `verify()` (enforced by the gateway's execution pipeline, not by
+ * this file, but this file never calls settle-like RPCs from verify()).
+ *
+ * The behaviour of x402@1.2.0 relied on here is verified, not assumed: see the
+ * SDK-behaviour notes beside each call site below.
+ */
+
+interface X402ProviderOptions {
+    /** x402 network name. Local deterministic chain uses 'base-sepolia'. */
+    readonly network: string;
+    /** RPC endpoint. Local chain: http://127.0.0.1:8545 */
+    readonly rpcUrl: string;
+    /** ERC-20 (EIP-3009) asset address used for settlement. */
+    readonly asset: `0x${string}`;
+    /** EIP-712 domain name of the asset, e.g. 'MockUSDC'. */
+    readonly assetName: string;
+    /** EIP-712 domain version of the asset, e.g. '2'. */
+    readonly assetVersion: string;
+    readonly assetDecimals: number;
+    /** Merchant-controlled settlement destination. Never a gateway-owned wallet. */
+    readonly payTo: `0x${string}`;
+    readonly maxTimeoutSeconds?: number;
+    /**
+     * Local facilitator: signer broadcasts settlement on the dev chain only.
+     * LOCAL DEVELOPMENT ONLY — DO NOT FUND.
+     */
+    readonly facilitator: {
+        readonly mode: 'local';
+        readonly signerPrivateKey: `0x${string}`;
+    } | {
+        readonly mode: 'remote';
+        readonly url: string;
+    };
+    readonly logger?: Logger;
+    readonly clock?: Clock;
+    readonly ids?: IdGenerator;
+}
+declare function createX402PaymentProvider(options: X402ProviderOptions): PaymentProvider;
+
+export { type CreatePaymentProofOptions, type X402ProviderOptions, createPaymentProof, createX402PaymentProvider, createX402PaymentProvider as x402 };