@agent-cards/checkout 0.15.0 → 0.15.1

package/dist/client.d.ts

@@ -527,8 +527,15 @@ export declare class VaultClient {
      * exchange rather than each minting their own token.
      */
     private accessToken;
-    /** Authenticated request that retries ONCE on a 401 with a fresh token. */
+    /**
+     * A preparation status read may retry two known connection failures, after
+     * 250ms and 500ms, while keeping its original approval deadline and signal.
+     * Only fetch and a successful response's body read belong to that retry:
+     * OAuth, HTTP errors, invalid JSON and every mutation remain outside it.
+     * The existing one-time 401 refresh carries the remaining read budget.
+     */
     private call;
     private post;
     private get;
+    private readPreparation;
 }

package/dist/client.js

@@ -354,6 +354,17 @@ export function redactUrl(raw) {
 }
 /** Default backoff for a 502 amount_unverifiable at create: two retries, then give up. */
 const UNVERIFIABLE_RETRY_DELAYS_MS = [500, 1500];
+const PREPARATION_READ_RETRY_DELAYS_MS = [250, 500];
+const TRANSIENT_READ_NETWORK_CODES = new Set([
+    'ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ETIMEDOUT', 'EAI_AGAIN',
+    'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT',
+]);
+function transientReadNetworkError(error) {
+    if (!(error instanceof Error) || error.name === 'AbortError' || error.name === 'TimeoutError' || error instanceof SyntaxError)
+        return false;
+    const code = error.cause?.code ?? error.code;
+    return typeof code === 'string' && TRANSIENT_READ_NETWORK_CODES.has(code);
+}
 export class VaultClient {
     opts;
     baseUrl;
@@ -460,7 +471,7 @@ export class VaultClient {
             }
             catch { /* observer only */ }
             while (!signal.aborted) {
-                const state = await this.get(`/v2/checkout/preparations/${id}`, signal);
+                const state = await this.readPreparation(id, signal);
                 if (signal.aborted)
                     throw fail('cancelled', id);
                 if (state?.id !== id)
@@ -1023,30 +1034,49 @@ export class VaultClient {
         })().finally(() => { this.inflight = null; });
         return this.inflight;
     }
-    /** Authenticated request that retries ONCE on a 401 with a fresh token. */
-    async call(path, init = {}, retried = false, stopNewRequests) {
+    /**
+     * A preparation status read may retry two known connection failures, after
+     * 250ms and 500ms, while keeping its original approval deadline and signal.
+     * Only fetch and a successful response's body read belong to that retry:
+     * OAuth, HTTP errors, invalid JSON and every mutation remain outside it.
+     * The existing one-time 401 refresh carries the remaining read budget.
+     */
+    async call(path, init = {}, retried = false, stopNewRequests, preparationReadAttempt) {
         const signal = init.signal ?? AbortSignal.timeout(30_000);
         const token = await withSignal(this.accessToken(), signal);
         // Auth can outlive the merchant request. Stop a create that has not left
         // yet, while preserving the response of one already sent for cleanup.
         if (stopNewRequests?.aborted)
             throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-        signal.throwIfAborted();
-        const r = await withSignal(this.fetch(`${this.baseUrl}${path}`, {
-            ...init,
-            signal,
-            headers: { ...(init.headers ?? {}), authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-        }), signal);
-        // A token can be revoked or expire early; one forced refresh, then give up.
-        if (r.status === 401 && !retried) {
-            if (stopNewRequests?.aborted)
-                throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-            await withSignal(this.accessToken(true), signal);
-            return this.call(path, { ...init, signal }, true, stopNewRequests);
-        }
-        if (!r.ok)
+        for (;;) {
+            signal.throwIfAborted();
+            let r;
+            try {
+                r = await withSignal(this.fetch(`${this.baseUrl}${path}`, {
+                    ...init,
+                    signal,
+                    headers: { ...(init.headers ?? {}), authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+                }), signal);
+                if (r.ok)
+                    return await withSignal(r.json(), signal);
+            }
+            catch (error) {
+                const delay = preparationReadAttempt === undefined ? undefined : PREPARATION_READ_RETRY_DELAYS_MS[preparationReadAttempt];
+                if (signal.aborted || preparationReadAttempt === undefined || delay === undefined || !transientReadNetworkError(error))
+                    throw error;
+                preparationReadAttempt++;
+                await interruptibleSleep(delay, signal);
+                continue;
+            }
+            // A token can be revoked or expire early; one forced refresh, then give up.
+            if (r.status === 401 && !retried) {
+                if (stopNewRequests?.aborted)
+                    throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
+                await withSignal(this.accessToken(true), signal);
+                return this.call(path, { ...init, signal }, true, stopNewRequests, preparationReadAttempt);
+            }
             throw new CheckoutApiError(r.status, path, await withSignal(r.text(), signal));
-        return withSignal(r.json(), signal);
+        }
     }
     post(path, body, signal, stopNewRequests) {
         return this.call(path, { method: 'POST', body: JSON.stringify(body), signal }, false, stopNewRequests);
@@ -1054,6 +1084,9 @@ export class VaultClient {
     get(path, signal) {
         return this.call(path, { signal });
     }
+    readPreparation(id, signal) {
+        return this.call(`/v2/checkout/preparations/${id}`, { signal }, false, undefined, 0);
+    }
 }
 function executionMetadata(state, authorizationId, previous = {}) {
     if (state.execution_mode === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",