@astrasyncai/verification-gateway 5.18.0 → 5.19.0

package/dist/adapters/sdk.d.mts

@@ -1,4 +1,4 @@
-import { T as TrustLevel, S as SDKOptions, d as VerificationResult, c as VerificationRequest } from '../types-Cns4l8gX.mjs';
+import { T as TrustLevel, S as SDKOptions, e as VerificationResult, d as VerificationRequest, A as AgentArtifacts, C as CheckoutMetadata } from '../types-DqWPkiYl.mjs';
 
 /**
  * AstraSync Universal Verification Gateway — Trust Level helpers.
@@ -68,6 +68,37 @@ declare class VerificationGatewayClient {
         subAgentDepth?: number;
         counterpartyUrl?: string;
         counterpartyType?: string;
+        /**
+         * 5.19.0: `'quote'` marks a price / limit check (peek only: no order, no
+         * approval redeemed) — prefer `quoteCheckout()`. Omitted with a
+         * `transactionValue`, the call is a PURCHASE leg (see the warning below).
+         */
+        commercePhase?: 'quote';
+    }): Promise<VerificationResult>;
+    /**
+     * 5.19.0: the QUOTE leg of a checkout — a price / limit check before the
+     * purchase. Sends `commercePhase: 'quote'`: verify-access evaluates the
+     * agent's policy at this value and tells you whether a purchase would be
+     * granted, held for the owner's approval, or denied, but records no order,
+     * moves no money and never redeems an approval. Always reaches the backend
+     * (no verdict cache).
+     *
+     * Quotes count toward limit-probing detection: a run of rising quotes is
+     * how an agent (or a merchant) maps a spending limit. Quote what the buyer
+     * asked for, not a ladder of values.
+     */
+    quoteCheckout(options: {
+        astraId?: string;
+        apiKey?: string;
+        jwt?: string;
+        purpose?: string;
+        action?: string;
+        transactionValue?: number;
+        currency?: string;
+        checkoutSessionId?: string;
+        attemptId?: string;
+        counterpartyUrl?: string;
+        counterpartyType?: string;
     }): Promise<VerificationResult>;
     /**
      * 5.4.0 (astra-pay): confirm-leg of a checkout — the ONLY call that may fire
@@ -107,6 +138,14 @@ declare class VerificationGatewayClient {
      * is matched to — and only to — this confirm. A held cart's approval is
      * bound to its checkout session and exact value; a confirm for any other
      * cart is held for its own approval.
+     *
+     * 5.19.0 checkout kits: pass the kit's `agentArtifacts` (the inbound agent
+     * request — signed RFC 9421 headers with the public URL and raw-body
+     * digest, or `{ unsigned: true }`) and `metadata` (`{ kitSessionId,
+     * protocol }`) from the `verifyPurchase` context. The platform attributes
+     * the confirm to the agent from the artifacts, and stores the metadata on
+     * any approval this confirm creates so the approval event
+     * (`handleApprovalEvents`) can find the kit session.
      */
     confirmCheckout(options: {
         astraId?: string;
@@ -125,6 +164,10 @@ declare class VerificationGatewayClient {
         /** 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;
+        /** 5.19.0: the inbound agent request behind this confirm (from the kit's verifyPurchase ctx). */
+        agentArtifacts?: AgentArtifacts;
+        /** 5.19.0: `{ kitSessionId, protocol }` (from the kit's verifyPurchase ctx). */
+        metadata?: CheckoutMetadata;
         counterpartyUrl?: string;
         counterpartyType?: string;
     }): Promise<VerificationResult>;

package/dist/adapters/sdk.d.ts

@@ -1,4 +1,4 @@
-import { T as TrustLevel, S as SDKOptions, d as VerificationResult, c as VerificationRequest } from '../types-Cns4l8gX.js';
+import { T as TrustLevel, S as SDKOptions, e as VerificationResult, d as VerificationRequest, A as AgentArtifacts, C as CheckoutMetadata } from '../types-DqWPkiYl.js';
 
 /**
  * AstraSync Universal Verification Gateway — Trust Level helpers.
@@ -68,6 +68,37 @@ declare class VerificationGatewayClient {
         subAgentDepth?: number;
         counterpartyUrl?: string;
         counterpartyType?: string;
+        /**
+         * 5.19.0: `'quote'` marks a price / limit check (peek only: no order, no
+         * approval redeemed) — prefer `quoteCheckout()`. Omitted with a
+         * `transactionValue`, the call is a PURCHASE leg (see the warning below).
+         */
+        commercePhase?: 'quote';
+    }): Promise<VerificationResult>;
+    /**
+     * 5.19.0: the QUOTE leg of a checkout — a price / limit check before the
+     * purchase. Sends `commercePhase: 'quote'`: verify-access evaluates the
+     * agent's policy at this value and tells you whether a purchase would be
+     * granted, held for the owner's approval, or denied, but records no order,
+     * moves no money and never redeems an approval. Always reaches the backend
+     * (no verdict cache).
+     *
+     * Quotes count toward limit-probing detection: a run of rising quotes is
+     * how an agent (or a merchant) maps a spending limit. Quote what the buyer
+     * asked for, not a ladder of values.
+     */
+    quoteCheckout(options: {
+        astraId?: string;
+        apiKey?: string;
+        jwt?: string;
+        purpose?: string;
+        action?: string;
+        transactionValue?: number;
+        currency?: string;
+        checkoutSessionId?: string;
+        attemptId?: string;
+        counterpartyUrl?: string;
+        counterpartyType?: string;
     }): Promise<VerificationResult>;
     /**
      * 5.4.0 (astra-pay): confirm-leg of a checkout — the ONLY call that may fire
@@ -107,6 +138,14 @@ declare class VerificationGatewayClient {
      * is matched to — and only to — this confirm. A held cart's approval is
      * bound to its checkout session and exact value; a confirm for any other
      * cart is held for its own approval.
+     *
+     * 5.19.0 checkout kits: pass the kit's `agentArtifacts` (the inbound agent
+     * request — signed RFC 9421 headers with the public URL and raw-body
+     * digest, or `{ unsigned: true }`) and `metadata` (`{ kitSessionId,
+     * protocol }`) from the `verifyPurchase` context. The platform attributes
+     * the confirm to the agent from the artifacts, and stores the metadata on
+     * any approval this confirm creates so the approval event
+     * (`handleApprovalEvents`) can find the kit session.
      */
     confirmCheckout(options: {
         astraId?: string;
@@ -125,6 +164,10 @@ declare class VerificationGatewayClient {
         /** 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;
+        /** 5.19.0: the inbound agent request behind this confirm (from the kit's verifyPurchase ctx). */
+        agentArtifacts?: AgentArtifacts;
+        /** 5.19.0: `{ kitSessionId, protocol }` (from the kit's verifyPurchase ctx). */
+        metadata?: CheckoutMetadata;
         counterpartyUrl?: string;
         counterpartyType?: string;
     }): Promise<VerificationResult>;

package/dist/adapters/sdk.js

@@ -28,7 +28,7 @@ __export(sdk_exports, {
 module.exports = __toCommonJS(sdk_exports);
 
 // src/version.ts
-var SDK_VERSION = "5.18.0";
+var SDK_VERSION = "5.19.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -206,7 +206,12 @@ function getCacheKey(request, counterpartyId) {
     // its start_checkout quote was served the cached quote-leg grant (no
     // settlementOutcome) and never reached the backend. Same F-A1-07 bug class.
     request.commercePhase || "",
-    request.checkoutSessionId || ""
+    request.checkoutSessionId || "",
+    // 5.19.0: a route_config purpose claim is checked server-side against
+    // the stored rule for this method + path, so it changes the verdict.
+    request.purposeSource || "",
+    request.requestMethod || "",
+    request.requestPath || ""
   ].join("|");
 }
 function getCachedResult(request, counterpartyId) {
@@ -383,6 +388,11 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.buyerEmail) body.buyerEmail = requestData.buyerEmail;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
   if (requestData.attemptId) body.attemptId = requestData.attemptId;
+  if (requestData.purposeSource) body.purposeSource = requestData.purposeSource;
+  if (requestData.agentArtifacts) body.agentArtifacts = requestData.agentArtifacts;
+  if (requestData.metadata) body.metadata = requestData.metadata;
+  if (requestData.requestMethod) body.requestMethod = requestData.requestMethod;
+  if (requestData.requestPath) body.requestPath = requestData.requestPath;
   if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
   body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
@@ -572,9 +582,18 @@ async function verify(config, request, options) {
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
     const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true && !aggregatedFailures?.some((f) => REJECTED_IDENTITY_DIMENSIONS.has(f.dimension));
+    const denyAgent = idVerifiedFromBackend && apiResponse.agent ? {
+      astraId: apiResponse.agent.astraId,
+      name: apiResponse.agent.name,
+      trustScore: apiResponse.agent.trustScore,
+      trustLevel: getTrustLevel(apiResponse.agent.trustScore),
+      blockchainAnchored: apiResponse.agent.blockchainStatus === "anchored",
+      status: apiResponse.agent.agentStatus
+    } : void 0;
     const result2 = {
       identityVerified: idVerifiedFromBackend,
       policyAllowed: false,
+      ...denyAgent && { agent: denyAgent },
       // 3.6.0: the server now emits top-level denialReasons on every deny
       // path — prefer it verbatim; the failure-message reconstruction remains
       // as the fallback for older backends.
@@ -745,6 +764,7 @@ var SettlementReportError = class extends AstraSyncError {
 };
 
 // src/adapters/sdk.ts
+var warnedPhaselessValue = false;
 var VerificationGatewayClient = class {
   constructor(options) {
     this.config = {
@@ -776,9 +796,16 @@ var VerificationGatewayClient = class {
       apiKey: options.apiKey,
       jwt: options.jwt
     };
+    if (options.transactionValue && !options.commercePhase && !warnedPhaselessValue) {
+      warnedPhaselessValue = true;
+      console.warn(
+        "[astrasync] verify() with a transactionValue and no commercePhase is a purchase leg: it records a pending order and redeems a matching owner approval. Use quoteCheckout() for a price / limit check (commercePhase 'quote') and confirmCheckout() for the purchase. The default becomes 'quote' in 6.0."
+      );
+    }
     return this.executeWithRetry(
       () => verify(this.config, {
         credentials,
+        ...options.commercePhase && { commercePhase: options.commercePhase },
         purpose: options.purpose,
         action: options.action,
         resourceType: options.resourceType,
@@ -794,6 +821,43 @@ var VerificationGatewayClient = class {
       })
     );
   }
+  /**
+   * 5.19.0: the QUOTE leg of a checkout — a price / limit check before the
+   * purchase. Sends `commercePhase: 'quote'`: verify-access evaluates the
+   * agent's policy at this value and tells you whether a purchase would be
+   * granted, held for the owner's approval, or denied, but records no order,
+   * moves no money and never redeems an approval. Always reaches the backend
+   * (no verdict cache).
+   *
+   * Quotes count toward limit-probing detection: a run of rising quotes is
+   * how an agent (or a merchant) maps a spending limit. Quote what the buyer
+   * asked for, not a ladder of values.
+   */
+  async quoteCheckout(options) {
+    const credentials = {
+      astraId: options.astraId,
+      apiKey: options.apiKey,
+      jwt: options.jwt
+    };
+    return this.executeWithRetry(
+      () => verify(
+        this.config,
+        {
+          credentials,
+          purpose: options.purpose ?? "shopping",
+          action: options.action ?? "shopping.purchase",
+          transactionValue: options.transactionValue,
+          currency: options.currency,
+          commercePhase: "quote",
+          ...options.checkoutSessionId && { checkoutSessionId: options.checkoutSessionId },
+          ...options.attemptId && { attemptId: options.attemptId },
+          counterpartyUrl: options.counterpartyUrl,
+          counterpartyType: options.counterpartyType
+        },
+        { bypassCache: true }
+      )
+    );
+  }
   /**
    * 5.4.0 (astra-pay): confirm-leg of a checkout — the ONLY call that may fire
    * first-party charge-at-redeem (server-side settlement on the owner's saved
@@ -832,6 +896,14 @@ var VerificationGatewayClient = class {
    * is matched to — and only to — this confirm. A held cart's approval is
    * bound to its checkout session and exact value; a confirm for any other
    * cart is held for its own approval.
+   *
+   * 5.19.0 checkout kits: pass the kit's `agentArtifacts` (the inbound agent
+   * request — signed RFC 9421 headers with the public URL and raw-body
+   * digest, or `{ unsigned: true }`) and `metadata` (`{ kitSessionId,
+   * protocol }`) from the `verifyPurchase` context. The platform attributes
+   * the confirm to the agent from the artifacts, and stores the metadata on
+   * any approval this confirm creates so the approval event
+   * (`handleApprovalEvents`) can find the kit session.
    */
   async confirmCheckout(options) {
     const credentials = {
@@ -854,6 +926,8 @@ var VerificationGatewayClient = class {
           ...options.checkoutJwt && { checkoutJwt: options.checkoutJwt },
           ...options.attemptId && { attemptId: options.attemptId },
           buyerEmail: options.buyerEmail,
+          ...options.agentArtifacts && { agentArtifacts: options.agentArtifacts },
+          ...options.metadata && { metadata: options.metadata },
           counterpartyUrl: options.counterpartyUrl,
           counterpartyType: options.counterpartyType
         },