@astrasyncai/verification-gateway 5.4.2 → 5.6.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-BU04qAAR.mjs';
+import { T as TrustLevel, S as SDKOptions, d as VerificationResult, c as VerificationRequest } from '../types-BK_pRNSs.mjs';
 
 /**
  * AstraSync Universal Verification Gateway — Trust Level helpers.
@@ -86,6 +86,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;
@@ -97,9 +112,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.
      *

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-BU04qAAR.js';
+import { T as TrustLevel, S as SDKOptions, d as VerificationResult, c as VerificationRequest } from '../types-BK_pRNSs.js';
 
 /**
  * AstraSync Universal Verification Gateway — Trust Level helpers.
@@ -86,6 +86,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;
@@ -97,9 +112,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.
      *

package/dist/adapters/sdk.js

@@ -28,7 +28,7 @@ __export(sdk_exports, {
 module.exports = __toCommonJS(sdk_exports);
 
 // 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}`;
@@ -310,6 +310,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;
@@ -482,7 +483,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;
   }
@@ -540,7 +546,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;
@@ -643,6 +652,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 = {
@@ -662,6 +686,7 @@ var VerificationGatewayClient = class {
           commercePhase: "confirm",
           checkoutSessionId: options.checkoutSessionId,
           checkoutItems: options.checkoutItems,
+          buyerEmail: options.buyerEmail,
           counterpartyUrl: options.counterpartyUrl,
           counterpartyType: options.counterpartyType
         },
@@ -672,6 +697,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.
    *