@agent-score/commerce 2.1.0 → 2.1.1

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import { VerifyWalletSignerResult, DenialReason } from './core.mjs';
 export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AssessResult, CreateSessionOnMissing, DenialCode, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, buildAgentMemoryHint } from './core.mjs';
 export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from './signer-3FAit11j.mjs';
-import { r as UCPSigningKey, o as UCPProfile } from './checkout-Bd_4aQ6c.mjs';
-export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as CheckoutValidationError, h as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, i as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, j as PricingFn, k as PricingResult, R as RecipientsFn, l as ReferenceIdFn, m as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, n as UCPPaymentHandlerBinding, p as UCPProfileBody, q as UCPServiceBinding, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-Bd_4aQ6c.mjs';
+import { q as UCPSigningKey, n as UCPProfile } from './checkout-BRw_caGr.mjs';
+export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, h as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, i as PricingFn, j as PricingResult, R as RecipientsFn, k as ReferenceIdFn, l as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, m as UCPPaymentHandlerBinding, o as UCPProfileBody, p as UCPServiceBinding, r as buildUCPProfile, s as getIdentityStatus, t as makeMppxComposeHook, u as mppPaymentHandler, v as pricingResult, w as stripeSptPaymentHandler, x as validationEnvelope, y as validationResponseExpress, z as validationResponseFastify, B as validationResponseHono, E as validationResponseNextjs, F as validationResponseWeb, H as x402PaymentHandler } from './checkout-BRw_caGr.mjs';
 export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed, validateShippingAgainstPolicy } from './identity/policy.mjs';
-import { H as HeadersLike } from './default_rails-BWAquZeu.mjs';
-export { c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, l as loadSolanaFeePayer } from './default_rails-BWAquZeu.mjs';
+import { H as HeadersLike } from './default_rails-XFCuRddA.mjs';
+export { c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, l as loadSolanaFeePayer } from './default_rails-XFCuRddA.mjs';
 import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-D6qzh3J0.mjs';
 export { c as TempoSessionRailSpec } from './rail_spec-D6qzh3J0.mjs';
 import { Context } from 'hono';
@@ -149,6 +149,41 @@ declare function verificationAgentInstructions({ userAction, retryStep, extraSte
  * `error.message` pair regardless of which layer produced the denial.
  */
 
+/**
+ * Build the canonical 4xx body shape for `identity_verification_required`.
+ *
+ * Every merchant maps the gate's auto-minted session fields (verify_url,
+ * session_id, poll_secret, poll_url, agent_instructions) into their own
+ * envelope with a merchant-specific message + error code. This collapses that
+ * mapping into one call:
+ *
+ * ```ts
+ * if (reason.code === 'identity_verification_required') {
+ *   return {
+ *     status: 403,
+ *     body: buildVerificationRequiredBody(reason, {
+ *       message: 'Identity verification is required to call this endpoint.',
+ *       agentInstructions: VERIFICATION_AGENT_INSTRUCTIONS,
+ *     }),
+ *   };
+ * }
+ * ```
+ *
+ * Goods merchants that surface an `order_id` (or similar) from
+ * `createSessionOnMissing.onBeforeSession` get it for free via
+ * `denialReasonToBody(reason)`'s `reason.extra` passthrough — but can also
+ * pass `opts.extra` for fallbacks (e.g. when invoked outside the auto-mint
+ * path and order_id needs to come from the validated context).
+ */
+declare function buildVerificationRequiredBody(reason: DenialReason, opts?: {
+    /** Override the `error.message`. Defaults to the canonical copy. */
+    message?: string;
+    /** Replace `agent_instructions` with merchant-specific copy. When omitted,
+     *  the gate-supplied or default instructions ride through. */
+    agentInstructions?: string;
+    /** Additional fields spread into the body (e.g. fallback `order_id`). */
+    extra?: Record<string, unknown>;
+}): Record<string, unknown>;
 declare function denialReasonToBody(reason: DenialReason): Record<string, unknown>;
 
 /**
@@ -560,6 +595,38 @@ type OwnerScope = {
  */
 declare function extractOwnerScope(input: Request | HeadersLike): OwnerScope;
 
+/**
+ * Cross-module typed errors.
+ *
+ * Lives in its own module so `payment/` and `stripe-multichain/` helpers can
+ * throw `CheckoutValidationError` without importing from `checkout.ts`. (In
+ * the python sibling this avoids a checkout → payment → checkout cycle; in
+ * node it sidesteps tsup's per-entry class duplication.)
+ *
+ * Re-exported from `checkout.ts` and the top-level entry to preserve the
+ * public import path.
+ */
+/**
+ * Raised to short-circuit a Checkout flow with a 4xx/5xx envelope. The
+ * framework catches this at request-flow boundaries (`preValidate`, recipient
+ * minting, settlement dispatch) and emits `{ error, next_steps }` via
+ * `buildValidationError` so merchants don't construct response bodies
+ * themselves.
+ */
+declare class CheckoutValidationError extends Error {
+    readonly code: string;
+    readonly action: string;
+    readonly status: number;
+    readonly extra: Record<string, unknown> | undefined;
+    constructor(opts: {
+        code: string;
+        message: string;
+        action?: string;
+        status?: number;
+        extra?: Record<string, unknown>;
+    });
+}
+
 /**
  * Short-TTL body-hash quote cache for the compute-first + exact-x402 pattern
  * (see {@link computeFirstCheckout}).
@@ -861,4 +928,4 @@ declare function createDefaultOnDenied(opts: CreateDefaultOnDeniedOptions): (rea
  */
 declare function defaultReadOnlyOnDenied(reason: DenialReason): DefaultOnDeniedResult;
 
-export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, type CachedQuote, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyUCPProfile };
+export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, type CachedQuote, CheckoutValidationError, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstMppContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstSettledContext, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, buildVerificationRequiredBody, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyUCPProfile };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { VerifyWalletSignerResult, DenialReason } from './core.js';
 export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AssessResult, CreateSessionOnMissing, DenialCode, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, buildAgentMemoryHint } from './core.js';
 export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from './signer-3FAit11j.js';
-import { r as UCPSigningKey, o as UCPProfile } from './checkout-BH-I_Ns8.js';
-export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as CheckoutValidationError, h as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, i as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, j as PricingFn, k as PricingResult, R as RecipientsFn, l as ReferenceIdFn, m as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, n as UCPPaymentHandlerBinding, p as UCPProfileBody, q as UCPServiceBinding, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-BH-I_Ns8.js';
+import { q as UCPSigningKey, n as UCPProfile } from './checkout-CuSNUJFX.js';
+export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, h as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, i as PricingFn, j as PricingResult, R as RecipientsFn, k as ReferenceIdFn, l as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, m as UCPPaymentHandlerBinding, o as UCPProfileBody, p as UCPServiceBinding, r as buildUCPProfile, s as getIdentityStatus, t as makeMppxComposeHook, u as mppPaymentHandler, v as pricingResult, w as stripeSptPaymentHandler, x as validationEnvelope, y as validationResponseExpress, z as validationResponseFastify, B as validationResponseHono, E as validationResponseNextjs, F as validationResponseWeb, H as x402PaymentHandler } from './checkout-CuSNUJFX.js';
 export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed, validateShippingAgainstPolicy } from './identity/policy.js';
-import { H as HeadersLike } from './default_rails-BxBzcCA1.js';
-export { c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, l as loadSolanaFeePayer } from './default_rails-BxBzcCA1.js';
+import { H as HeadersLike } from './default_rails-C5gKZJMI.js';
+export { c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, l as loadSolanaFeePayer } from './default_rails-C5gKZJMI.js';
 import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-D6qzh3J0.js';
 export { c as TempoSessionRailSpec } from './rail_spec-D6qzh3J0.js';
 import { Context } from 'hono';
@@ -149,6 +149,41 @@ declare function verificationAgentInstructions({ userAction, retryStep, extraSte
  * `error.message` pair regardless of which layer produced the denial.
  */
 
+/**
+ * Build the canonical 4xx body shape for `identity_verification_required`.
+ *
+ * Every merchant maps the gate's auto-minted session fields (verify_url,
+ * session_id, poll_secret, poll_url, agent_instructions) into their own
+ * envelope with a merchant-specific message + error code. This collapses that
+ * mapping into one call:
+ *
+ * ```ts
+ * if (reason.code === 'identity_verification_required') {
+ *   return {
+ *     status: 403,
+ *     body: buildVerificationRequiredBody(reason, {
+ *       message: 'Identity verification is required to call this endpoint.',
+ *       agentInstructions: VERIFICATION_AGENT_INSTRUCTIONS,
+ *     }),
+ *   };
+ * }
+ * ```
+ *
+ * Goods merchants that surface an `order_id` (or similar) from
+ * `createSessionOnMissing.onBeforeSession` get it for free via
+ * `denialReasonToBody(reason)`'s `reason.extra` passthrough — but can also
+ * pass `opts.extra` for fallbacks (e.g. when invoked outside the auto-mint
+ * path and order_id needs to come from the validated context).
+ */
+declare function buildVerificationRequiredBody(reason: DenialReason, opts?: {
+    /** Override the `error.message`. Defaults to the canonical copy. */
+    message?: string;
+    /** Replace `agent_instructions` with merchant-specific copy. When omitted,
+     *  the gate-supplied or default instructions ride through. */
+    agentInstructions?: string;
+    /** Additional fields spread into the body (e.g. fallback `order_id`). */
+    extra?: Record<string, unknown>;
+}): Record<string, unknown>;
 declare function denialReasonToBody(reason: DenialReason): Record<string, unknown>;
 
 /**
@@ -560,6 +595,38 @@ type OwnerScope = {
  */
 declare function extractOwnerScope(input: Request | HeadersLike): OwnerScope;
 
+/**
+ * Cross-module typed errors.
+ *
+ * Lives in its own module so `payment/` and `stripe-multichain/` helpers can
+ * throw `CheckoutValidationError` without importing from `checkout.ts`. (In
+ * the python sibling this avoids a checkout → payment → checkout cycle; in
+ * node it sidesteps tsup's per-entry class duplication.)
+ *
+ * Re-exported from `checkout.ts` and the top-level entry to preserve the
+ * public import path.
+ */
+/**
+ * Raised to short-circuit a Checkout flow with a 4xx/5xx envelope. The
+ * framework catches this at request-flow boundaries (`preValidate`, recipient
+ * minting, settlement dispatch) and emits `{ error, next_steps }` via
+ * `buildValidationError` so merchants don't construct response bodies
+ * themselves.
+ */
+declare class CheckoutValidationError extends Error {
+    readonly code: string;
+    readonly action: string;
+    readonly status: number;
+    readonly extra: Record<string, unknown> | undefined;
+    constructor(opts: {
+        code: string;
+        message: string;
+        action?: string;
+        status?: number;
+        extra?: Record<string, unknown>;
+    });
+}
+
 /**
  * Short-TTL body-hash quote cache for the compute-first + exact-x402 pattern
  * (see {@link computeFirstCheckout}).
@@ -861,4 +928,4 @@ declare function createDefaultOnDenied(opts: CreateDefaultOnDeniedOptions): (rea
  */
 declare function defaultReadOnlyOnDenied(reason: DenialReason): DefaultOnDeniedResult;
 
-export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, type CachedQuote, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyUCPProfile };
+export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, type CachedQuote, CheckoutValidationError, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstMppContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstSettledContext, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, buildVerificationRequiredBody, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyUCPProfile };