reqon-dsl 0.3.0 → 0.4.0

package/dist/interpreter/fetch-handler.d.ts

@@ -18,6 +18,35 @@ export interface FetchHandlerDeps {
     log: (message: string) => void;
     /** Optional event emitter for observability */
     emit?: <T>(type: EventType, payload: T) => void;
+    /**
+     * When set (durable mode), mutating requests carry a stable Idempotency-Key
+     * derived from (executionId, stepId, request signature) so retries and
+     * replays don't double-apply server-side where the API honours the header.
+     */
+    idempotency?: {
+        executionId: string;
+        stepId: string;
+    };
+    /**
+     * Resumable (backfill) pagination, wired in durable mode. `resume` seeds the
+     * starting page/cursor from the folded log; `onPage` records each completed
+     * page back to the log; `maxItemsPerRun` bounds memory per run (a backfill
+     * that exceeds it stops cleanly and continues on the next resume).
+     */
+    pagination?: {
+        resume?: {
+            page: number;
+            cursor?: string;
+            done: boolean;
+        };
+        onPage?: (progress: {
+            page: number;
+            cursor?: string;
+            recordCount: number;
+            done: boolean;
+        }) => Promise<void>;
+        maxItemsPerRun?: number;
+    };
 }
 export interface FetchResult {
     data: unknown;
@@ -38,9 +67,18 @@ export declare class FetchHandler {
     /**
      * Record a sync checkpoint after successful fetch.
      */
-    recordCheckpoint(key: string, step: FetchStep, data: unknown): Promise<void>;
+    recordCheckpoint(key: string, step: FetchStep, data: unknown, fallbackTime?: Date): Promise<Date | undefined>;
     private resolveFetchTarget;
     private resolveSinceParams;
+    /**
+     * Idempotency-Key header for a mutating request, when durable mode is on.
+     *
+     * GET is safe and gets no key. The key is a hash of
+     * (executionId, stepId, method, path, body) so it is stable across retries
+     * and replays of the same request, yet distinct per loop iteration (different
+     * path/body) — letting a cooperating API dedupe re-issued effects.
+     */
+    private idempotencyKeyFor;
     private executePaginated;
     private countRecords;
     private validateOASResponse;

package/dist/interpreter/fetch-handler.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { evaluate, interpolatePath } from './evaluator.js';
 import { resolveOperation, getResponseSchema, validateResponse, generateMockData, } from '../oas/index.js';
 import { generateCheckpointKey, formatSinceDate } from '../sync/index.js';
@@ -5,6 +6,12 @@ import { extractNestedValue } from '../utils/path.js';
 import { createPaginationStrategy } from './pagination.js';
 /** Maximum pages to fetch to prevent infinite loops */
 const MAX_PAGINATION_PAGES = 100;
+/**
+ * Maximum items to accumulate in memory across all pages. Results are buffered
+ * in one array (no per-page streaming yet), so this caps memory regardless of
+ * page size. Hitting it stops pagination with a warning.
+ */
+const MAX_PAGINATION_ITEMS = 100_000;
 /**
  * Handles HTTP fetch operations including pagination and incremental sync.
  * Extracted from MissionExecutor for better separation of concerns.
@@ -52,12 +59,14 @@ export class FetchHandler {
                 pagesFetched = Array.isArray(result) ? undefined : 1; // Will be set by executePaginated
             }
             else {
+                const body = step.body ? evaluate(step.body, this.deps.ctx) : undefined;
                 const response = await client.request({
                     method: resolved.method,
                     path: resolved.path,
                     query: Object.keys(sinceQuery).length > 0 ? sinceQuery : undefined,
                     headers: Object.keys(sinceHeaders).length > 0 ? sinceHeaders : undefined,
-                    body: step.body ? evaluate(step.body, this.deps.ctx) : undefined,
+                    body,
+                    idempotencyKey: this.idempotencyKeyFor(resolved.method, resolved.path, body),
                 }, step.retry);
                 await this.validateOASResponse(resolved.sourceName, resolved.operationId, response.data);
                 data = response.data;
@@ -100,10 +109,13 @@ export class FetchHandler {
     /**
      * Record a sync checkpoint after successful fetch.
      */
-    async recordCheckpoint(key, step, data) {
+    async recordCheckpoint(key, step, data, fallbackTime) {
         if (!this.deps.syncStore)
-            return;
-        let syncedAt = new Date();
+            return undefined;
+        // Prefer the data's own clock; otherwise fall back to when the request was
+        // issued (not now), so records written server-side during the fetch are
+        // re-fetched next run rather than skipped on clock skew.
+        let syncedAt = fallbackTime ?? new Date();
         // If updateFrom is specified, extract the timestamp from response
         if (step.since?.updateFrom && data && typeof data === 'object') {
             const extracted = extractNestedValue(data, step.since.updateFrom);
@@ -134,6 +146,7 @@ export class FetchHandler {
             recordsFetched: recordCount ?? 0,
             isIncremental: true,
         });
+        return syncedAt;
     }
     resolveFetchTarget(step) {
         if (step.operationRef) {
@@ -205,6 +218,21 @@ export class FetchHandler {
         }
         return { query, headers, checkpointKey };
     }
+    /**
+     * Idempotency-Key header for a mutating request, when durable mode is on.
+     *
+     * GET is safe and gets no key. The key is a hash of
+     * (executionId, stepId, method, path, body) so it is stable across retries
+     * and replays of the same request, yet distinct per loop iteration (different
+     * path/body) — letting a cooperating API dedupe re-issued effects.
+     */
+    idempotencyKeyFor(method, path, body) {
+        if (!this.deps.idempotency || method === 'GET')
+            return undefined;
+        const { executionId, stepId } = this.deps.idempotency;
+        const signature = `${executionId}${stepId}${method}${path}${JSON.stringify(body ?? null)}`;
+        return createHash('sha256').update(signature).digest('hex').slice(0, 32);
+    }
     async executePaginated(step, client, basePath, method, sourceName, operationId, sinceQuery = {}, sinceHeaders = {}) {
         const allResults = [];
         const paginate = step.paginate;
@@ -213,7 +241,24 @@ export class FetchHandler {
             page: 0,
             pageSize: paginate.pageSize,
         };
+        // Resumable (backfill) pagination: seed the cursor/page from the last
+        // persisted position so a restart continues from where it stopped.
+        const backfill = this.deps.pagination;
+        if (step.backfill && backfill?.resume) {
+            if (backfill.resume.done) {
+                this.deps.log('Backfill already complete; nothing to fetch.');
+                return [];
+            }
+            ctx.page = backfill.resume.page;
+            ctx.cursor = backfill.resume.cursor;
+            this.deps.log(`Resuming backfill from page ${ctx.page + 1}`);
+        }
+        // Per-run item cap. For a backfill this bounds memory per run: when hit, the
+        // run stops *incomplete* and a later resume continues — so an arbitrarily
+        // large backfill completes across runs without buffering it all at once.
+        const itemCap = backfill?.maxItemsPerRun ?? MAX_PAGINATION_ITEMS;
         let hasMore = true;
+        let stoppedByCap = false;
         while (hasMore) {
             // Build query with pagination params
             const paginationQuery = strategy.buildQuery(ctx);
@@ -224,22 +269,46 @@ export class FetchHandler {
             await this.validateOASResponse(sourceName, operationId, response.data);
             // Temporarily set response for until condition evaluation
             this.deps.ctx.response = response.data;
-            // Check until condition
-            if (step.until) {
-                const shouldStop = evaluate(step.until, this.deps.ctx);
-                if (shouldStop) {
-                    break;
-                }
-            }
-            // Extract results using strategy
+            // Extract and append the current page BEFORE deciding whether to stop, so
+            // the page that satisfies `until` is not silently dropped.
             const pageResult = strategy.extractResults(response.data, ctx);
             allResults.push(...pageResult.items);
             hasMore = pageResult.hasMore;
-            // Update cursor for next iteration
-            if (pageResult.nextCursor) {
-                ctx.cursor = pageResult.nextCursor;
+            // Advance the cursor. If the API echoes the cursor we just used, stop
+            // instead of looping to the page cap and duplicating items each round.
+            if (pageResult.nextCursor !== undefined) {
+                if (pageResult.nextCursor === ctx.cursor) {
+                    this.deps.log(`Pagination cursor did not advance ('${pageResult.nextCursor}'); stopping.`);
+                    hasMore = false;
+                }
+                else {
+                    ctx.cursor = pageResult.nextCursor;
+                }
             }
             ctx.page++;
+            // `until` is checked after the current page has been appended.
+            if (hasMore && step.until && evaluate(step.until, this.deps.ctx)) {
+                hasMore = false;
+            }
+            // Memory safety: cap total accumulated items, not just page count. For a
+            // backfill this is a clean stop-and-resume boundary, not an end of data.
+            if (allResults.length >= itemCap) {
+                this.deps.log(`Pagination item limit (${itemCap}) reached`);
+                if (hasMore)
+                    stoppedByCap = true;
+                hasMore = false;
+            }
+            // Record this page's position for a resumable backfill. `done` is the
+            // natural end of pagination — never set when we stopped on the item cap,
+            // so a resume knows to continue rather than treat the backfill as finished.
+            if (step.backfill && backfill?.onPage) {
+                await backfill.onPage({
+                    page: ctx.page,
+                    cursor: ctx.cursor,
+                    recordCount: pageResult.items.length,
+                    done: !hasMore && !stoppedByCap,
+                });
+            }
             // Emit heartbeat after each page
             this.deps.emit?.('fetch.heartbeat', {
                 source: sourceName,

package/dist/interpreter/http.d.ts

@@ -1,6 +1,14 @@
 import type { RetryConfig } from '../ast/nodes.js';
 import type { RateLimiter } from '../auth/types.js';
 import { CircuitBreaker } from '../auth/circuit-breaker.js';
+/**
+ * Parse a `Retry-After` header into a delay in ms, clamped to `maxDelayMs`.
+ * The header may be delta-seconds (`120`) or an HTTP-date; a date in the past or
+ * an unparseable value yields 0 and `undefined` respectively. Clamping stops a
+ * hostile/broken server from pinning the client for hours, and the date branch
+ * stops `parseInt` from turning a date into `NaN` → `sleep(NaN)` → a tight loop.
+ */
+export declare function parseRetryAfterMs(value: string | null | undefined, maxDelayMs: number): number | undefined;
 export interface HttpClientConfig {
     baseUrl: string;
     headers?: Record<string, string>;
@@ -9,6 +17,8 @@ export interface HttpClientConfig {
     circuitBreaker?: CircuitBreaker;
     /** Source name for rate limit and circuit breaker tracking */
     sourceName?: string;
+    /** Default per-request timeout in ms (overridden by RetryConfig.timeout) */
+    timeout?: number;
 }
 export interface AuthProvider {
     getToken(): Promise<string>;
@@ -20,6 +30,12 @@ export interface HttpRequest {
     body?: unknown;
     headers?: Record<string, string>;
     query?: Record<string, string>;
+    /**
+     * Opt a non-idempotent request (POST/PATCH) into automatic retries by
+     * supplying an idempotency key. Sent as the `Idempotency-Key` header so the
+     * server can dedup a re-sent write.
+     */
+    idempotencyKey?: string;
 }
 export interface HttpResponse<T = unknown> {
     status: number;
@@ -31,10 +47,20 @@ export declare class HttpClient {
     constructor(config: HttpClientConfig);
     request<T = unknown>(req: HttpRequest, retry?: RetryConfig): Promise<HttpResponse<T>>;
     /**
-     * Safely parse response body, handling non-JSON responses gracefully.
-     * Attempts JSON parsing first, providing helpful errors on failure.
+     * Run a fetch with a per-attempt timeout. Aborts the request (freeing the
+     * connection and rate-limiter slot) if it exceeds `timeoutMs`, surfacing a
+     * retryable FetchError rather than hanging forever.
+     */
+    private fetchWithTimeout;
+    /**
+     * Parse a successful (2xx) response body. Handles empty/204 responses,
+     * returns non-JSON content as raw text, and caps the buffered size.
      */
     private parseResponseBody;
+    /** Read a response body to text, rejecting once it exceeds MAX_RESPONSE_BYTES. */
+    private readCappedText;
+    /** Read a short snippet of a body for an error message (best-effort). */
+    private safeReadSnippet;
     private buildUrl;
     private buildHeaders;
     private calculateDelay;
@@ -50,6 +76,8 @@ export declare class OAuth2AuthProvider implements AuthProvider {
     private tokenEndpoint?;
     private clientId?;
     private clientSecret?;
+    /** Single-flight guard: coalesces concurrent refreshes into one in-flight request */
+    private refreshPromise;
     constructor(config: {
         accessToken: string;
         refreshToken?: string;
@@ -59,4 +87,5 @@ export declare class OAuth2AuthProvider implements AuthProvider {
     });
     getToken(): Promise<string>;
     refreshToken(): Promise<string>;
+    private doRefresh;
 }

package/dist/interpreter/http.js

@@ -3,6 +3,34 @@ import { CircuitBreakerError } from '../auth/circuit-breaker.js';
 import { sleep } from '../utils/async.js';
 import { HTTP_RETRY_DEFAULTS } from '../config/index.js';
 import { FetchError } from '../errors/index.js';
+/**
+ * Parse a `Retry-After` header into a delay in ms, clamped to `maxDelayMs`.
+ * The header may be delta-seconds (`120`) or an HTTP-date; a date in the past or
+ * an unparseable value yields 0 and `undefined` respectively. Clamping stops a
+ * hostile/broken server from pinning the client for hours, and the date branch
+ * stops `parseInt` from turning a date into `NaN` → `sleep(NaN)` → a tight loop.
+ */
+export function parseRetryAfterMs(value, maxDelayMs) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    const seconds = Number(trimmed);
+    let ms;
+    if (trimmed !== '' && Number.isFinite(seconds)) {
+        ms = seconds * 1000;
+    }
+    else {
+        const when = Date.parse(trimmed);
+        if (Number.isNaN(when))
+            return undefined;
+        ms = when - Date.now();
+    }
+    return Math.min(Math.max(ms, 0), maxDelayMs);
+}
+/** Maximum buffered response body size (10 MiB) before the request is rejected. */
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+/** HTTP methods that are safe to retry automatically (idempotent per RFC 7231). */
+const IDEMPOTENT_METHODS = new Set(['GET', 'PUT', 'DELETE']);
 export class HttpClient {
     config;
     constructor(config) {
@@ -10,17 +38,29 @@ export class HttpClient {
     }
     async request(req, retry) {
         const url = this.buildUrl(req.path, req.query);
-        const headers = await this.buildHeaders(req.headers);
+        const requestHeaders = { ...req.headers };
+        if (req.idempotencyKey) {
+            requestHeaders['Idempotency-Key'] = req.idempotencyKey;
+        }
+        const headers = await this.buildHeaders(requestHeaders);
         const fetchOptions = {
             method: req.method,
             headers,
             body: req.body ? JSON.stringify(req.body) : undefined,
         };
+        // Auto-retry only idempotent verbs, or any verb carrying an idempotency key.
+        // A blind retry of POST/PATCH can re-send a write the server already
+        // committed (timeout / dropped socket after commit), duplicating data.
+        const retriable = IDEMPOTENT_METHODS.has(req.method) || Boolean(req.idempotencyKey);
         const maxAttempts = retry?.maxAttempts ?? HTTP_RETRY_DEFAULTS.MAX_ATTEMPTS;
         const backoff = retry?.backoff ?? HTTP_RETRY_DEFAULTS.BACKOFF;
         const initialDelay = retry?.initialDelay ?? HTTP_RETRY_DEFAULTS.INITIAL_DELAY_MS;
         const maxDelay = retry?.maxDelay ?? HTTP_RETRY_DEFAULTS.MAX_DELAY_MS;
+        const timeout = retry?.timeout ?? this.config.timeout ?? HTTP_RETRY_DEFAULTS.TIMEOUT_MS;
         let lastError = null;
+        // Refresh the token at most once per request to avoid burning a fresh
+        // rotating refresh token on every 401 retry attempt.
+        let hasRefreshed = false;
         // Check circuit breaker before attempting requests
         if (this.config.circuitBreaker && this.config.sourceName) {
             // This will throw CircuitBreakerError if circuit is open
@@ -32,14 +72,16 @@ export class HttpClient {
                 if (attempt > 1 && this.config.circuitBreaker && this.config.sourceName) {
                     if (!this.config.circuitBreaker.canProceed(this.config.sourceName, req.path)) {
                         // Circuit opened during retries, fail fast
-                        throw new CircuitBreakerError(this.config.sourceName, req.path, this.config.circuitBreaker.getStatus(this.config.sourceName, req.path).nextAttemptTime?.getTime() ?? 0 - Date.now());
+                        throw new CircuitBreakerError(this.config.sourceName, req.path, this.config.circuitBreaker
+                            .getStatus(this.config.sourceName, req.path)
+                            .nextAttemptTime?.getTime() ?? 0 - Date.now());
                     }
                 }
                 // Wait for rate limit capacity if we have a rate limiter
                 if (this.config.rateLimiter && this.config.sourceName) {
                     await this.config.rateLimiter.waitForCapacity(this.config.sourceName, req.path);
                 }
-                const response = await fetch(url, fetchOptions);
+                const response = await this.fetchWithTimeout(url, fetchOptions, timeout, req.method);
                 // Extract and record rate limit info from response headers
                 const responseHeaders = {};
                 response.headers.forEach((value, key) => {
@@ -49,17 +91,19 @@ export class HttpClient {
                     const rateLimitInfo = parseRateLimitHeaders(responseHeaders);
                     // Add retry-after from 429 responses
                     if (response.status === 429) {
-                        const retryAfter = response.headers.get('Retry-After');
-                        if (retryAfter) {
-                            rateLimitInfo.retryAfter = parseInt(retryAfter, 10);
+                        const ms = parseRetryAfterMs(response.headers.get('Retry-After'), maxDelay);
+                        if (ms !== undefined) {
+                            rateLimitInfo.retryAfter = Math.ceil(ms / 1000);
                         }
                     }
                     this.config.rateLimiter.recordResponse(this.config.sourceName, rateLimitInfo, req.path);
                 }
-                // Handle rate limiting
-                if (response.status === 429) {
-                    const retryAfter = response.headers.get('Retry-After');
-                    const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
+                // Handle rate limiting: retry only while attempts remain. A 429 on the
+                // final attempt falls through to the >=400 handler below, which throws a
+                // FetchError carrying status 429 — not the generic "all retries" error.
+                if (response.status === 429 && retriable && attempt < maxAttempts) {
+                    const delay = parseRetryAfterMs(response.headers.get('Retry-After'), maxDelay) ??
+                        this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
                     await sleep(delay);
                     continue;
                 }
@@ -69,20 +113,34 @@ export class HttpClient {
                     if (this.config.circuitBreaker && this.config.sourceName) {
                         this.config.circuitBreaker.recordFailure(this.config.sourceName, req.path, response.status);
                     }
-                    if (attempt < maxAttempts) {
+                    if (retriable && attempt < maxAttempts) {
                         const delay = this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
                         await sleep(delay);
                         continue;
                     }
+                    // Non-idempotent without an idempotency key: do not re-send a write
+                    // that the server may have already committed. Return the 5xx instead.
                 }
-                // Handle 401 - try token refresh
-                if (response.status === 401 && this.config.auth?.refreshToken && attempt < maxAttempts) {
+                // Handle 401 - try token refresh (at most once per request)
+                if (response.status === 401 &&
+                    this.config.auth?.refreshToken &&
+                    !hasRefreshed &&
+                    attempt < maxAttempts) {
+                    hasRefreshed = true;
                     await this.config.auth.refreshToken();
-                    // Rebuild headers with new token
-                    const newHeaders = await this.buildHeaders(req.headers);
+                    // Rebuild headers with new token (preserving the idempotency key)
+                    const newHeaders = await this.buildHeaders(requestHeaders);
                     fetchOptions.headers = newHeaders;
                     continue;
                 }
+                // Any remaining non-2xx/3xx response is an error: a 4xx (other than the
+                // 429/401-refresh cases handled above) or a 5xx that exhausted retries.
+                // Returning it as `data` would let map/store persist an API error body.
+                if (response.status >= 400) {
+                    const snippet = await this.safeReadSnippet(response);
+                    throw new FetchError(`HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}` +
+                        (snippet ? `: ${snippet}` : ''), { url, method: req.method, statusCode: response.status });
+                }
                 const data = await this.parseResponseBody(response, url, req.method);
                 // Record success in circuit breaker
                 if (this.config.circuitBreaker && this.config.sourceName && response.status < 500) {
@@ -100,10 +158,21 @@ export class HttpClient {
                 if (error instanceof CircuitBreakerError) {
                     throw error;
                 }
+                // HTTP-status errors (4xx, exhausted 5xx) and body parse/size errors
+                // are definitive — don't burn retries re-fetching them.
+                if (error instanceof FetchError && error.statusCode !== undefined) {
+                    throw error;
+                }
                 // Record network errors in circuit breaker
                 if (this.config.circuitBreaker && this.config.sourceName) {
                     this.config.circuitBreaker.recordFailure(this.config.sourceName, req.path, undefined, true);
                 }
+                // A network error on a non-idempotent write is ambiguous: the request
+                // may have reached the server and committed before the socket dropped.
+                // Surface the error rather than blindly re-sending a duplicate write.
+                if (!retriable) {
+                    throw lastError;
+                }
                 if (attempt < maxAttempts) {
                     const delay = this.calculateDelay(attempt, backoff, initialDelay, maxDelay);
                     await sleep(delay);
@@ -113,22 +182,97 @@ export class HttpClient {
         throw lastError ?? new Error('Request failed after all retries');
     }
     /**
-     * Safely parse response body, handling non-JSON responses gracefully.
-     * Attempts JSON parsing first, providing helpful errors on failure.
+     * Run a fetch with a per-attempt timeout. Aborts the request (freeing the
+     * connection and rate-limiter slot) if it exceeds `timeoutMs`, surfacing a
+     * retryable FetchError rather than hanging forever.
+     */
+    async fetchWithTimeout(url, options, timeoutMs, method) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return fetch(url, options);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, { ...options, signal: controller.signal });
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                throw new FetchError(`Request timed out after ${timeoutMs}ms`, {
+                    url,
+                    method,
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Parse a successful (2xx) response body. Handles empty/204 responses,
+     * returns non-JSON content as raw text, and caps the buffered size.
      */
     async parseResponseBody(response, url, method) {
+        // No-content responses have no body to parse.
+        if (response.status === 204 || response.status === 205) {
+            return null;
+        }
+        const text = await this.readCappedText(response, url, method);
+        if (text.trim() === '') {
+            return null;
+        }
         const contentType = response.headers.get('content-type') ?? '';
-        // Always attempt JSON parsing - many APIs don't set content-type correctly
+        const looksJson = contentType === '' || contentType.includes('json');
         try {
-            return await response.json();
+            return JSON.parse(text);
         }
         catch (parseError) {
-            // Provide context about content-type mismatch if applicable
-            const isJsonContentType = contentType.includes('application/json') || contentType === '';
-            const contentTypeHint = !isJsonContentType
-                ? ` (content-type was '${contentType}')`
-                : '';
-            throw new FetchError(`Failed to parse JSON response${contentTypeHint}: ${parseError.message}`, { url, method, statusCode: response.status, cause: parseError });
+            // A non-JSON content-type (text/html, text/plain, …) is returned as-is
+            // rather than throwing — only fail when the body claimed to be JSON.
+            if (!looksJson) {
+                return text;
+            }
+            throw new FetchError(`Failed to parse JSON response (content-type '${contentType}'): ${parseError.message}`, { url, method, statusCode: response.status, cause: parseError });
+        }
+    }
+    /** Read a response body to text, rejecting once it exceeds MAX_RESPONSE_BYTES. */
+    async readCappedText(response, url, method) {
+        const body = response.body;
+        if (!body) {
+            return await response.text();
+        }
+        const reader = body.getReader();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                size += value.byteLength;
+                if (size > MAX_RESPONSE_BYTES) {
+                    await reader.cancel();
+                    throw new FetchError(`Response body exceeds ${MAX_RESPONSE_BYTES} bytes`, {
+                        url,
+                        method,
+                        statusCode: response.status,
+                    });
+                }
+                chunks.push(Buffer.from(value));
+            }
+        }
+        return Buffer.concat(chunks).toString('utf-8');
+    }
+    /** Read a short snippet of a body for an error message (best-effort). */
+    async safeReadSnippet(response) {
+        try {
+            const text = await response.text();
+            const trimmed = text.trim();
+            return trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed;
+        }
+        catch {
+            return '';
         }
     }
     buildUrl(path, query) {
@@ -190,6 +334,8 @@ export class OAuth2AuthProvider {
     tokenEndpoint;
     clientId;
     clientSecret;
+    /** Single-flight guard: coalesces concurrent refreshes into one in-flight request */
+    refreshPromise = null;
     constructor(config) {
         this.accessToken = config.accessToken;
         this.refreshTokenValue = config.refreshToken;
@@ -201,6 +347,21 @@ export class OAuth2AuthProvider {
         return this.accessToken;
     }
     async refreshToken() {
+        // Deduplicate concurrent refresh requests. With rotating refresh tokens,
+        // letting many in-flight requests each POST to the token endpoint would
+        // 400 invalid_grant all but one and kill the session.
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.doRefresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async doRefresh() {
         if (!this.refreshTokenValue || !this.tokenEndpoint) {
             throw new Error('Cannot refresh token: missing refresh token or endpoint');
         }
@@ -214,7 +375,7 @@ export class OAuth2AuthProvider {
                 client_secret: this.clientSecret ?? '',
             }),
         });
-        const data = await response.json();
+        const data = (await response.json());
         this.accessToken = data.access_token;
         if (data.refresh_token) {
             this.refreshTokenValue = data.refresh_token;

package/dist/interpreter/index.d.ts

@@ -1,8 +1,8 @@
 export { MissionExecutor, type ExecutionResult, type ExecutionError, type ExecutorConfig, type ProgressCallbacks, type ExecutionStartEvent, type ExecutionCompleteEvent, type StageStartEvent, type StageCompleteEvent, type AuthConfig, } from './executor.js';
-export { HttpClient, BearerAuthProvider, OAuth2AuthProvider, type HttpClientConfig, type AuthProvider } from './http.js';
-export { SourceManager, type SourceManagerConfig, type SourceManagerDeps } from './source-manager.js';
+export { HttpClient, BearerAuthProvider, OAuth2AuthProvider, type HttpClientConfig, type AuthProvider, } from './http.js';
+export { SourceManager, type SourceManagerConfig, type SourceManagerDeps, } from './source-manager.js';
 export { StoreManager, type StoreManagerConfig } from './store-manager.js';
-export { createContext, childContext, getVariable, setVariable, type ExecutionContext } from './context.js';
+export { createContext, childContext, getVariable, setVariable, type ExecutionContext, } from './context.js';
 export { evaluate, evaluateToString, interpolatePath } from './evaluator.js';
 export { FetchHandler, type FetchHandlerDeps, type FetchResult } from './fetch-handler.js';
 export { type PaginationStrategy, type PaginationContext, type PageResult, createPaginationStrategy, OffsetPaginationStrategy, PageNumberPaginationStrategy, CursorPaginationStrategy, } from './pagination.js';

package/dist/interpreter/index.js

@@ -1,8 +1,8 @@
 export { MissionExecutor, } from './executor.js';
-export { HttpClient, BearerAuthProvider, OAuth2AuthProvider } from './http.js';
-export { SourceManager } from './source-manager.js';
+export { HttpClient, BearerAuthProvider, OAuth2AuthProvider, } from './http.js';
+export { SourceManager, } from './source-manager.js';
 export { StoreManager } from './store-manager.js';
-export { createContext, childContext, getVariable, setVariable } from './context.js';
+export { createContext, childContext, getVariable, setVariable, } from './context.js';
 export { evaluate, evaluateToString, interpolatePath } from './evaluator.js';
 export { FetchHandler } from './fetch-handler.js';
 export { createPaginationStrategy, OffsetPaginationStrategy, PageNumberPaginationStrategy, CursorPaginationStrategy, } from './pagination.js';

package/dist/interpreter/pagination.d.ts

@@ -63,7 +63,7 @@ export declare class CursorPaginationStrategy implements PaginationStrategy {
     private cachedArrayField;
     constructor(config: PaginationConfig);
     buildQuery(ctx: PaginationContext): Record<string, string>;
-    extractResults(response: unknown, ctx: PaginationContext): PageResult;
+    extractResults(response: unknown, _ctx: PaginationContext): PageResult;
     clearCache(): void;
 }
 /**