scrapely 1.2.10 → 1.2.12

package/dist/actor.d.ts

@@ -517,6 +517,11 @@ export declare class Actor {
     /** One-shot bounded reconciliation on fatal process errors. */
     private static installFatalChargeHandlers;
     private static _shutdownActor;
+    /**
+     * Store the exit/fail status message on the run as terminal. Best effort and
+     * bounded: a failing or slow API is logged and never blocks the exit.
+     */
+    private static _persistTerminalStatusMessage;
     /**
      * Sets the status message for the current Actor run.
      *

package/dist/actor.js

@@ -382,9 +382,11 @@ class Actor {
         const code = opts.exitCode ?? 0;
         const timeoutSecs = opts.timeoutSecs ?? 30;
         const shouldExit = opts.exit ?? true;
-        if (opts.statusMessage)
-            console.log(`[Scrapely] ${opts.statusMessage}`);
         Actor._ensureActorInit('exit');
+        // Apify parity: the exit/fail message becomes the run's terminal status
+        // message. Stored before teardown, while the run and process are alive.
+        if (opts.statusMessage)
+            await Actor._persistTerminalStatusMessage(opts.statusMessage, code);
         await Actor._shutdownActor(timeoutSecs);
         if (shouldExit) {
             await new Promise((resolve) => process.stdout.write('', () => resolve()));
@@ -949,6 +951,31 @@ class Actor {
         // drain, usually within milliseconds, and is still bounded.
         await waitForStdioDrain(Math.min(1000, flushDeadlineMs));
     }
+    /**
+     * Store the exit/fail status message on the run as terminal. Best effort and
+     * bounded: a failing or slow API is logged and never blocks the exit.
+     */
+    static async _persistTerminalStatusMessage(message, exitCode, timeoutMs = 10_000) {
+        let timer;
+        try {
+            await Promise.race([
+                Actor.setStatusMessage(message, {
+                    isStatusMessageTerminal: true,
+                    level: exitCode > 0 ? 'ERROR' : 'INFO',
+                }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+                }),
+            ]);
+        }
+        catch (err) {
+            console.warn(`[Scrapely] Failed to store the final status message on the run: ${err.message}`);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     /**
      * Sets the status message for the current Actor run.
      *
@@ -1000,6 +1027,7 @@ class Actor {
                 statusMessage: message,
                 isStatusMessageTerminal,
             }),
+            signal: AbortSignal.timeout(10_000),
         });
         if (!response.ok) {
             const error = await response.text();

package/dist/cdp-retry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Retry remote-browser (CDP) connects that fail for transient reasons.
+ *
+ * The remote browser answers 429 when it is at capacity and 503 when it cannot
+ * start a browser or validate the session right now, both with a Retry-After
+ * delay (repeated in the response body, because Playwright only puts the
+ * status line and body into its error message). Connection errors and
+ * timeouts are transient too. Those are retried with exponential backoff,
+ * waiting at least the Retry-After delay when the error carries one. Any other
+ * status (400/401/402/403/404) fails at once.
+ *
+ * Tuning (environment):
+ * - SCRAPELY_CDP_CONNECT_ATTEMPTS: total attempts, default 5 (1 disables retries).
+ * - SCRAPELY_CDP_RETRY_BASE_SECS: first backoff delay, default 1; doubles per attempt.
+ * - SCRAPELY_CDP_RETRY_MAX_SECS: cap for one backoff delay, default 30.
+ * - SCRAPELY_CDP_RETRY_AFTER_MAX_SECS: longest Retry-After the SDK waits out,
+ *   default 120. A longer Retry-After ends the retries (the SDK never retries
+ *   earlier than the server asked).
+ */
+/** @internal Exported for tests. */
+export declare function classifyConnectError(err: unknown): {
+    retryable: boolean;
+    status?: number;
+    retryAfterSecs?: number;
+};
+/** @internal Delay in ms before retry number `attempt` (1-based), honoring Retry-After. */
+export declare function backoffDelayMs(attempt: number, retryAfterSecs?: number): number;
+/** @internal Overridable for tests. */
+export declare const retryTiming: {
+    sleep: (ms: number) => Promise<void>;
+};
+/** Run a CDP connect, retrying transient failures with backoff. */
+export declare function connectWithRetry<T>(connect: () => Promise<T>): Promise<T>;
+/** True when `url` points at the same host as the platform's CDP_URL. */
+export declare function isPlatformCdpUrl(url: unknown, platformCdpUrl: string | undefined): boolean;
+export declare function isRetryWrapped(fn: unknown): boolean;
+/**
+ * Make `target[method]` (Playwright `connectOverCDP` or Puppeteer `connect`)
+ * retry transient failures when it connects to the platform CDP host. Covers
+ * actor code that connects to CDP_URL directly as well as the SDK's own
+ * redirected launches. Other hosts are left alone. Idempotent.
+ */
+export declare function wrapConnectWithRetry(target: any, method: 'connectOverCDP' | 'connect', getPlatformCdpUrl: () => string | undefined): void;

package/dist/cdp-retry.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Retry remote-browser (CDP) connects that fail for transient reasons.
+ *
+ * The remote browser answers 429 when it is at capacity and 503 when it cannot
+ * start a browser or validate the session right now, both with a Retry-After
+ * delay (repeated in the response body, because Playwright only puts the
+ * status line and body into its error message). Connection errors and
+ * timeouts are transient too. Those are retried with exponential backoff,
+ * waiting at least the Retry-After delay when the error carries one. Any other
+ * status (400/401/402/403/404) fails at once.
+ *
+ * Tuning (environment):
+ * - SCRAPELY_CDP_CONNECT_ATTEMPTS: total attempts, default 5 (1 disables retries).
+ * - SCRAPELY_CDP_RETRY_BASE_SECS: first backoff delay, default 1; doubles per attempt.
+ * - SCRAPELY_CDP_RETRY_MAX_SECS: cap for one backoff delay, default 30.
+ * - SCRAPELY_CDP_RETRY_AFTER_MAX_SECS: longest Retry-After the SDK waits out,
+ *   default 120. A longer Retry-After ends the retries (the SDK never retries
+ *   earlier than the server asked).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryTiming = void 0;
+exports.classifyConnectError = classifyConnectError;
+exports.backoffDelayMs = backoffDelayMs;
+exports.connectWithRetry = connectWithRetry;
+exports.isPlatformCdpUrl = isPlatformCdpUrl;
+exports.isRetryWrapped = isRetryWrapped;
+exports.wrapConnectWithRetry = wrapConnectWithRetry;
+const RETRY_WRAPPED = Symbol.for('scrapely.cdpRetryWrapped');
+const REASONS = 'Too Many Requests|Internal Server Error|Bad Gateway|Service Unavailable|Gateway Timeout|' +
+    'Request Timeout|Bad Request|Unauthorized|Payment Required|Forbidden|Not Found';
+const STATUS_RE = new RegExp(`\\b([1-5]\\d\\d) (?:${REASONS})\\b`);
+const WS_STATUS_RE = /Unexpected server response:?\s*(\d{3})/i;
+const RETRY_AFTER_RE = /Retry-After:?\s*(\d+(?:\.\d+)?)/i;
+const TRANSIENT_MARKERS = [
+    'econnrefused',
+    'econnreset',
+    'etimedout',
+    'epipe',
+    'eai_again',
+    'ehostunreach',
+    'enetunreach',
+    'socket hang up',
+    'timeout',
+    'timed out',
+    'connection closed',
+    'connection refused',
+    'connection reset',
+    'websocket error',
+    'net::err_',
+    'target closed',
+];
+function envNumber(name, fallback) {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function maxAttempts() {
+    return Math.max(1, Math.floor(envNumber('SCRAPELY_CDP_CONNECT_ATTEMPTS', 5)));
+}
+function errorText(err) {
+    if (err instanceof Error) {
+        const code = err.code;
+        return `${err.name}: ${err.message}${code ? ` ${code}` : ''}`;
+    }
+    return String(err);
+}
+/** @internal Exported for tests. */
+function classifyConnectError(err) {
+    const text = errorText(err);
+    const statusMatch = WS_STATUS_RE.exec(text) ?? STATUS_RE.exec(text);
+    const retryAfterMatch = RETRY_AFTER_RE.exec(text);
+    const retryAfterSecs = retryAfterMatch ? Number(retryAfterMatch[1]) : undefined;
+    if (statusMatch) {
+        const status = Number(statusMatch[1]);
+        return { retryable: status === 408 || status === 429 || status >= 500, status, retryAfterSecs };
+    }
+    const lowered = text.toLowerCase();
+    return { retryable: TRANSIENT_MARKERS.some((m) => lowered.includes(m)), retryAfterSecs };
+}
+/** @internal Delay in ms before retry number `attempt` (1-based), honoring Retry-After. */
+function backoffDelayMs(attempt, retryAfterSecs) {
+    const base = envNumber('SCRAPELY_CDP_RETRY_BASE_SECS', 1);
+    const cap = envNumber('SCRAPELY_CDP_RETRY_MAX_SECS', 30);
+    let delay = Math.min(cap, base * 2 ** (attempt - 1)) * (0.75 + Math.random() * 0.5);
+    if (retryAfterSecs !== undefined)
+        delay = Math.max(delay, retryAfterSecs);
+    return Math.round(delay * 1000);
+}
+function describe(err, status) {
+    if (status !== undefined)
+        return `HTTP ${status}`;
+    // First line only, URL masked: connect errors can carry the session URL with ids.
+    const first = (err instanceof Error ? err.message : String(err)).trim().split('\n')[0] || 'error';
+    return first.replace(/(wss?|https?):\/\/\S+/g, '<cdp-url>').slice(0, 200);
+}
+/** @internal Overridable for tests. */
+exports.retryTiming = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/** Run a CDP connect, retrying transient failures with backoff. */
+async function connectWithRetry(connect) {
+    const attempts = maxAttempts();
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await connect();
+        }
+        catch (err) {
+            const { retryable, status, retryAfterSecs } = classifyConnectError(err);
+            if (!retryable || attempt >= attempts)
+                throw err;
+            if (retryAfterSecs !== undefined && retryAfterSecs > envNumber('SCRAPELY_CDP_RETRY_AFTER_MAX_SECS', 120)) {
+                // Never retry earlier than the server asked; give up instead of waiting that long.
+                throw err;
+            }
+            const delayMs = backoffDelayMs(attempt, retryAfterSecs);
+            console.warn(`[scrapely] Remote browser connect failed (${describe(err, status)}); ` +
+                `retrying in ${(delayMs / 1000).toFixed(1)}s (attempt ${attempt + 1}/${attempts})`);
+            await exports.retryTiming.sleep(delayMs);
+        }
+    }
+}
+/** True when `url` points at the same host as the platform's CDP_URL. */
+function isPlatformCdpUrl(url, platformCdpUrl) {
+    if (typeof url !== 'string' || !platformCdpUrl)
+        return false;
+    try {
+        const target = new URL(url);
+        const platform = new URL(platformCdpUrl);
+        return !!target.host && target.host.toLowerCase() === platform.host.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+function connectTarget(arg) {
+    if (typeof arg === 'string')
+        return arg;
+    if (arg && typeof arg === 'object') {
+        const o = arg;
+        return o.endpointURL ?? o.wsEndpoint ?? o.browserWSEndpoint ?? o.browserURL;
+    }
+    return undefined;
+}
+function isRetryWrapped(fn) {
+    return typeof fn === 'function' && fn[RETRY_WRAPPED] === true;
+}
+/**
+ * Make `target[method]` (Playwright `connectOverCDP` or Puppeteer `connect`)
+ * retry transient failures when it connects to the platform CDP host. Covers
+ * actor code that connects to CDP_URL directly as well as the SDK's own
+ * redirected launches. Other hosts are left alone. Idempotent.
+ */
+function wrapConnectWithRetry(target, method, getPlatformCdpUrl) {
+    const original = target?.[method];
+    if (typeof original !== 'function' || isRetryWrapped(original))
+        return;
+    const wrapped = function (...args) {
+        const self = this ?? target;
+        if (!isPlatformCdpUrl(connectTarget(args[0]), getPlatformCdpUrl())) {
+            return original.apply(self, args);
+        }
+        return connectWithRetry(() => original.apply(self, args));
+    };
+    wrapped[RETRY_WRAPPED] = true;
+    try {
+        target[method] = wrapped;
+    }
+    catch {
+        // frozen object: leave it unwrapped
+    }
+}

package/dist/patch-browser-pool.js

@@ -18,6 +18,7 @@ exports.patchRawBrowserType = patchRawBrowserType;
  */
 const browser_configuration_js_1 = require("./browser-configuration.js");
 const browser_locations_js_1 = require("./browser-locations.js");
+const cdp_retry_js_1 = require("./cdp-retry.js");
 let _cdpUrl;
 /**
  * Lazily get CDP URL from environment or cached value.
@@ -321,6 +322,7 @@ function patchPlaywrightPluginClass(PlaywrightPlugin) {
         }
         const cdpUrl = applyProxyInfoToCdpUrl(requireCdpUrl(), proxyInfoFromLaunchContext(launchContext), launchContext?.browserConfiguration);
         const chromium = getPlaywrightChromium(this.library);
+        (0, cdp_retry_js_1.wrapConnectWithRetry)(chromium, 'connectOverCDP', getCdpUrl);
         return chromium.connectOverCDP(cdpUrl);
     };
     proto._scrapelyCdpPatched = true;
@@ -344,6 +346,7 @@ function patchPuppeteerPluginClass(PuppeteerPlugin) {
         if (!launcher || typeof launcher.connect !== 'function') {
             throw new Error('Puppeteer library is missing connect(). Install puppeteer or puppeteer-core.');
         }
+        (0, cdp_retry_js_1.wrapConnectWithRetry)(launcher, 'connect', getCdpUrl);
         return launcher.connect({ browserWSEndpoint: cdpUrl });
     };
     proto._scrapelyCdpPatched = true;
@@ -669,6 +672,10 @@ function patchRawBrowserType(chromium, browserType, name) {
 function patchRawPlaywrightModule(pw) {
     if (!pw?.chromium || typeof pw.chromium.connectOverCDP !== 'function')
         return;
+    // Retry transient connect failures (429/5xx/network) for the platform CDP
+    // host: covers direct chromium.connectOverCDP(CDP_URL) calls in actor code
+    // and the redirected launches, which call this same property.
+    (0, cdp_retry_js_1.wrapConnectWithRetry)(pw.chromium, 'connectOverCDP', getCdpUrl);
     for (const name of ['chromium', 'firefox', 'webkit']) {
         patchRawBrowserType(pw.chromium, pw[name], name);
     }
@@ -683,6 +690,7 @@ function patchRawPuppeteerModule(mod, moduleName) {
     if (typeof launcher?.launch !== 'function' || launcher._scrapelyRawCdpPatched) {
         return;
     }
+    (0, cdp_retry_js_1.wrapConnectWithRetry)(launcher, 'connect', getCdpUrl);
     const origLaunch = launcher.launch.bind(launcher);
     launcher.launch = async function rawPuppeteerLaunchPatched(launchOptions = {}) {
         const { options, browserConfiguration } = takeBrowserConfiguration(launchOptions);

package/dist/storage/api-storage-client.d.ts

@@ -12,6 +12,19 @@ export declare class ApiStorageClientError extends Error {
     readonly statusCode: number;
     constructor(message: string, statusCode: number);
 }
+/**
+ * Whether a non-2xx answer is retried. Idempotent methods: 500/502/503/504.
+ * Others (dataset push, KV PUT) only on a 503 that certainly was not
+ * processed: the rate limiter refused it ("rate-limit-unavailable", before the
+ * handler), or HAProxy had no backend (its own page, nothing forwarded). Any
+ * other 503 may mean "outcome unknown" (e.g. a direct dataset write whose
+ * commit was not confirmed), and re-sending could store the items twice.
+ */
+export declare function isRetryableResponse(status: number, idempotent: boolean, errorType?: string, bodyText?: string): boolean;
+/** Exponential backoff with jitter; honours a Retry-After (seconds or HTTP date) of up to 30 s. */
+export declare function serverRetryDelayMs(serverAttempt: number, retryAfter: string | null, random?: () => number, now?: number): number;
+/** fetch() failed before the request reached the server. */
+export declare function isConnectFailure(err: unknown): boolean;
 /**
  * Options for API requests (passed through from RecordOptions)
  */
@@ -20,19 +33,29 @@ interface ApiRequestOptions {
     timeoutSecs?: number;
     /** If true, don't retry on timeout errors */
     doNotRetryTimeouts?: boolean;
+    /** Override the method-based idempotency (e.g. get-or-create by name is safe to repeat). */
+    idempotent?: boolean;
 }
 /**
  * Base class for API-based storage clients.
  * Communicates with internal storage API instead of direct DB access.
  * No sensitive credentials are stored - only the user's API key.
  */
-declare abstract class BaseApiClient {
+export declare abstract class BaseApiClient {
     protected config: ApiStorageConfig;
     protected headers: Record<string, string>;
     private static rateLimiter;
     private static maxRetries;
+    static maxServerRetries: number;
     private static defaultTimeoutMs;
     constructor(config: ApiStorageConfig);
+    /**
+     * Sends the request and returns the successful (2xx) response, with the
+     * retry policy: 429 (rate limiter), timeouts, and the API being briefly
+     * unavailable (503, 5xx for idempotent methods, connection failures).
+     * Non-2xx answers that are not retried throw ApiStorageClientError.
+     */
+    private send;
     protected request<T>(method: string, path: string, body?: any, contentType?: string, options?: ApiRequestOptions): Promise<T>;
     protected requestWithHeaders<T>(method: string, path: string, body?: any, contentType?: string): Promise<{
         data: T;

package/dist/storage/api-storage-client.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiStorageClientFactory = exports.ApiRequestQueueClient = exports.ApiKeyValueStoreClient = exports.ApiDatasetClient = exports.ApiStorageClientError = void 0;
+exports.ApiStorageClientFactory = exports.ApiRequestQueueClient = exports.ApiKeyValueStoreClient = exports.ApiDatasetClient = exports.BaseApiClient = exports.ApiStorageClientError = void 0;
+exports.isRetryableResponse = isRetryableResponse;
+exports.serverRetryDelayMs = serverRetryDelayMs;
+exports.isConnectFailure = isConnectFailure;
 const node_crypto_1 = require("node:crypto");
 const kvs_iteration_js_1 = require("./kvs-iteration.js");
 function buildRqQueryParams(baseClientKey, options) {
@@ -155,6 +158,53 @@ exports.ApiStorageClientError = ApiStorageClientError;
 function isApiStorageClientError(err) {
     return err instanceof ApiStorageClientError;
 }
+// PUT is left out: a KV record PUT is counted (and billed) as a write each
+// time it is applied, so a lost response must not be re-sent blindly.
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'DELETE', 'OPTIONS']);
+// HAProxy's own 503 page: no backend was available, so nothing was forwarded.
+const NO_BACKEND_MARKER = 'No server is available to handle this request';
+const CONNECT_FAILURE_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'UND_ERR_CONNECT_TIMEOUT']);
+/**
+ * Whether a non-2xx answer is retried. Idempotent methods: 500/502/503/504.
+ * Others (dataset push, KV PUT) only on a 503 that certainly was not
+ * processed: the rate limiter refused it ("rate-limit-unavailable", before the
+ * handler), or HAProxy had no backend (its own page, nothing forwarded). Any
+ * other 503 may mean "outcome unknown" (e.g. a direct dataset write whose
+ * commit was not confirmed), and re-sending could store the items twice.
+ */
+function isRetryableResponse(status, idempotent, errorType, bodyText) {
+    if (idempotent)
+        return status === 500 || status === 502 || status === 503 || status === 504;
+    if (status !== 503)
+        return false;
+    return errorType === 'rate-limit-unavailable' || (bodyText ?? '').includes(NO_BACKEND_MARKER);
+}
+/** Exponential backoff with jitter; honours a Retry-After (seconds or HTTP date) of up to 30 s. */
+function serverRetryDelayMs(serverAttempt, retryAfter, random = Math.random, now = Date.now()) {
+    if (retryAfter !== null && retryAfter.trim() !== '') {
+        let secs = Number(retryAfter);
+        if (!Number.isFinite(secs)) {
+            const at = Date.parse(retryAfter);
+            secs = Number.isFinite(at) ? Math.max(0, (at - now) / 1000) : NaN;
+        }
+        if (Number.isFinite(secs) && secs >= 0)
+            return Math.min(secs, 30) * 1000 + random() * 100;
+    }
+    return Math.min(8000, 500 * 2 ** serverAttempt) + random() * 250;
+}
+function fetchErrorCode(err) {
+    const e = err;
+    return e?.cause?.code ?? e?.cause?.cause?.code ?? e?.code;
+}
+/** fetch() failed before the request reached the server. */
+function isConnectFailure(err) {
+    const code = fetchErrorCode(err);
+    return code !== undefined && CONNECT_FAILURE_CODES.has(code);
+}
+function describeFetchError(err) {
+    return fetchErrorCode(err) ?? err?.message ?? String(err);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Map GET storage errors: rethrow 403, return undefined for 404 (triggers getOrCreate for names only). */
 function handleStorageGetError(err) {
     if (isApiStorageClientError(err)) {
@@ -175,17 +225,11 @@ function storageCollectionHeaders(config) {
 /** POST /v2/{datasets|key-value-stores|request-queues} to create or get-by-name. */
 async function postStorageCollection(config, path, name) {
     const query = name ? `?name=${encodeURIComponent(name)}` : '';
-    const url = `${config.apiUrl}/v2${path}${query}`;
-    const response = await fetch(url, {
-        method: 'POST',
-        headers: storageCollectionHeaders(config),
-    });
-    if (!response.ok) {
-        const error = await response.json().catch(() => ({ error: { message: response.statusText } }));
-        throw new Error(error.error?.message || `Failed to create storage: ${response.status}`);
-    }
-    const body = await response.json();
-    return unwrapData(body);
+    // Not marked repeatable even by name: a 500 after the create (e.g. scoped
+    // token registration failed) must surface, since a re-send would take the
+    // existing-name path and hide it. POST rules apply (limiter/HAProxy 503,
+    // refused connection).
+    return new CollectionApiClient(config).call('POST', `${path}${query}`);
 }
 /**
  * Helper to create AsyncIterable + Promise result (matches Crawlee pattern)
@@ -226,6 +270,10 @@ class BaseApiClient {
     static rateLimiter = new AdaptiveRateLimiter();
     // Maximum retries for rate-limited requests
     static maxRetries = 3;
+    // Retries while the API is briefly unavailable (503/5xx, connection
+    // refused): backoff 0.5 s doubling to 8 s, about 45 s in total, which
+    // covers a main redeploy.
+    static maxServerRetries = 8;
     // Default timeout for requests (30 seconds)
     static defaultTimeoutMs = 30000;
     constructor(config) {
@@ -236,7 +284,13 @@ class BaseApiClient {
             'Content-Type': 'application/json',
         };
     }
-    async request(method, path, body, contentType, options) {
+    /**
+     * Sends the request and returns the successful (2xx) response, with the
+     * retry policy: 429 (rate limiter), timeouts, and the API being briefly
+     * unavailable (503, 5xx for idempotent methods, connection failures).
+     * Non-2xx answers that are not retried throw ApiStorageClientError.
+     */
+    async send(method, path, body, contentType, options, decode) {
         const url = `${this.config.apiUrl}/v2${path}`;
         const headers = { ...this.headers };
         if (contentType) {
@@ -246,8 +300,10 @@ class BaseApiClient {
             ? options.timeoutSecs * 1000
             : BaseApiClient.defaultTimeoutMs;
         const shouldRetryTimeouts = options?.doNotRetryTimeouts !== true;
-        let lastError = null;
-        for (let attempt = 0; attempt <= BaseApiClient.maxRetries; attempt++) {
+        const idempotent = options?.idempotent ?? IDEMPOTENT_METHODS.has(method.toUpperCase());
+        let attempt = 0; // timeouts and 429s
+        let serverAttempt = 0; // 503/5xx and connection failures (API briefly unavailable)
+        for (;;) {
             // Wait for rate limiter slot before making request
             await BaseApiClient.rateLimiter.waitForSlot();
             // Create AbortController for timeout
@@ -265,89 +321,110 @@ class BaseApiClient {
                 // Handle rate limiting (429)
                 if (response.status === 429) {
                     if (attempt < BaseApiClient.maxRetries) {
+                        attempt++;
                         await BaseApiClient.rateLimiter.handleRateLimited(response);
                         continue; // Retry
                     }
-                    // Max retries exceeded
                     const error = await response.json().catch(() => ({ error: { message: 'Rate limit exceeded' } }));
-                    throw new Error(error.error?.message || 'Rate limit exceeded');
+                    throw new ApiStorageClientError(error.error?.message || 'Rate limit exceeded', 429);
                 }
-                if (!response.ok) {
-                    const error = await response.json().catch(() => ({ error: { message: response.statusText } }));
-                    throw new ApiStorageClientError(error.error?.message || `API request failed: ${response.status}`, response.status);
+                if (response.ok) {
+                    try {
+                        // Decoded inside the retry loop: a body cut off after
+                        // the headers is a transport failure like any other.
+                        return await decode(response);
+                    }
+                    catch (bodyErr) {
+                        // The request was applied (2xx); a write whose answer
+                        // timed out while being read must not be sent again.
+                        if (bodyErr.name === 'AbortError' && !idempotent) {
+                            const timeoutError = new Error(`Request timed out after ${timeoutMs}ms (response body; the request was applied)`);
+                            timeoutError.isTimeout = true;
+                            throw timeoutError;
+                        }
+                        if (idempotent && bodyErr.name !== 'AbortError' && serverAttempt < BaseApiClient.maxServerRetries) {
+                            const waitMs = serverRetryDelayMs(serverAttempt, null);
+                            serverAttempt++;
+                            console.warn(`[Scrapely] ${method} ${path} response body failed (${describeFetchError(bodyErr)}); retry ${serverAttempt}/${BaseApiClient.maxServerRetries} in ${Math.round(waitMs)}ms`);
+                            await sleep(waitMs);
+                            continue;
+                        }
+                        throw bodyErr;
+                    }
                 }
-                // Handle empty responses (204 No Content)
-                if (response.status === 204) {
-                    return undefined;
+                // API briefly unavailable (main redeploy, limiter store blip).
+                const text = await response.text().catch(() => '');
+                let errorBody;
+                try {
+                    errorBody = JSON.parse(text);
                 }
-                // Handle text/plain responses
-                const responseContentType = response.headers.get('content-type') || '';
-                if (responseContentType.includes('text/plain')) {
-                    return response.text();
+                catch {
+                    errorBody = undefined;
                 }
-                // Handle binary responses
-                if (responseContentType.includes('application/octet-stream')) {
-                    const buffer = Buffer.from(await response.arrayBuffer());
-                    return buffer;
+                if (isRetryableResponse(response.status, idempotent, errorBody?.error?.type, text)
+                    && serverAttempt < BaseApiClient.maxServerRetries) {
+                    const waitMs = serverRetryDelayMs(serverAttempt, response.headers.get('retry-after'));
+                    serverAttempt++;
+                    console.warn(`[Scrapely] ${method} ${path} answered ${response.status}; retry ${serverAttempt}/${BaseApiClient.maxServerRetries} in ${Math.round(waitMs)}ms`);
+                    await sleep(waitMs);
+                    continue;
                 }
-                const json = await response.json();
-                return unwrapData(json);
+                throw new ApiStorageClientError(errorBody?.error?.message || response.statusText || `API request failed: ${response.status}`, response.status);
             }
             catch (err) {
                 // Handle timeout/abort errors
                 if (err.name === 'AbortError') {
                     const timeoutError = new Error(`Request timed out after ${timeoutMs}ms`);
                     timeoutError.isTimeout = true;
-                    lastError = timeoutError;
                     // Don't retry if doNotRetryTimeouts is true
                     if (!shouldRetryTimeouts || attempt >= BaseApiClient.maxRetries) {
                         throw timeoutError;
                     }
+                    attempt++;
                     // Wait a bit before retrying
-                    await new Promise(resolve => setTimeout(resolve, 100 * (attempt + 1)));
+                    await sleep(100 * attempt);
                     continue;
                 }
-                lastError = err;
-                // Don't retry non-timeout errors unless it's a network issue
-                const isNetworkError = !err.response && !err.status;
-                if (!isNetworkError || attempt >= BaseApiClient.maxRetries) {
+                // HTTP errors (already decided above) are final.
+                if (isApiStorageClientError(err))
                     throw err;
+                // fetch() failed without a response. A refused/unresolvable
+                // connection never reached the API, so it is safe for every
+                // method; anything else (reset mid-request) only for idempotent ones.
+                if ((idempotent || isConnectFailure(err)) && serverAttempt < BaseApiClient.maxServerRetries) {
+                    const waitMs = serverRetryDelayMs(serverAttempt, null);
+                    serverAttempt++;
+                    console.warn(`[Scrapely] ${method} ${path} failed (${describeFetchError(err)}); retry ${serverAttempt}/${BaseApiClient.maxServerRetries} in ${Math.round(waitMs)}ms`);
+                    await sleep(waitMs);
+                    continue;
                 }
-                // Wait before retrying network errors
-                await new Promise(resolve => setTimeout(resolve, 100 * (attempt + 1)));
+                throw err;
             }
             finally {
                 clearTimeout(timeoutId);
             }
         }
-        throw lastError || new Error('Request failed after retries');
     }
-    async requestWithHeaders(method, path, body, contentType) {
-        const url = `${this.config.apiUrl}/v2${path}`;
-        const headers = { ...this.headers };
-        if (contentType) {
-            headers['Content-Type'] = contentType;
-        }
-        for (let attempt = 0; attempt <= BaseApiClient.maxRetries; attempt++) {
-            await BaseApiClient.rateLimiter.waitForSlot();
-            const response = await fetch(url, {
-                method,
-                headers,
-                body: body !== undefined ? (typeof body === 'string' ? body : JSON.stringify(body)) : undefined,
-            });
-            BaseApiClient.rateLimiter.updateFromHeaders(response.headers);
-            if (response.status === 429) {
-                if (attempt < BaseApiClient.maxRetries) {
-                    await BaseApiClient.rateLimiter.handleRateLimited(response);
-                    continue;
-                }
-                const error = await response.json().catch(() => ({ error: { message: 'Rate limit exceeded' } }));
-                throw new Error(error.error?.message || 'Rate limit exceeded');
+    async request(method, path, body, contentType, options) {
+        return this.send(method, path, body, contentType, options, async (response) => {
+            // Handle empty responses (204 No Content)
+            if (response.status === 204) {
+                return undefined;
             }
-            if (!response.ok) {
-                const error = await response.json().catch(() => ({ error: { message: response.statusText } }));
-                throw new Error(error.error?.message || `API request failed: ${response.status}`);
+            // Handle text/plain responses
+            const responseContentType = response.headers.get('content-type') || '';
+            if (responseContentType.includes('text/plain')) {
+                return (await response.text());
             }
+            // Handle binary responses
+            if (responseContentType.includes('application/octet-stream')) {
+                return Buffer.from(await response.arrayBuffer());
+            }
+            return unwrapData(await response.json());
+        });
+    }
+    async requestWithHeaders(method, path, body, contentType) {
+        return this.send(method, path, body, contentType, undefined, async (response) => {
             if (response.status === 204) {
                 return { data: undefined, contentType: '' };
             }
@@ -356,13 +433,18 @@ class BaseApiClient {
                 return { data: await response.text(), contentType: 'text/plain' };
             }
             if (responseContentType.includes('application/octet-stream')) {
-                const buffer = Buffer.from(await response.arrayBuffer());
-                return { data: buffer, contentType: 'application/octet-stream' };
+                return { data: Buffer.from(await response.arrayBuffer()), contentType: 'application/octet-stream' };
             }
             const json = await response.json();
             return { data: json, contentType: responseContentType.split(';')[0].trim() || 'application/json' };
-        }
-        throw new Error('Request failed after retries');
+        });
+    }
+}
+exports.BaseApiClient = BaseApiClient;
+/** Collection-level calls (create/get by name, list) with the same retry policy. */
+class CollectionApiClient extends BaseApiClient {
+    call(method, path, options) {
+        return this.request(method, path, undefined, undefined, options);
     }
 }
 /**
@@ -531,8 +613,12 @@ class ApiKeyValueStoreClient extends BaseApiClient {
             }
             return { key, value, contentType: contentType || 'application/json' };
         }
-        catch {
-            return undefined;
+        catch (err) {
+            // Missing record only; anything else (API unavailable after the
+            // retries) must not look like "no record" (lost state, restarts).
+            if (isApiStorageClientError(err) && err.statusCode === 404)
+                return undefined;
+            throw err;
         }
     }
     async setRecord(record, options) {
@@ -850,17 +936,7 @@ class ApiRequestQueueCollectionClient {
         };
     }
     async list() {
-        const url = `${this.config.apiUrl}/v2/request-queues`;
-        const response = await fetch(url, {
-            headers: storageCollectionHeaders(this.config),
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: { message: response.statusText } }));
-            throw new Error(error.error?.message
-                || `Failed to list request queues: ${response.status}`);
-        }
-        const body = await response.json();
-        const data = unwrapData(body);
+        const data = await new CollectionApiClient(this.config).call('GET', '/request-queues');
         return {
             total: data.total,
             count: data.count,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "scrapely",
-    "version": "1.2.10",
+    "version": "1.2.12",
     "description": "Scrapely SDK for building JavaScript and TypeScript Actors",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -19,6 +19,7 @@
     "scripts": {
         "test": "npx tsx tests/test-mvp.ts",
         "test:charging": "npx tsx --test tests/charging-pending.test.ts",
+        "test:storage-retries": "npx tsx --test tests/storage-retries.test.ts",
         "test:stdio-drain": "npx tsx --test tests/stdio-drain.test.ts",
         "test:charging-client": "npx tsx --test tests/charging-client.test.ts",
         "test:proxy": "npx tsx --test tests/proxy-configuration.test.ts",
@@ -35,7 +36,9 @@
         "test:init-rollback": "npx tsx --test tests/init-rollback.test.ts",
         "test:apify-parity": "npx tsx --test tests/apify-parity.test.ts",
         "test:run-control": "npx tsx --test tests/run-control.test.ts",
-        "test:rq-list": "npx tsx --test tests/rq-list-requests.test.ts"
+        "test:rq-list": "npx tsx --test tests/rq-list-requests.test.ts",
+        "test:terminal-status": "npx tsx --test tests/terminal-status-message.test.ts",
+        "test:cdp-retry": "npx tsx --test tests/cdp-retry.test.ts"
     },
     "author": "SandeepDev1",
     "license": "ISC",