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

package/dist/index.d.ts

@@ -0,0 +1,412 @@
+import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, B as BackendHandler, A as AdapterDescriptor, a as AdapterHealth, C as CommerceResource, R as ResourceRegistry, b as PaymentProvider, L as Logger, c as Clock, d as IdGenerator } from './runtime-LCk2TzGN.js';
+export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PaymentChallenge, h as PaymentContext, i as PaymentRequirement, j as PaymentResult, k as PaymentSettlementContext, l as PaymentSubmission, m as PaymentVerificationContext, n as Pricing, o as ProtocolName, s as systemClock } from './runtime-LCk2TzGN.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter } from './protocol-adapter-C0goMgLK.js';
+export { d as COMMERCE_EVENT_TYPES, e as CanonicalRequest, f as CommerceEventType, g as EventSink, h as ExecutionOutcome, H as HttpProtocolAdapter, i as ProtocolAdapterContext, j as isHttpProtocolAdapter } from './protocol-adapter-C0goMgLK.js';
+import { FastifyInstance } from 'fastify';
+import 'node:http';
+
+/**
+ * Typed domain error codes.
+ *
+ * FROZEN CONTRACT. Protocol adapters map these codes into their own response
+ * format. Never throw a bare string or untyped Error across a package boundary.
+ */
+declare const COMMERCE_ERROR_CODES: readonly ["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"];
+type CommerceErrorCode = (typeof COMMERCE_ERROR_CODES)[number];
+/**
+ * Canonical HTTP status for each error code.
+ *
+ * Paid resources fail closed: every payment failure maps to a 4xx/5xx status
+ * and never to a successful delivery.
+ */
+declare const COMMERCE_ERROR_HTTP_STATUS: Readonly<Record<CommerceErrorCode, number>>;
+/** Codes for which a client may reasonably retry the same request. */
+declare const RETRYABLE_ERROR_CODES: ReadonlySet<CommerceErrorCode>;
+
+/**
+ * The single error type crossing package boundaries.
+ *
+ * FROZEN CONTRACT.
+ */
+
+interface CommerceErrorOptions {
+    /** Structured, non-secret detail safe to return to a client. */
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly cause?: unknown;
+    readonly requestId?: string;
+    readonly resourceId?: string;
+    /** Override the default HTTP status for this code. */
+    readonly httpStatus?: number;
+}
+/** Serialisable wire form of a CommerceError. */
+interface CommerceErrorInfo {
+    readonly code: CommerceErrorCode;
+    readonly message: string;
+    readonly httpStatus: number;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly resourceId?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+declare class CommerceError extends Error {
+    readonly code: CommerceErrorCode;
+    readonly httpStatus: number;
+    readonly retryable: boolean;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly requestId?: string;
+    readonly resourceId?: string;
+    constructor(code: CommerceErrorCode, message: string, options?: CommerceErrorOptions);
+    /** Non-secret, client-safe representation. */
+    toInfo(): CommerceErrorInfo;
+}
+declare function isCommerceError(value: unknown): value is CommerceError;
+/**
+ * Normalise any thrown value into a CommerceError.
+ *
+ * Used at package boundaries so an unexpected failure never escapes untyped.
+ *
+ * SECURITY — do not "improve" this by propagating `value.message`.
+ * `CommerceError.message` is client-visible: it is serialised by `toInfo()`
+ * and `toErrorEnvelope()` and returned over HTTP and MCP. An arbitrary thrown
+ * Error's message routinely carries internal detail — database connection
+ * strings, internal hostnames, filesystem paths, backend URLs. Copying it into
+ * a client-facing field turns every unexpected exception into an information
+ * disclosure.
+ *
+ * The original value is preserved on `cause`, which is never serialised, so
+ * logs and diagnostics keep the full detail while clients get only the
+ * caller's deliberate, reviewed `fallbackMessage`.
+ *
+ * A caller that *wants* a specific client-facing message passes one:
+ * toCommerceError(err, 'BACKEND_ERROR', 'Backend call failed')
+ */
+declare function toCommerceError(value: unknown, fallbackCode?: CommerceErrorCode, fallbackMessage?: string): CommerceError;
+
+/**
+ * Gateway-defined wire envelopes.
+ *
+ * FROZEN CONTRACT. These are the *only* representations of "payment required"
+ * and "error" that leave the gateway, whichever protocol carries them. The HTTP
+ * routes, the MCP adapter and the demo buyer agent all use these helpers so the
+ * three can never drift apart.
+ */
+
+/**
+ * Reserved input property carrying a payment proof on protocols that have no
+ * header channel (MCP tool calls). Over HTTP the `X-PAYMENT` header is used.
+ */
+declare const PAYMENT_INPUT_FIELD = "_payment";
+/** HTTP header carrying the payment proof. */
+declare const PAYMENT_HEADER = "x-payment";
+/** HTTP response header carrying the settlement reference. */
+declare const PAYMENT_RESPONSE_HEADER = "x-payment-response";
+/**
+ * Key under which a protocol adapter attaches a {@link DeliverySummary} to its
+ * result metadata — MCP's `CallToolResult._meta`, and anywhere else a protocol
+ * offers an out-of-band metadata channel.
+ *
+ * Frozen deliberately. The bug this whole mechanism exists to fix was two
+ * surfaces disagreeing about what a payer gets back; a key name enforced only
+ * by one side's tests would reintroduce exactly that drift. Producer and
+ * consumer both import this constant.
+ *
+ * Follows MCP's `<namespace>/<name>` convention for `_meta` keys.
+ */
+declare const DELIVERY_SUMMARY_META_KEY = "agent-commerce/delivery";
+interface PaymentRequiredEnvelope {
+    readonly status: 'payment-required';
+    readonly code: 'PAYMENT_REQUIRED';
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly message: string;
+    readonly payment: {
+        readonly provider: PaymentMethodName;
+        readonly version: string;
+        readonly amount: DecimalAmount;
+        readonly currency: string;
+        readonly destination: string;
+        readonly network?: string;
+        readonly asset?: string;
+        readonly expiresAt?: IsoTimestamp;
+        /** Provider-native requirement objects, passed through verbatim. */
+        readonly accepts: readonly Readonly<Record<string, unknown>>[];
+    };
+}
+interface ErrorEnvelope {
+    readonly status: 'error';
+    readonly code: CommerceErrorCode;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly resourceId?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * What a buyer learns about their own completed purchase.
+ *
+ * A payer is entitled to the record of their own transaction — the request it
+ * belonged to, whether it settled, and the settlement reference they can check
+ * on-chain. They are NOT entitled to the merchant's ledger, which is why
+ * `/api/receipts` is an operator route behind `server.adminToken`.
+ *
+ * Before this existed the two surfaces disagreed: HTTP callers received a
+ * settlement summary in `X-PAYMENT-RESPONSE` while MCP callers received
+ * nothing, so an MCP buyer's only route to their own receipt was the merchant's
+ * ledger. Both surfaces now emit this same shape.
+ */
+interface DeliverySummary {
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly receiptId: string;
+    readonly deliveredAt: IsoTimestamp;
+    readonly payment?: {
+        readonly status: 'verified' | 'settled' | 'rejected';
+        readonly amount: DecimalAmount;
+        readonly currency: string;
+        /** Settlement reference, e.g. an on-chain transaction hash. */
+        readonly externalReference?: string;
+        readonly network?: string;
+    };
+}
+/** Build the payer-facing summary of a delivered outcome. */
+declare function toDeliverySummary(outcome: DeliveredOutcome): DeliverySummary;
+declare function toPaymentRequiredEnvelope(outcome: PaymentRequiredOutcome): PaymentRequiredEnvelope;
+declare function toErrorEnvelope(error: CommerceError): ErrorEnvelope;
+declare function isPaymentRequiredEnvelope(value: unknown): value is PaymentRequiredEnvelope;
+
+/**
+ * Merchant backend execution boundary.
+ *
+ * The only place in the system allowed to make an outbound HTTP call to a
+ * merchant backend. Every call is bounded by a timeout; redirects are not
+ * followed (see docs/security.md).
+ */
+
+interface BackendRequest {
+    readonly requestId: string;
+    readonly resourceId: string;
+    /** Validated resource input. */
+    readonly input: unknown;
+}
+interface BackendResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: unknown;
+    readonly durationMs: number;
+}
+interface BackendExecutor {
+    /**
+     * Call the merchant backend.
+     *
+     * Must throw `CommerceError('BACKEND_TIMEOUT')` on timeout and
+     * `CommerceError('BACKEND_ERROR')` for non-2xx responses and transport
+     * failures. Must never throw an untyped error.
+     */
+    call(handler: BackendHandler, request: BackendRequest): Promise<BackendResponse>;
+}
+
+/**
+ * Persistence boundary for receipts, events and payment attempts.
+ *
+ * Implemented by src/storage/receipts. Core depends only on this
+ * interface, never on SQLite.
+ */
+
+interface PaymentAttemptReservation {
+    readonly requestId: string;
+    readonly resourceId: string;
+    readonly provider: string;
+    /** Must be unique across the store — see PaymentResult.replayKey. */
+    readonly replayKey: string;
+    readonly amount: string;
+    readonly currency: string;
+    readonly payer?: string;
+    readonly payee?: string;
+}
+interface PaymentAttemptUpdate {
+    readonly replayKey: string;
+    readonly status: PaymentAttempt['status'];
+    readonly externalReference?: string;
+    readonly rejectionReason?: string;
+}
+interface ListOptions {
+    readonly limit?: number;
+    readonly requestId?: string;
+}
+interface ReceiptStore {
+    init(): Promise<void>;
+    /** Append a canonical event. Must not throw into the caller's flow. */
+    appendEvent(event: CommerceEvent): Promise<void>;
+    /**
+     * Atomically claim a payment authorisation before settlement.
+     *
+     * Throws `CommerceError('PAYMENT_REPLAYED')` if `replayKey` was already
+     * reserved. This is the gateway's replay defence and is required for every
+     * paid request.
+     */
+    reservePaymentAttempt(reservation: PaymentAttemptReservation): Promise<PaymentAttempt>;
+    updatePaymentAttempt(update: PaymentAttemptUpdate): Promise<void>;
+    saveReceipt(receipt: CommerceReceipt): Promise<void>;
+    getReceipt(id: string): Promise<CommerceReceipt | undefined>;
+    listReceipts(options?: ListOptions): Promise<readonly CommerceReceipt[]>;
+    /**
+     * Total receipts held, ignoring any list limit.
+     *
+     * `listReceipts` clamps to a bounded page (a store-level invariant, so an
+     * unbounded `limit` cannot dump the ledger). Counting by measuring the length
+     * of a list therefore silently saturates at the clamp — `doctor` reported
+     * "receipts=500" forever once 500 was passed. A diagnostic that quietly stops
+     * counting is worse than one that admits it cannot.
+     */
+    countReceipts(): Promise<number>;
+    /**
+     * Receipts whose delivery did not succeed — `backendStatus` outside 2xx.
+     *
+     * A paid-but-undelivered purchase is the one row a merchant must notice:
+     * settlement is final and v0.1 has no refunds, so *seeing* it is the only
+     * remedy available. Counted rather than listed for the same reason as
+     * {@link countReceipts} — `listReceipts` is clamped, so counting by list
+     * length silently saturates.
+     *
+     * In practice this is exactly "paid but undelivered", not "any failed
+     * delivery": the pipeline only ever persists a receipt when a payment was
+     * attempted (`paymentResult !== undefined`), so a free resource whose
+     * backend call fails throws without writing a receipt at all — there is no
+     * row for `countUndeliveredReceipts` to see. Free-resource failures are
+     * therefore *not* counted here, however natural it is to read the name as
+     * saying they are. Writing a receipt for a failed free delivery too would be
+     * a more complete ledger, but it changes what this count means — that is
+     * a product decision for after the alpha, not something to do here.
+     */
+    countUndeliveredReceipts(): Promise<number>;
+    listEvents(options?: ListOptions): Promise<readonly CommerceEvent[]>;
+    listPaymentAttempts(options?: ListOptions): Promise<readonly PaymentAttempt[]>;
+    readonly descriptor: AdapterDescriptor;
+    health(): Promise<AdapterHealth>;
+    close(): Promise<void>;
+}
+
+/**
+ * `config.yaml` schema, validation and normalisation into the
+ * canonical `GatewayConfig` (docs/contracts.md).
+ *
+ * Two-phase validation:
+ * 1. Zod validates *shape* (types, required fields, unknown-key rejection).
+ * Numeric/boolean leaves accept either their native type or a string
+ * (env substitution always produces a string), and are left as-is here —
+ * Zod's typed transforms have surprising inference interactions with
+ * `.strict()` objects, so numeric/boolean coercion is done explicitly,
+ * in plain TypeScript, in the normalisation pass below.
+ * 2. A manual business-rule pass validates cross-references that need a
+ * specific, actionable message (duplicate ids, disabled protocols/payment
+ * methods, dynamic pricing, destination-address plausibility) and
+ * performs the numeric/boolean coercion.
+ *
+ * Env substitution (`${VAR}` / `${VAR:-default}`) runs over the raw parsed
+ * value *before* either phase, so numeric/boolean fields can be templated too.
+ * One exception, deliberate: `checkVersion` runs **before** substitution, so
+ * `version:` cannot itself be templated. It is the compatibility gate that
+ * decides whether this parser understands the document at all; resolving
+ * environment variables to find out which schema version to expect would be
+ * backwards. The order is intended; `version:` is the one exception to the
+ * substitution rule, which this sentence exists to record.
+ */
+
+interface GatewayConfig {
+    readonly version: 1;
+    readonly merchant: {
+        readonly id: string;
+        readonly name: string;
+        readonly publicBaseUrl: string;
+    };
+    readonly server: {
+        readonly port: number;
+        readonly host: string;
+        readonly adminToken?: string;
+        readonly allowedOrigins: readonly string[];
+    };
+    readonly storage: {
+        readonly receipts: {
+            readonly driver: 'sqlite';
+            readonly path: string;
+        };
+    };
+    readonly protocols: {
+        readonly http: {
+            readonly enabled: boolean;
+        };
+        readonly mcp: {
+            readonly enabled: boolean;
+            readonly mountPath: string;
+        };
+    };
+    /** Canonical resources, already normalised. */
+    readonly resources: readonly CommerceResource[];
+    readonly payments: {
+        readonly x402?: {
+            readonly enabled: boolean;
+            readonly network: string;
+            readonly rpcUrl: string;
+            readonly asset: string;
+            readonly assetName: string;
+            readonly assetVersion: string;
+            readonly assetDecimals: number;
+            readonly payTo: string;
+            readonly maxTimeoutSeconds: number;
+            readonly facilitator: {
+                readonly mode: 'local';
+                readonly signerPrivateKey: string;
+            } | {
+                readonly mode: 'remote';
+                readonly url: string;
+            };
+        };
+    };
+}
+declare function parseConfig(raw: unknown, env: NodeJS.ProcessEnv): GatewayConfig;
+
+interface LoadConfigOptions {
+    readonly path?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly cwd?: string;
+}
+declare function loadConfig(options?: LoadConfigOptions): Promise<GatewayConfig>;
+
+/**
+ * `createGateway()` — the Fastify server. Fully usable (and tested) with
+ * fakes, without `main.ts` (docs/contracts.md "Composition root").
+ */
+
+interface GatewayOptions {
+    readonly config: GatewayConfig;
+    readonly store: ReceiptStore;
+    readonly paymentProviders: readonly PaymentProvider[];
+    readonly protocolAdapters: readonly ProtocolAdapter[];
+    readonly logger?: Logger;
+    readonly clock?: Clock;
+    readonly ids?: IdGenerator;
+    /** Override for tests. */
+    readonly backend?: BackendExecutor;
+}
+interface GatewayInstance {
+    readonly pipeline: ExecutionPipeline;
+    readonly resources: ResourceRegistry;
+    listen(): Promise<{
+        url: string;
+    }>;
+    close(): Promise<void>;
+    /** Fastify instance, for `.inject()` in tests. */
+    readonly server: FastifyInstance;
+}
+declare function createGateway(options: GatewayOptions): Promise<GatewayInstance>;
+
+interface SqliteReceiptStoreOptions {
+    /** File path, or ':memory:' for tests. Parent directory is created if missing. */
+    readonly path: string;
+    readonly logger?: Logger;
+    readonly clock?: Clock;
+    readonly ids?: IdGenerator;
+}
+declare function createSqliteReceiptStore(options: SqliteReceiptStoreOptions): ReceiptStore;
+
+export { AdapterDescriptor, AdapterHealth, type BackendExecutor, BackendHandler, type BackendRequest, type BackendResponse, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, Clock, CommerceError, type CommerceErrorCode, type CommerceErrorInfo, type CommerceErrorOptions, CommerceEvent, CommerceReceipt, CommerceResource, DELIVERY_SUMMARY_META_KEY, DecimalAmount, DeliveredOutcome, type DeliverySummary, type ErrorEnvelope, ExecutionPipeline, type GatewayConfig, type GatewayInstance, type GatewayOptions, IdGenerator, IsoTimestamp, type ListOptions, Logger, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, ProtocolAdapter, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createGateway, createSqliteReceiptStore, isCommerceError, isPaymentRequiredEnvelope, loadConfig, parseConfig, createSqliteReceiptStore as receipts, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };