@astrasyncai/verification-gateway 5.4.2 → 5.6.0

package/dist/git-trigger/git-hooks.d.mts

@@ -1,4 +1,4 @@
-import { T as TokenGuidance, b as CounterpartyType } from '../types-Bd2O3eX1.mjs';
+import { T as TokenGuidance, b as CounterpartyType } from '../types-BCmHFdkJ.mjs';
 import '../metadata-capture.mjs';
 
 /**

package/dist/git-trigger/git-hooks.d.ts

@@ -1,4 +1,4 @@
-import { T as TokenGuidance, b as CounterpartyType } from '../types-DMChboN_.js';
+import { T as TokenGuidance, b as CounterpartyType } from '../types-CwY5IY-0.js';
 import '../metadata-capture.js';
 
 /**

package/dist/index.d.mts

@@ -653,11 +653,72 @@ interface VerificationResult {
      * instrument on file (steer the user to add one via onboarding).
      */
     settlementOutcome?: SettlementOutcomeInfo;
+    /**
+     * 5.5.0 (astra-pay): interim merchant self-settlement token. Present ONLY
+     * for firstParty merchants opted into settlement_mode='self_settle' on the
+     * confirm leg — YOUR server charges with this material on the shared Stripe
+     * account and reports the outcome via `client.reportSettlement()`.
+     * MERCHANT-ONLY lane: never expose it to the agent plane, never log it,
+     * never echo it back over the bridge handoff (the bridge strips it
+     * defensively). Charge with idempotency key `voucher:<jti>` and
+     * `metadata.jti` — that lets the platform webhook auto-reconcile even if
+     * your report never arrives.
+     */
+    settlementToken?: MerchantSettlementToken;
+    /**
+     * 5.6.0 (astra-pay): fulfilment contact for first-party confirm legs.
+     * The platform always resolves an email for the merchant — the agent's
+     * `buyerEmail` when one was supplied, else the buyer's account email
+     * (`emailSource` says which). Present on every first-party confirm leg that
+     * progressed (settled, pending_merchant, held, requires_action) so it can be
+     * stored with a pending order; only FULFIL against it once the order is
+     * settled / pending_merchant. MERCHANT-ONLY lane like `settlementToken` —
+     * the bridge strips it from the agent plane. An explicit `buyerEmail` on the
+     * confirm handoff body wins over `fulfilment.email` (the platform default).
+     */
+    fulfilment?: FulfilmentInfo;
     /** Timestamp of verification */
     verifiedAt: Date;
     /** TTL for this result (seconds) */
     cacheTtl?: number;
 }
+/**
+ * 5.5.0 (astra-pay): agent-blind settlement token for self-settling
+ * first-party merchants. Self-describing via `type`, so a Stripe Shared
+ * Payment Token can replace the raw customer/payment-method pair without a
+ * contract change.
+ */
+interface MerchantSettlementToken {
+    type: 'stripe_delegated_charge';
+    stripeCustomerId: string;
+    stripePaymentMethodId: string;
+    /** Integer minor units — money is never a float on the wire. */
+    amountMinor: number;
+    /** Upper-case ISO-4217. */
+    currency: string;
+    /** Verification session id — the report-back key. */
+    sessionId: string | null;
+    /** The pending kya_shop_order row your report resolves. */
+    orderId: string;
+    /** Settlement spine: charge with Stripe idempotency key `voucher:<jti>`
+     * and set `metadata.jti` on the PaymentIntent. */
+    jti: string;
+    statementSuffix: string | null;
+    /** Advisory charge-by bound (ISO); stuck orders are ops-swept after it. */
+    expiresAt: string;
+}
+/**
+ * 5.6.0 (astra-pay): fulfilment contact block. `emailSource` is an OPEN union
+ * (same rule as settlement statuses): treat unknown sources like
+ * 'agent_provided' — the email is still the one to use.
+ */
+interface FulfilmentInfo {
+    /** Canonicalized (trimmed, lower-cased) receipt/delivery email. */
+    email: string;
+    /** 'agent_provided' = the agent passed buyerEmail on this confirm;
+     * 'account' = platform default — the buyer's account email. */
+    emailSource: 'agent_provided' | 'account' | (string & {});
+}
 /**
  * 5.3.0 (astra-pay): sanitized outcome of first-party charge-at-redeem
  * settlement. Carries NO voucher/instrument material — the settlement channel
@@ -668,9 +729,16 @@ interface VerificationResult {
  * approves, the platform re-drives the confirm with the SAME
  * checkoutSessionId and that re-drive carries the settling outcome
  * (one order row per session — the re-drive claims the same row).
+ *
+ * 5.5.0: OPEN union — the platform may introduce statuses (e.g.
+ * `pending_merchant` for self-settling merchants) ahead of your SDK version.
+ * Rule: treat any status you don't recognize as PENDING, never as failed.
+ * Also 5.5.0: `no_instrument` on a held/approved session is NON-terminal —
+ * the human's approval is NOT consumed; a re-drive with the same
+ * checkoutSessionId settles once a card is on file.
  */
 interface SettlementOutcomeInfo {
-    status: 'settled' | 'failed' | 'requires_action' | 'no_instrument' | 'requires_approval';
+    status: 'settled' | 'failed' | 'requires_action' | 'no_instrument' | 'requires_approval' | 'pending_merchant' | (string & {});
     /** First-party order id — the buyer sees the purchase in their AstraSync
      * dashboard orders view (no public receipt page). */
     orderId?: string;
@@ -760,6 +828,15 @@ interface VerificationRequest {
             currency: string;
         };
     }>;
+    /**
+     * 5.6.0 (astra-pay): buyer's receipt/delivery email, forwarded on the
+     * confirm leg only. TRANSIT-ONLY fulfilment PII — the platform echoes it
+     * back (canonicalized) in `VerificationResult.fulfilment` for first-party
+     * merchants and never persists it. When omitted, the platform defaults
+     * `fulfilment.email` to the buyer's account email, so supplying this is
+     * only needed for an alternate contact (gift delivery etc.).
+     */
+    buyerEmail?: string;
     /** Whether this is a sub-agent request */
     isSubAgentRequest?: boolean;
     /** Parent agent ID for sub-agent requests */
@@ -1685,6 +1762,21 @@ declare class VerificationGatewayClient {
      * settled/failed/requires_action/no_instrument outcome (+ `orderId`), and the
      * identity/policy/`failures` fields for a denial. On any non-`confirm`/first-
      * party path `settlementOutcome` is simply absent — no money moves.
+     *
+     * 5.5.0 self-settling merchants (settlement_mode='self_settle'): the result
+     * carries `.settlementToken` instead of a completed charge. Charge on your
+     * own integration with Stripe idempotency key `voucher:<token.jti>` and
+     * `metadata: { jti: token.jti, sessionId: token.sessionId }`, then call
+     * `reportSettlement()` with the outcome. Treat any `settlementOutcome.status`
+     * you don't recognize (e.g. `pending_merchant`) as PENDING, never failed.
+     *
+     * 5.6.0 fulfilment contact: first-party confirm results carry
+     * `.fulfilment { email, emailSource }` — the buyer's receipt/delivery
+     * email. You always get one: the platform defaults to the buyer's account
+     * email when no `buyerEmail` was passed. Store it with the pending order;
+     * fulfil against it only once the order is settled / pending_merchant. An
+     * explicit `buyerEmail` (here or on the bridge handoff body) wins over the
+     * account default.
      */
     confirmCheckout(options: {
         astraId?: string;
@@ -1696,9 +1788,34 @@ declare class VerificationGatewayClient {
         currency?: string;
         checkoutSessionId?: string;
         checkoutItems?: VerificationRequest['checkoutItems'];
+        /** 5.6.0: alternate receipt/delivery email (transit-only) — omit to let
+         * the platform default `fulfilment.email` to the buyer's account email. */
+        buyerEmail?: string;
         counterpartyUrl?: string;
         counterpartyType?: string;
     }): Promise<VerificationResult>;
+    /**
+     * 5.5.0 (astra-pay): report a self-settled charge outcome back to the
+     * platform — the other half of the `settlementToken` contract. Call after
+     * your PaymentIntent reaches a terminal state so the buyer's dashboard,
+     * /orders and the agent's poll surface reconcile. Authenticated with this
+     * client's api key (must be the merchant's own). Amounts must match the
+     * order EXACTLY (integer minor units) or the report is rejected whole
+     * (409 amount_mismatch). Replays of the same terminal state are safe.
+     */
+    reportSettlement(options: {
+        sessionId: string;
+        status: 'settled' | 'declined' | 'failed';
+        amountMinor: number;
+        currency: string;
+        /** Stripe PaymentIntent id — REQUIRED when status is 'settled'. */
+        processorRef?: string;
+        failureCode?: string;
+    }): Promise<{
+        orderId: string;
+        status: string;
+        alreadySettled?: boolean;
+    }>;
     /**
      * Quick verification — checks credentials and policy in one call.
      *
@@ -4641,7 +4758,7 @@ declare function detectRuntime(userAgent: string | undefined | null): string | u
  * silently (never throwing), so this is a no-op there — which is correct:
  * in a browser the page's real UA is the honest identity.
  */
-declare const SDK_USER_AGENT = "astrasync-sdk/5.4.1";
+declare const SDK_USER_AGENT = "astrasync-sdk/5.6.0";
 declare const sdkFetch: typeof fetch;
 
 /**
@@ -4662,6 +4779,6 @@ declare const sdkFetch: typeof fetch;
  * is fine — bumping both in the release-ceremony commit keeps them
  * lockstep.
  */
-declare const SDK_VERSION = "5.4.1";
+declare const SDK_VERSION = "5.6.0";
 
-export { AgentClient, type AgentCredentials, type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DEFAULT_EDGE_CONFIG, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FiatSettlementBinding, type FrameworkConfig, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, KYDRequiredError, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, type ModelConfig, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type RouteAccessConfig, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, type SettlementRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, _resetEdgeConfigCache, index as agent, authorizeSettlement, awaitStepUpApproval, buildGuidance, buildSdkObservedMetadata, clearCache, createMcpMiddleware, degradeToObserve, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, express, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, isEdgeConfig, isVerifiedHopValidFor, matchEdgePathRule, matchPlatformSignature, nextjs, parseVerifiedHop, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, sanitizeHeaders, sdk, sdkFetch, serializeVerifiedHop, setMcpMeta, index$1 as transport, verify };
+export { AgentClient, type AgentCredentials, type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DEFAULT_EDGE_CONFIG, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FiatSettlementBinding, type FrameworkConfig, type FulfilmentInfo, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, KYDRequiredError, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, type MerchantSettlementToken, type ModelConfig, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type RouteAccessConfig, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, type SettlementRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, _resetEdgeConfigCache, index as agent, authorizeSettlement, awaitStepUpApproval, buildGuidance, buildSdkObservedMetadata, clearCache, createMcpMiddleware, degradeToObserve, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, express, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, isEdgeConfig, isVerifiedHopValidFor, matchEdgePathRule, matchPlatformSignature, nextjs, parseVerifiedHop, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, sanitizeHeaders, sdk, sdkFetch, serializeVerifiedHop, setMcpMeta, index$1 as transport, verify };

package/dist/index.d.ts

@@ -653,11 +653,72 @@ interface VerificationResult {
      * instrument on file (steer the user to add one via onboarding).
      */
     settlementOutcome?: SettlementOutcomeInfo;
+    /**
+     * 5.5.0 (astra-pay): interim merchant self-settlement token. Present ONLY
+     * for firstParty merchants opted into settlement_mode='self_settle' on the
+     * confirm leg — YOUR server charges with this material on the shared Stripe
+     * account and reports the outcome via `client.reportSettlement()`.
+     * MERCHANT-ONLY lane: never expose it to the agent plane, never log it,
+     * never echo it back over the bridge handoff (the bridge strips it
+     * defensively). Charge with idempotency key `voucher:<jti>` and
+     * `metadata.jti` — that lets the platform webhook auto-reconcile even if
+     * your report never arrives.
+     */
+    settlementToken?: MerchantSettlementToken;
+    /**
+     * 5.6.0 (astra-pay): fulfilment contact for first-party confirm legs.
+     * The platform always resolves an email for the merchant — the agent's
+     * `buyerEmail` when one was supplied, else the buyer's account email
+     * (`emailSource` says which). Present on every first-party confirm leg that
+     * progressed (settled, pending_merchant, held, requires_action) so it can be
+     * stored with a pending order; only FULFIL against it once the order is
+     * settled / pending_merchant. MERCHANT-ONLY lane like `settlementToken` —
+     * the bridge strips it from the agent plane. An explicit `buyerEmail` on the
+     * confirm handoff body wins over `fulfilment.email` (the platform default).
+     */
+    fulfilment?: FulfilmentInfo;
     /** Timestamp of verification */
     verifiedAt: Date;
     /** TTL for this result (seconds) */
     cacheTtl?: number;
 }
+/**
+ * 5.5.0 (astra-pay): agent-blind settlement token for self-settling
+ * first-party merchants. Self-describing via `type`, so a Stripe Shared
+ * Payment Token can replace the raw customer/payment-method pair without a
+ * contract change.
+ */
+interface MerchantSettlementToken {
+    type: 'stripe_delegated_charge';
+    stripeCustomerId: string;
+    stripePaymentMethodId: string;
+    /** Integer minor units — money is never a float on the wire. */
+    amountMinor: number;
+    /** Upper-case ISO-4217. */
+    currency: string;
+    /** Verification session id — the report-back key. */
+    sessionId: string | null;
+    /** The pending kya_shop_order row your report resolves. */
+    orderId: string;
+    /** Settlement spine: charge with Stripe idempotency key `voucher:<jti>`
+     * and set `metadata.jti` on the PaymentIntent. */
+    jti: string;
+    statementSuffix: string | null;
+    /** Advisory charge-by bound (ISO); stuck orders are ops-swept after it. */
+    expiresAt: string;
+}
+/**
+ * 5.6.0 (astra-pay): fulfilment contact block. `emailSource` is an OPEN union
+ * (same rule as settlement statuses): treat unknown sources like
+ * 'agent_provided' — the email is still the one to use.
+ */
+interface FulfilmentInfo {
+    /** Canonicalized (trimmed, lower-cased) receipt/delivery email. */
+    email: string;
+    /** 'agent_provided' = the agent passed buyerEmail on this confirm;
+     * 'account' = platform default — the buyer's account email. */
+    emailSource: 'agent_provided' | 'account' | (string & {});
+}
 /**
  * 5.3.0 (astra-pay): sanitized outcome of first-party charge-at-redeem
  * settlement. Carries NO voucher/instrument material — the settlement channel
@@ -668,9 +729,16 @@ interface VerificationResult {
  * approves, the platform re-drives the confirm with the SAME
  * checkoutSessionId and that re-drive carries the settling outcome
  * (one order row per session — the re-drive claims the same row).
+ *
+ * 5.5.0: OPEN union — the platform may introduce statuses (e.g.
+ * `pending_merchant` for self-settling merchants) ahead of your SDK version.
+ * Rule: treat any status you don't recognize as PENDING, never as failed.
+ * Also 5.5.0: `no_instrument` on a held/approved session is NON-terminal —
+ * the human's approval is NOT consumed; a re-drive with the same
+ * checkoutSessionId settles once a card is on file.
  */
 interface SettlementOutcomeInfo {
-    status: 'settled' | 'failed' | 'requires_action' | 'no_instrument' | 'requires_approval';
+    status: 'settled' | 'failed' | 'requires_action' | 'no_instrument' | 'requires_approval' | 'pending_merchant' | (string & {});
     /** First-party order id — the buyer sees the purchase in their AstraSync
      * dashboard orders view (no public receipt page). */
     orderId?: string;
@@ -760,6 +828,15 @@ interface VerificationRequest {
             currency: string;
         };
     }>;
+    /**
+     * 5.6.0 (astra-pay): buyer's receipt/delivery email, forwarded on the
+     * confirm leg only. TRANSIT-ONLY fulfilment PII — the platform echoes it
+     * back (canonicalized) in `VerificationResult.fulfilment` for first-party
+     * merchants and never persists it. When omitted, the platform defaults
+     * `fulfilment.email` to the buyer's account email, so supplying this is
+     * only needed for an alternate contact (gift delivery etc.).
+     */
+    buyerEmail?: string;
     /** Whether this is a sub-agent request */
     isSubAgentRequest?: boolean;
     /** Parent agent ID for sub-agent requests */
@@ -1685,6 +1762,21 @@ declare class VerificationGatewayClient {
      * settled/failed/requires_action/no_instrument outcome (+ `orderId`), and the
      * identity/policy/`failures` fields for a denial. On any non-`confirm`/first-
      * party path `settlementOutcome` is simply absent — no money moves.
+     *
+     * 5.5.0 self-settling merchants (settlement_mode='self_settle'): the result
+     * carries `.settlementToken` instead of a completed charge. Charge on your
+     * own integration with Stripe idempotency key `voucher:<token.jti>` and
+     * `metadata: { jti: token.jti, sessionId: token.sessionId }`, then call
+     * `reportSettlement()` with the outcome. Treat any `settlementOutcome.status`
+     * you don't recognize (e.g. `pending_merchant`) as PENDING, never failed.
+     *
+     * 5.6.0 fulfilment contact: first-party confirm results carry
+     * `.fulfilment { email, emailSource }` — the buyer's receipt/delivery
+     * email. You always get one: the platform defaults to the buyer's account
+     * email when no `buyerEmail` was passed. Store it with the pending order;
+     * fulfil against it only once the order is settled / pending_merchant. An
+     * explicit `buyerEmail` (here or on the bridge handoff body) wins over the
+     * account default.
      */
     confirmCheckout(options: {
         astraId?: string;
@@ -1696,9 +1788,34 @@ declare class VerificationGatewayClient {
         currency?: string;
         checkoutSessionId?: string;
         checkoutItems?: VerificationRequest['checkoutItems'];
+        /** 5.6.0: alternate receipt/delivery email (transit-only) — omit to let
+         * the platform default `fulfilment.email` to the buyer's account email. */
+        buyerEmail?: string;
         counterpartyUrl?: string;
         counterpartyType?: string;
     }): Promise<VerificationResult>;
+    /**
+     * 5.5.0 (astra-pay): report a self-settled charge outcome back to the
+     * platform — the other half of the `settlementToken` contract. Call after
+     * your PaymentIntent reaches a terminal state so the buyer's dashboard,
+     * /orders and the agent's poll surface reconcile. Authenticated with this
+     * client's api key (must be the merchant's own). Amounts must match the
+     * order EXACTLY (integer minor units) or the report is rejected whole
+     * (409 amount_mismatch). Replays of the same terminal state are safe.
+     */
+    reportSettlement(options: {
+        sessionId: string;
+        status: 'settled' | 'declined' | 'failed';
+        amountMinor: number;
+        currency: string;
+        /** Stripe PaymentIntent id — REQUIRED when status is 'settled'. */
+        processorRef?: string;
+        failureCode?: string;
+    }): Promise<{
+        orderId: string;
+        status: string;
+        alreadySettled?: boolean;
+    }>;
     /**
      * Quick verification — checks credentials and policy in one call.
      *
@@ -4641,7 +4758,7 @@ declare function detectRuntime(userAgent: string | undefined | null): string | u
  * silently (never throwing), so this is a no-op there — which is correct:
  * in a browser the page's real UA is the honest identity.
  */
-declare const SDK_USER_AGENT = "astrasync-sdk/5.4.1";
+declare const SDK_USER_AGENT = "astrasync-sdk/5.6.0";
 declare const sdkFetch: typeof fetch;
 
 /**
@@ -4662,6 +4779,6 @@ declare const sdkFetch: typeof fetch;
  * is fine — bumping both in the release-ceremony commit keeps them
  * lockstep.
  */
-declare const SDK_VERSION = "5.4.1";
+declare const SDK_VERSION = "5.6.0";
 
-export { AgentClient, type AgentCredentials, type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DEFAULT_EDGE_CONFIG, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FiatSettlementBinding, type FrameworkConfig, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, KYDRequiredError, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, type ModelConfig, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type RouteAccessConfig, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, type SettlementRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, _resetEdgeConfigCache, index as agent, authorizeSettlement, awaitStepUpApproval, buildGuidance, buildSdkObservedMetadata, clearCache, createMcpMiddleware, degradeToObserve, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, express, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, isEdgeConfig, isVerifiedHopValidFor, matchEdgePathRule, matchPlatformSignature, nextjs, parseVerifiedHop, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, sanitizeHeaders, sdk, sdkFetch, serializeVerifiedHop, setMcpMeta, index$1 as transport, verify };
+export { AgentClient, type AgentCredentials, type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DEFAULT_EDGE_CONFIG, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FiatSettlementBinding, type FrameworkConfig, type FulfilmentInfo, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, KYDRequiredError, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, type MerchantSettlementToken, type ModelConfig, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type RouteAccessConfig, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, type SettlementRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, _resetEdgeConfigCache, index as agent, authorizeSettlement, awaitStepUpApproval, buildGuidance, buildSdkObservedMetadata, clearCache, createMcpMiddleware, degradeToObserve, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, express, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, isEdgeConfig, isVerifiedHopValidFor, matchEdgePathRule, matchPlatformSignature, nextjs, parseVerifiedHop, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, sanitizeHeaders, sdk, sdkFetch, serializeVerifiedHop, setMcpMeta, index$1 as transport, verify };

package/dist/index.js

@@ -112,7 +112,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "5.4.1";
+var SDK_VERSION = "5.6.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -475,6 +475,7 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.commercePhase) body.commercePhase = requestData.commercePhase;
   if (requestData.checkoutSessionId) body.checkoutSessionId = requestData.checkoutSessionId;
   if (requestData.checkoutItems) body.checkoutItems = requestData.checkoutItems;
+  if (requestData.buyerEmail) body.buyerEmail = requestData.buyerEmail;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
   if (requestData.attemptId) body.attemptId = requestData.attemptId;
   if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
@@ -647,7 +648,12 @@ async function verify(config, request, options) {
       recommendationReasons: apiResponse.recommendationReasons,
       stepUpApproval: apiResponse.stepUpApproval,
       settlement: apiResponse.settlement,
-      settlementOutcome: apiResponse.settlementOutcome
+      settlementOutcome: apiResponse.settlementOutcome,
+      // 5.5.0 self-settlement: merchant-only material — passes through to the
+      // MERCHANT caller only (bridge callers strip it before the agent plane).
+      settlementToken: apiResponse.settlementToken,
+      // 5.6.0: fulfilment contact — merchant-only lane, same strip rule.
+      fulfilment: apiResponse.fulfilment
     };
     return result2;
   }
@@ -705,7 +711,10 @@ async function verify(config, request, options) {
     warningHeader: apiResponse.warningHeader,
     stepUpApproval: apiResponse.stepUpApproval,
     settlement: apiResponse.settlement,
-    settlementOutcome: apiResponse.settlementOutcome
+    settlementOutcome: apiResponse.settlementOutcome,
+    settlementToken: apiResponse.settlementToken,
+    // 5.6.0: fulfilment contact — merchant-only lane, same strip rule.
+    fulfilment: apiResponse.fulfilment
   };
   if (result.recommendation === "deny") {
     result.policyAllowed = false;
@@ -2737,6 +2746,21 @@ var VerificationGatewayClient = class {
    * settled/failed/requires_action/no_instrument outcome (+ `orderId`), and the
    * identity/policy/`failures` fields for a denial. On any non-`confirm`/first-
    * party path `settlementOutcome` is simply absent — no money moves.
+   *
+   * 5.5.0 self-settling merchants (settlement_mode='self_settle'): the result
+   * carries `.settlementToken` instead of a completed charge. Charge on your
+   * own integration with Stripe idempotency key `voucher:<token.jti>` and
+   * `metadata: { jti: token.jti, sessionId: token.sessionId }`, then call
+   * `reportSettlement()` with the outcome. Treat any `settlementOutcome.status`
+   * you don't recognize (e.g. `pending_merchant`) as PENDING, never failed.
+   *
+   * 5.6.0 fulfilment contact: first-party confirm results carry
+   * `.fulfilment { email, emailSource }` — the buyer's receipt/delivery
+   * email. You always get one: the platform defaults to the buyer's account
+   * email when no `buyerEmail` was passed. Store it with the pending order;
+   * fulfil against it only once the order is settled / pending_merchant. An
+   * explicit `buyerEmail` (here or on the bridge handoff body) wins over the
+   * account default.
    */
   async confirmCheckout(options) {
     const credentials = {
@@ -2756,6 +2780,7 @@ var VerificationGatewayClient = class {
           commercePhase: "confirm",
           checkoutSessionId: options.checkoutSessionId,
           checkoutItems: options.checkoutItems,
+          buyerEmail: options.buyerEmail,
           counterpartyUrl: options.counterpartyUrl,
           counterpartyType: options.counterpartyType
         },
@@ -2766,6 +2791,32 @@ var VerificationGatewayClient = class {
       )
     );
   }
+  /**
+   * 5.5.0 (astra-pay): report a self-settled charge outcome back to the
+   * platform — the other half of the `settlementToken` contract. Call after
+   * your PaymentIntent reaches a terminal state so the buyer's dashboard,
+   * /orders and the agent's poll surface reconcile. Authenticated with this
+   * client's api key (must be the merchant's own). Amounts must match the
+   * order EXACTLY (integer minor units) or the report is rejected whole
+   * (409 amount_mismatch). Replays of the same terminal state are safe.
+   */
+  async reportSettlement(options) {
+    const base = this.config.apiBaseUrl.replace(/\/+$/, "");
+    const res = await sdkFetch(`${base}/merchant/settlements/report`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        // Same auth pair as every backend call the SDK makes (verify.ts).
+        ...this.config.apiKey ? { Authorization: `Bearer ${this.config.apiKey}`, "X-API-Key": this.config.apiKey } : {}
+      },
+      body: JSON.stringify(options)
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok || !json.success || !json.data) {
+      throw new Error(`reportSettlement failed (${res.status}): ${json.error ?? "unknown error"}`);
+    }
+    return json.data;
+  }
   /**
    * Quick verification — checks credentials and policy in one call.
    *