@devlab.group/agent-commerce 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-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-CC6EFmLP.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-CC6EFmLP.js';
+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-Plk5Peqi.js';
+export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PROTOCOL_NAMES, h as PaymentChallenge, i as PaymentContext, j as PaymentRequirement, k as PaymentResult, l as PaymentSettlementContext, m as PaymentSubmission, n as PaymentVerificationContext, o as Pricing, p as ProtocolName, s as systemClock } from './runtime-Plk5Peqi.js';
 import { X as X402FacilitatorConfig } from './guardrails-Dmwi63KB.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-DZ8qkkAa.js';
-export { A as AdapterHttpRoute, 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-DZ8qkkAa.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter, H as HttpProtocolAdapter, A as AdapterHttpRoute, d as ProtocolAdapterContext } from './protocol-adapter-DTFGWGXq.js';
+export { e as COMMERCE_EVENT_TYPES, f as CanonicalRequest, g as CommerceEventType, h as EventSink, i as ExecutionOutcome, j as isHttpProtocolAdapter } from './protocol-adapter-DTFGWGXq.js';
 import { FastifyInstance } from 'fastify';
-import 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
 
 /**
  * Typed domain error codes.
@@ -309,6 +309,33 @@ interface ReceiptStore {
     close(): Promise<void>;
 }
 
+/**
+ * ACP protocol constants shared by the config layer and the adapter.
+ *
+ * Kept dependency-free: `src/config` reads the operation set at load time, so
+ * anything imported here would become a config-load dependency too.
+ */
+/**
+ * The ACP stable snapshot this adapter implements, and the only value accepted
+ * in the `API-Version` request header. Both name the same released snapshot;
+ * they are separate constants because ACP versions the wire contract and the
+ * header independently, and a future snapshot may accept more than one.
+ *
+ * Changing either means vendoring a new schema directory beside
+ * `spec/2026-04-17/` - never editing the vendored one in place.
+ */
+declare const ACP_SPEC_VERSION = "2026-04-17";
+declare const ACP_API_VERSION = "2026-04-17";
+/** Discovery path fixed by the ACP specification - never a configurable mount. */
+declare const ACP_WELL_KNOWN_PATH = "/.well-known/acp.json";
+/**
+ * The stable checkout operations, by ACP operation id. All five are required
+ * when ACP is enabled: a partially configured checkout lifecycle would be
+ * advertised as a whole service the seller cannot actually serve.
+ */
+declare const ACP_CHECKOUT_OPERATIONS: readonly ["createCheckoutSession", "updateCheckoutSession", "getCheckoutSession", "completeCheckoutSession", "cancelCheckoutSession"];
+type AcpCheckoutOperation = (typeof ACP_CHECKOUT_OPERATIONS)[number];
+
 /**
  * `config.yaml` schema, validation and normalisation into the
  * canonical `GatewayConfig` (docs/contracts.md).
@@ -316,7 +343,7 @@ interface ReceiptStore {
  * 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 —
+ * (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.
@@ -335,6 +362,37 @@ interface ReceiptStore {
  * substitution rule, which this sentence exists to record.
  */
 
+/** Optional ACP discovery metadata. Absent fields are omitted from the document. */
+interface AcpDiscoveryConfig {
+    readonly documentationUrl?: string;
+    readonly supportedCurrencies?: readonly string[];
+    readonly supportedLocales?: readonly string[];
+    readonly interventionTypes?: readonly string[];
+}
+/**
+ * Discriminated on `enabled` so an enabled ACP config carries everything the
+ * adapter needs, with no optional-field assertions at the mount point: a
+ * half-configured checkout lifecycle is rejected at load instead.
+ */
+type AcpProtocolConfig = {
+    readonly enabled: false;
+    readonly mountPath: string;
+} | {
+    readonly enabled: true;
+    readonly mountPath: string;
+    readonly auth: {
+        readonly type: 'bearer';
+        readonly token: string;
+    };
+    readonly idempotency: {
+        readonly path: string;
+        readonly retentionHours: number;
+    };
+    readonly checkout: {
+        readonly operations: Readonly<Record<AcpCheckoutOperation, string>>;
+    };
+    readonly discovery?: AcpDiscoveryConfig;
+};
 interface GatewayConfig {
     readonly version: 1;
     readonly merchant: {
@@ -366,6 +424,7 @@ interface GatewayConfig {
             readonly enabled: boolean;
             readonly mountPath: string;
         };
+        readonly acp: AcpProtocolConfig;
     };
     /** Canonical resources, already normalised. */
     readonly resources: readonly CommerceResource[];
@@ -423,6 +482,94 @@ interface GatewayInstance {
 }
 declare function createGateway(options: GatewayOptions): Promise<GatewayInstance>;
 
+/** Discovery metadata an operator may configure. Absent fields are omitted, never guessed. */
+interface AcpDiscoveryMetadata {
+    readonly documentationUrl?: string;
+    readonly supportedCurrencies?: readonly string[];
+    readonly supportedLocales?: readonly string[];
+    readonly interventionTypes?: readonly string[];
+}
+
+/**
+ * ACP (Agentic Commerce Protocol) adapter - experimental.
+ *
+ * Serves two paths: the configured mount (`/acp`), where the five stable
+ * checkout routes live, and the specification-fixed `/.well-known/acp.json`,
+ * declared through `additionalHttpRoutes` so the gateway needs no ACP-specific
+ * routing.
+ *
+ * Discovery and every protocol guard that must hold before canonical execution
+ * are implemented. A guarded request is not executed yet: until checkout
+ * operations reach the pipeline, a fully-valid request is answered with an
+ * honest "not implemented" rather than a fabricated session.
+ *
+ * This file never calls a merchant backend and never inspects a payment
+ * object.
+ */
+
+interface AcpAdapterOptions {
+    readonly mountPath: string;
+    /** The configured bearer token. Never logged, never echoed, never published. */
+    readonly token: string;
+    /** Which canonical resource implements each ACP checkout operation. */
+    readonly operations: Readonly<Record<AcpCheckoutOperation, string>>;
+    /** Where checkout idempotency records live, and how long they are kept. */
+    readonly idempotency: {
+        readonly path: string;
+        readonly retentionHours: number;
+    };
+    readonly discovery?: AcpDiscoveryMetadata;
+}
+declare class AcpProtocolAdapter implements HttpProtocolAdapter {
+    readonly name: "acp";
+    readonly mountPath: string;
+    readonly descriptor: AdapterDescriptor;
+    readonly additionalHttpRoutes: readonly AdapterHttpRoute[];
+    private readonly token;
+    private readonly operations;
+    private readonly idempotencyOptions;
+    /** Derived once: the token is fixed, and only its digest may be persisted. */
+    private readonly identityHash;
+    private readonly discoveryMetadata;
+    private idempotency;
+    private resources;
+    private context;
+    private started;
+    private discovery;
+    constructor(options: AcpAdapterOptions);
+    start(context: ProtocolAdapterContext): Promise<void>;
+    /** `GET /.well-known/acp.json` - public, unauthenticated, cacheable. */
+    handleDiscovery(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** `<mountPath>/checkout_sessions...` - the five stable checkout routes. */
+    handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * One request, at most one execution.
+     *
+     * A body-bearing route claims its idempotency key *before* the work starts,
+     * so a retry that arrives while the first one is still running finds the
+     * claim instead of starting a second checkout. A route with no key (the GET)
+     * is read-only and needs none.
+     */
+    private dispatch;
+    /**
+     * One accepted request, one `pipeline.execute()`.
+     *
+     * Nothing here prices a resource, inspects a payment proof or calls a
+     * merchant backend: the adapter builds a canonical request and reads back
+     * what the pipeline decided.
+     */
+    private runCheckout;
+    /**
+     * Protocol-owned headers only. A merchant backend's own headers are never
+     * proxied onto an ACP response.
+     */
+    private responseHeaders;
+    private fail;
+    health(): Promise<AdapterHealth>;
+    stop(): Promise<void>;
+}
+declare function createAcpAdapter(options: AcpAdapterOptions): AcpProtocolAdapter;
+
 interface SqliteReceiptStoreOptions {
     /** File path, or ':memory:' for tests. Parent directory is created if missing. */
     readonly path: string;
@@ -432,4 +579,4 @@ interface SqliteReceiptStoreOptions {
 }
 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_REQUIRED_HEADER, 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 };
+export { ACP_API_VERSION, ACP_SPEC_VERSION, ACP_WELL_KNOWN_PATH, type AcpAdapterOptions, AdapterDescriptor, AdapterHealth, AdapterHttpRoute, 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, HttpProtocolAdapter, IdGenerator, IsoTimestamp, type ListOptions, Logger, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, ProtocolAdapter, ProtocolAdapterContext, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createAcpAdapter, createGateway, createSqliteReceiptStore, isCommerceError, isPaymentRequiredEnvelope, loadConfig, parseConfig, createSqliteReceiptStore as receipts, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };