@devlab.group/agent-commerce 1.4.1 → 1.6.0

package/dist/runtime-CKq3d_3K.d.ts

@@ -1,340 +0,0 @@
-/**
- * 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 this release.
- *
- * The runtime list is the definition and the type is derived from it, so a
- * caller that has to *check* a name (config validation, the OpenAPI
- * importer's `--expose`) reads the same strings the type is built from
- * rather than keeping a second copy that can drift.
- */
-type ProtocolName = 'http' | 'mcp' | 'a2a' | 'acp';
-/**
- * The same names as a value, for code that has to *check* one at
- * runtime - config validation, the OpenAPI importer's `--expose`. Typed
- * against `ProtocolName` so an unsupported name cannot enter the list, which
- * is what keeps this from becoming a second definition that drifts.
- */
-declare const PROTOCOL_NAMES: readonly ProtocolName[];
-/** Payment methods a resource can accept in this release. */
-type PaymentMethodName = 'x402';
-/**
- * Authorization methods a resource can require in this release.
- *
- * Deliberately not a `ProtocolName` and not a `PaymentMethodName`: an
- * authorization method is neither a transport nor a payment rail. It proves
- * the purchase was approved, and sits beside the payment rather than
- * replacing it.
- */
-type AuthorizationMethodName = 'ap2';
-/** 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' | 'authorization';
-    /** 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;
-    /**
-     * Names the top-level input properties carrying each part of the request.
-     *
-     * Absent (the default) keeps the original mapping: `{param}` values are read
-     * from top-level input and everything left over becomes either the query
-     * string (GET/DELETE) or the entire JSON body (POST/PUT/PATCH). That mapping
-     * cannot express `POST /users/{userId}/orders?notify=true` with a JSON body
-     * - one perfectly ordinary REST operation with all three parts at once.
-     *
-     * When present, each group is sourced independently and top-level input that
-     * no binding names is not forwarded to the backend at all.
-     */
-    readonly inputBindings?: {
-        readonly path?: string;
-        readonly query?: string;
-        readonly body?: string;
-    };
-}
-/** 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 this release.
- */
-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[];
-    /**
-     * Authorization the buyer must present in addition to payment.
-     *
-     * Opt-in per resource and absent by default, so every resource configured
-     * before this existed behaves exactly as it did. It sits beside
-     * `paymentMethods` rather than inside it: an authorization method is not a
-     * payment rail and must never be selectable as one.
-     */
-    readonly authorization?: {
-        readonly required: readonly AuthorizationMethodName[];
-    };
-}
-/** 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>>[];
-    /**
-     * The provider's own challenge document, verbatim — for x402 v2 the
-     * `PaymentRequired` object a buyer's client consumes.
-     *
-     * `accepts` alone is not that document: v2 moves the resource description
-     * out of the individual requirements and up onto the envelope, and the
-     * protocol version rides there too. Protocol adapters that have a native
-     * channel for it (the HTTP `PAYMENT-REQUIRED` header) emit this as-is
-     * rather than reassembling it, so every surface offers the same challenge
-     * instead of each building its own from parts. Opaque to core.
-     */
-    readonly envelope?: 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 `PAYMENT-SIGNATURE` 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 Clock 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 CommerceResource as a, type PaymentSubmission as b, type AdapterHealth as c, type PaymentProvider as d, type IdGenerator as e, type AuthorizationMethodName as f, type BackendMethod as g, DEFAULT_BACKEND_TIMEOUT_MS as h, PROTOCOL_NAMES as i, type PaymentChallenge as j, type PaymentContext as k, type PaymentRequirement as l, type PaymentResult as m, type PaymentSettlementContext as n, type PaymentVerificationContext as o, type Pricing as p, type ProtocolName as q, systemClock as s };