scrapely 1.2.19 → 1.2.20

package/dist/actor.d.ts

@@ -21,6 +21,7 @@ import { type ApiStorageConfig } from './storage/api-storage-client.js';
 import { ChargingManager, type ChargeOptions as ChargingChargeOptions, type ChargeResult as ChargingChargeResult } from './charging.js';
 import { createProxyConfiguration, type CreateProxyConfigurationOptions } from './proxy-configuration.js';
 import { type BrowserConfiguration, type BrowserConfigurationOptions } from './browser-configuration.js';
+import { type Clearance, type SolveOptions, type SolverVendorStatus } from './solver.js';
 import type { Dataset, KeyValueStore, RequestQueue } from 'crawlee';
 /** User function passed to {@link Actor.main} (Apify-compatible). */
 export type UserFunc<T = unknown> = () => T | Promise<T>;
@@ -530,6 +531,25 @@ export declare class Actor {
      * @returns The updated ActorRun object, or an empty object if running locally
      */
     static setStatusMessage(message: string, options?: SetStatusMessageOptions): Promise<ActorRun>;
+    /**
+     * Anti-bot solver status for a vendor (free, cached for 15 s, never throws).
+     * `usable: false` means the vendor cannot be solved right now: take your
+     * fallback (for example the hosted browser), or fail the items that need a
+     * solve at once and call `setSolverDegradedStatus()`.
+     */
+    static solverStatus(vendor: string): Promise<SolverVendorStatus>;
+    /**
+     * Solves one anti-bot challenge on the Actor's own session through the
+     * platform solver. See `solve` in `scrapely` (solver.ts) for the options.
+     */
+    static solve(options: SolveOptions): Promise<Clearance>;
+    /**
+     * Sets the standard status message for a run whose site protection cannot
+     * be solved right now ("Site protection temporarily unavailable, results
+     * may be incomplete", plus "(N of M items skipped)" when both counts are
+     * given). Never throws: the run goes on.
+     */
+    static setSolverDegradedStatus(skipped?: number, total?: number): Promise<void>;
     /**
      * Creates a proxy configuration and returns a promise resolving to an instance
      * of the ProxyConfiguration class that is already initialized.

package/dist/actor.js

@@ -33,6 +33,7 @@ const charging_client_js_1 = require("./charging_client.js");
 const proxy_configuration_js_1 = require("./proxy-configuration.js");
 const browser_configuration_js_1 = require("./browser-configuration.js");
 const utils_js_1 = require("./utils.js");
+const solver_js_1 = require("./solver.js");
 /** "429 Run API rate limit exceeded ..." for an API error, the message otherwise. */
 function describeRunApiError(err) {
     const status = err.statusCode;
@@ -1073,6 +1074,36 @@ class Actor {
         });
         return (body?.data ?? {});
     }
+    /**
+     * Anti-bot solver status for a vendor (free, cached for 15 s, never throws).
+     * `usable: false` means the vendor cannot be solved right now: take your
+     * fallback (for example the hosted browser), or fail the items that need a
+     * solve at once and call `setSolverDegradedStatus()`.
+     */
+    static async solverStatus(vendor) {
+        return (0, solver_js_1.solverStatus)(vendor);
+    }
+    /**
+     * Solves one anti-bot challenge on the Actor's own session through the
+     * platform solver. See `solve` in `scrapely` (solver.ts) for the options.
+     */
+    static async solve(options) {
+        return (0, solver_js_1.solve)(options);
+    }
+    /**
+     * Sets the standard status message for a run whose site protection cannot
+     * be solved right now ("Site protection temporarily unavailable, results
+     * may be incomplete", plus "(N of M items skipped)" when both counts are
+     * given). Never throws: the run goes on.
+     */
+    static async setSolverDegradedStatus(skipped, total) {
+        try {
+            await Actor.setStatusMessage((0, solver_js_1.degradedStatusMessage)(skipped, total));
+        }
+        catch (err) {
+            console.warn(`Could not set the solver status message: ${err.message}`);
+        }
+    }
     /**
      * Creates a proxy configuration and returns a promise resolving to an instance
      * of the ProxyConfiguration class that is already initialized.

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { Actor, ACTOR_PERMISSION_LEVEL, type ActorInput, type InitOptions, type
 export type { StorageAlias, StorageId, StorageName, StorageIdentifier, StorageIdentifierWithoutAlias, } from './storage-identifiers.js';
 export { ApifyClient, type ApifyClientOptions, type ActorRun } from 'scrapely-client';
 export { Configuration, type ConfigurationOptions } from './configuration.js';
+export { DEGRADED_STATUS_MESSAGE, IpBanned, SolveAttemptError, SolverAuthError, SolverRateLimited, VendorUnavailable, degradedStatusMessage, detectVendor, isBlocked, reportSolveOutcome, solve, solverConfigured, solverStatus, stepAllowed, type Clearance, type SolveCookie, type SolveOptions, type SolverStepRequest, type SolverVendorStatus, } from './solver.js';
 export { ScrapelyEventManager as PlatformEventManager } from './events/scrapely-event-manager.js';
 export { ChargingManager, ChargeUncertainError, ChargeRejectedError, DEFAULT_DATASET_ITEM_EVENT, APIFY_DEFAULT_DATASET_ITEM_EVENT, SCRAPELY_DEFAULT_DATASET_ITEM_EVENT, hasDefaultDatasetItemEventInPricing, isDefaultDatasetItemEvent, resolveDefaultDatasetItemEventName, mergeChargeResults, pushDataAndCharge, type ChargeOptions, type ChargeResult, type ActorPricingInfo, } from './charging.js';
 export { createChargingClient, pushDataChargingContext, USES_PUSH_DATA_INTERCEPTION, type PpeAwarePushDataContext, } from './charging_client.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LinkeDOMCrawler = exports.JSDOMCrawler = exports.BrowserCrawler = exports.BasicCrawler = exports.HttpCrawler = exports.CheerioCrawler = exports.PuppeteerCrawler = exports.PlaywrightCrawler = exports.ScrapelyRequestList = exports.enqueueLinks = exports.utils = exports.LoggerText = exports.LoggerJson = exports.Logger = exports.LogLevel = exports.Log = exports.log = exports.RequestQueue = exports.KeyValueStore = exports.Dataset = exports.createBrowserConfiguration = exports.BrowserConfiguration = exports.getPlatformProxyEnv = exports.createProxyConfiguration = exports.validateProxySessionId = exports.isPlatformProxySentinel = exports.ProxyConfiguration = exports.ApiStorageClientFactory = exports.BillingTracker = exports.USES_PUSH_DATA_INTERCEPTION = exports.pushDataChargingContext = exports.createChargingClient = exports.pushDataAndCharge = exports.mergeChargeResults = exports.resolveDefaultDatasetItemEventName = exports.isDefaultDatasetItemEvent = exports.hasDefaultDatasetItemEventInPricing = exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT = exports.APIFY_DEFAULT_DATASET_ITEM_EVENT = exports.DEFAULT_DATASET_ITEM_EVENT = exports.ChargeRejectedError = exports.ChargeUncertainError = exports.ChargingManager = exports.PlatformEventManager = exports.Configuration = exports.ApifyClient = exports.EXIT_CODES = exports.ACTOR_PERMISSION_LEVEL = exports.Actor = exports.setCdpUrl = void 0;
-exports.puppeteerUtils = exports.playwrightUtils = void 0;
+exports.LogLevel = exports.Log = exports.log = exports.RequestQueue = exports.KeyValueStore = exports.Dataset = exports.createBrowserConfiguration = exports.BrowserConfiguration = exports.getPlatformProxyEnv = exports.createProxyConfiguration = exports.validateProxySessionId = exports.isPlatformProxySentinel = exports.ProxyConfiguration = exports.ApiStorageClientFactory = exports.BillingTracker = exports.USES_PUSH_DATA_INTERCEPTION = exports.pushDataChargingContext = exports.createChargingClient = exports.pushDataAndCharge = exports.mergeChargeResults = exports.resolveDefaultDatasetItemEventName = exports.isDefaultDatasetItemEvent = exports.hasDefaultDatasetItemEventInPricing = exports.SCRAPELY_DEFAULT_DATASET_ITEM_EVENT = exports.APIFY_DEFAULT_DATASET_ITEM_EVENT = exports.DEFAULT_DATASET_ITEM_EVENT = exports.ChargeRejectedError = exports.ChargeUncertainError = exports.ChargingManager = exports.PlatformEventManager = exports.stepAllowed = exports.solverStatus = exports.solverConfigured = exports.solve = exports.reportSolveOutcome = exports.isBlocked = exports.detectVendor = exports.degradedStatusMessage = exports.VendorUnavailable = exports.SolverRateLimited = exports.SolverAuthError = exports.SolveAttemptError = exports.IpBanned = exports.DEGRADED_STATUS_MESSAGE = exports.Configuration = exports.ApifyClient = exports.EXIT_CODES = exports.ACTOR_PERMISSION_LEVEL = exports.Actor = exports.setCdpUrl = void 0;
+exports.puppeteerUtils = exports.playwrightUtils = exports.LinkeDOMCrawler = exports.JSDOMCrawler = exports.BrowserCrawler = exports.BasicCrawler = exports.HttpCrawler = exports.CheerioCrawler = exports.PuppeteerCrawler = exports.PlaywrightCrawler = exports.ScrapelyRequestList = exports.enqueueLinks = exports.utils = exports.LoggerText = exports.LoggerJson = exports.Logger = void 0;
 require("./log-env.js");
 var patch_browser_pool_js_1 = require("./patch-browser-pool.js");
 Object.defineProperty(exports, "setCdpUrl", { enumerable: true, get: function () { return patch_browser_pool_js_1.setCdpUrl; } });
@@ -14,6 +14,21 @@ var scrapely_client_1 = require("scrapely-client");
 Object.defineProperty(exports, "ApifyClient", { enumerable: true, get: function () { return scrapely_client_1.ApifyClient; } });
 var configuration_js_1 = require("./configuration.js");
 Object.defineProperty(exports, "Configuration", { enumerable: true, get: function () { return configuration_js_1.Configuration; } });
+var solver_js_1 = require("./solver.js");
+Object.defineProperty(exports, "DEGRADED_STATUS_MESSAGE", { enumerable: true, get: function () { return solver_js_1.DEGRADED_STATUS_MESSAGE; } });
+Object.defineProperty(exports, "IpBanned", { enumerable: true, get: function () { return solver_js_1.IpBanned; } });
+Object.defineProperty(exports, "SolveAttemptError", { enumerable: true, get: function () { return solver_js_1.SolveAttemptError; } });
+Object.defineProperty(exports, "SolverAuthError", { enumerable: true, get: function () { return solver_js_1.SolverAuthError; } });
+Object.defineProperty(exports, "SolverRateLimited", { enumerable: true, get: function () { return solver_js_1.SolverRateLimited; } });
+Object.defineProperty(exports, "VendorUnavailable", { enumerable: true, get: function () { return solver_js_1.VendorUnavailable; } });
+Object.defineProperty(exports, "degradedStatusMessage", { enumerable: true, get: function () { return solver_js_1.degradedStatusMessage; } });
+Object.defineProperty(exports, "detectVendor", { enumerable: true, get: function () { return solver_js_1.detectVendor; } });
+Object.defineProperty(exports, "isBlocked", { enumerable: true, get: function () { return solver_js_1.isBlocked; } });
+Object.defineProperty(exports, "reportSolveOutcome", { enumerable: true, get: function () { return solver_js_1.reportSolveOutcome; } });
+Object.defineProperty(exports, "solve", { enumerable: true, get: function () { return solver_js_1.solve; } });
+Object.defineProperty(exports, "solverConfigured", { enumerable: true, get: function () { return solver_js_1.solverConfigured; } });
+Object.defineProperty(exports, "solverStatus", { enumerable: true, get: function () { return solver_js_1.solverStatus; } });
+Object.defineProperty(exports, "stepAllowed", { enumerable: true, get: function () { return solver_js_1.stepAllowed; } });
 var scrapely_event_manager_js_1 = require("./events/scrapely-event-manager.js");
 Object.defineProperty(exports, "PlatformEventManager", { enumerable: true, get: function () { return scrapely_event_manager_js_1.ScrapelyEventManager; } });
 var charging_js_1 = require("./charging.js");

package/dist/solver.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Anti-bot solver helpers (JS). Python parity: scrapely-python `scrapely.solver`.
+ *
+ * The platform runs the challenge solver behind /v2/solver; Actors never
+ * hold a solver key. Runs of Actors that may use it get SCRAPELY_SOLVER_URL
+ * and SCRAPELY_SOLVER_API_KEY (the run's own token).
+ *
+ *   const st = await Actor.solverStatus('datadome');      // free, cached 15 s
+ *   if (!st.usable) { ...fallback or fail the item fast... }
+ *
+ *   const clearance = await Actor.solve({
+ *       url, response: { status, body },                  // the blocked response
+ *       fetch: (req) => mySession(req),                   // send step requests on YOUR session
+ *       sessionId: 's-42', identity: 'chrome-146-macos',
+ *   });
+ *   // clearance.cookies -> put them in your cookie jar (fetch already sent the rest)
+ *
+ * Errors: SolveAttemptError (retry on a fresh exit), IpBanned, VendorUnavailable
+ * (fail fast, `code`), SolverRateLimited, SolverAuthError.
+ */
+export declare const DEGRADED_STATUS_MESSAGE = "Site protection temporarily unavailable, results may be incomplete";
+export declare class SolveAttemptError extends Error {
+    constructor(message: string);
+}
+export declare class IpBanned extends SolveAttemptError {
+    constructor(message: string);
+}
+export declare class SolverRateLimited extends SolveAttemptError {
+    readonly retryAfterSecs: number | null;
+    constructor(retryAfterSecs?: number | null);
+}
+export declare class SolverAuthError extends SolveAttemptError {
+    constructor(message: string);
+}
+/** The platform says this vendor cannot be solved right now. Fail fast; do not retry. */
+export declare class VendorUnavailable extends Error {
+    readonly code: string;
+    readonly vendor: string | null;
+    readonly retryAfterSecs: number | null;
+    constructor(code: string, vendor?: string | null, retryAfterSecs?: number | null, message?: string);
+}
+export interface SolverVendorStatus {
+    status: 'healthy' | 'degraded' | 'down' | 'unsupported' | 'unknown';
+    usable: boolean;
+    code: string | null;
+    successRate30m: number | null;
+    since: string | null;
+    recheckAfterSecs: number;
+}
+export interface SolverStepRequest {
+    id: string;
+    method: 'GET' | 'POST';
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface SolveCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+}
+export interface SolveOptions {
+    /** The page that was blocked. */
+    url: string;
+    /** The blocked response. */
+    response: {
+        status: number;
+        body: string;
+    };
+    /** Sends one step request on the Actor's own session (same exit IP); returns its status and body. */
+    fetch: (request: SolverStepRequest) => Promise<{
+        status: number;
+        body: string;
+    }>;
+    /** 'datadome', 'akamai-sbsd' or 'auto' (default). */
+    vendor?: string;
+    /** Proxy session id (enables the platform's clearance cache for that exit). */
+    sessionId?: string;
+    /** Browser profile the TLS impersonation claims (default chrome-146-macos), or an object with locale. */
+    identity?: string | {
+        profile?: string;
+        acceptLanguage?: string;
+        timezone?: string;
+        languages?: string;
+    };
+    /** Cookie header the session holds for the site (SBSD needs it). */
+    cookieHeader?: () => string | null | Promise<string | null>;
+    /** Verifies the clearance (cookies already applied by you or by `fetch`); reported to the platform. */
+    verify?: (cookies: SolveCookie[]) => Promise<boolean> | boolean;
+    timeoutMs?: number;
+}
+export interface Clearance {
+    solveId: string | null;
+    cookies: SolveCookie[];
+    ttlHintSecs: number;
+    cached: boolean;
+    verified: boolean | null;
+}
+/** True when the platform solver API is available to this run. */
+export declare function solverConfigured(): boolean;
+/**
+ * The protection behind a *challenge* response. Ordinary pages that merely load a
+ * vendor script are not challenges: DataDome, PerimeterX and Kasada need a 4xx
+ * status; an SBSD bundle counts only on a short interstitial page.
+ */
+export declare function detectVendor(status: number, body: string): string | null;
+/** A step may only go to the target page's own host or to captcha-delivery.com, over https. */
+export declare function stepAllowed(stepUrl: string, targetUrl: string): boolean;
+export declare function isBlocked(response: {
+    status: number;
+    body: string;
+}, vendor?: string): boolean;
+export declare function degradedStatusMessage(skipped?: number, total?: number): string;
+/** Vendor status from the platform (free, cached for 15 s). Never throws. */
+export declare function solverStatus(vendor: string): Promise<SolverVendorStatus>;
+/** Solves one challenge on the Actor's session through the platform. */
+export declare function solve(options: SolveOptions): Promise<Clearance>;
+/** Reports your own verification of a clearance (when `verify` was not passed to solve). */
+export declare function reportSolveOutcome(clearance: Clearance, verified: boolean): Promise<void>;
+/** Test hook. */
+export declare function clearSolverStatusCache(): void;

package/dist/solver.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * Anti-bot solver helpers (JS). Python parity: scrapely-python `scrapely.solver`.
+ *
+ * The platform runs the challenge solver behind /v2/solver; Actors never
+ * hold a solver key. Runs of Actors that may use it get SCRAPELY_SOLVER_URL
+ * and SCRAPELY_SOLVER_API_KEY (the run's own token).
+ *
+ *   const st = await Actor.solverStatus('datadome');      // free, cached 15 s
+ *   if (!st.usable) { ...fallback or fail the item fast... }
+ *
+ *   const clearance = await Actor.solve({
+ *       url, response: { status, body },                  // the blocked response
+ *       fetch: (req) => mySession(req),                   // send step requests on YOUR session
+ *       sessionId: 's-42', identity: 'chrome-146-macos',
+ *   });
+ *   // clearance.cookies -> put them in your cookie jar (fetch already sent the rest)
+ *
+ * Errors: SolveAttemptError (retry on a fresh exit), IpBanned, VendorUnavailable
+ * (fail fast, `code`), SolverRateLimited, SolverAuthError.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VendorUnavailable = exports.SolverAuthError = exports.SolverRateLimited = exports.IpBanned = exports.SolveAttemptError = exports.DEGRADED_STATUS_MESSAGE = void 0;
+exports.solverConfigured = solverConfigured;
+exports.detectVendor = detectVendor;
+exports.stepAllowed = stepAllowed;
+exports.isBlocked = isBlocked;
+exports.degradedStatusMessage = degradedStatusMessage;
+exports.solverStatus = solverStatus;
+exports.solve = solve;
+exports.reportSolveOutcome = reportSolveOutcome;
+exports.clearSolverStatusCache = clearSolverStatusCache;
+exports.DEGRADED_STATUS_MESSAGE = 'Site protection temporarily unavailable, results may be incomplete';
+const COMPAT_SUFFIX = '/compat/xhrdev';
+const STATUS_TTL_MS = 15_000;
+const MAX_BODY = 4 * 1024 * 1024;
+const UNAVAILABLE_CODES = new Set(['vendor_degraded', 'vendor_down', 'provider_unavailable', 'vendor_unsupported', 'solver_not_enabled']);
+class SolveAttemptError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SolveAttemptError';
+    }
+}
+exports.SolveAttemptError = SolveAttemptError;
+class IpBanned extends SolveAttemptError {
+    constructor(message) {
+        super(message);
+        this.name = 'IpBanned';
+    }
+}
+exports.IpBanned = IpBanned;
+class SolverRateLimited extends SolveAttemptError {
+    retryAfterSecs;
+    constructor(retryAfterSecs = null) {
+        super(`solver rate limit hit (HTTP 429${retryAfterSecs !== null ? `, retry after ${retryAfterSecs}s` : ''})`);
+        this.retryAfterSecs = retryAfterSecs;
+        this.name = 'SolverRateLimited';
+    }
+}
+exports.SolverRateLimited = SolverRateLimited;
+class SolverAuthError extends SolveAttemptError {
+    constructor(message) {
+        super(message);
+        this.name = 'SolverAuthError';
+    }
+}
+exports.SolverAuthError = SolverAuthError;
+/** The platform says this vendor cannot be solved right now. Fail fast; do not retry. */
+class VendorUnavailable extends Error {
+    code;
+    vendor;
+    retryAfterSecs;
+    constructor(code, vendor = null, retryAfterSecs = null, message) {
+        super(message ?? `anti-bot solver unavailable (${code}${vendor ? `, ${vendor}` : ''})`);
+        this.code = code;
+        this.vendor = vendor;
+        this.retryAfterSecs = retryAfterSecs;
+        this.name = 'VendorUnavailable';
+    }
+}
+exports.VendorUnavailable = VendorUnavailable;
+function solverEnv() {
+    const url = (process.env.SCRAPELY_SOLVER_URL ?? '').trim().replace(/\/+$/, '');
+    const key = (process.env.SCRAPELY_SOLVER_API_KEY ?? '').trim();
+    return url && key ? { url, key } : null;
+}
+function gateway() {
+    const env = solverEnv();
+    if (!env || !env.url.endsWith(COMPAT_SUFFIX))
+        return null;
+    return { base: env.url.slice(0, -COMPAT_SUFFIX.length), key: env.key };
+}
+/** True when the platform solver API is available to this run. */
+function solverConfigured() {
+    return gateway() !== null;
+}
+/**
+ * The protection behind a *challenge* response. Ordinary pages that merely load a
+ * vendor script are not challenges: DataDome, PerimeterX and Kasada need a 4xx
+ * status; an SBSD bundle counts only on a short interstitial page.
+ */
+function detectVendor(status, body) {
+    const all = body || '';
+    const sample = all.slice(0, 20000);
+    const head = sample.slice(0, 4000).toLowerCase();
+    const challenged = status >= 400;
+    if (challenged && (head.includes('captcha-delivery.com') || /var\s+dd\s*=\s*\{/.test(sample) || head.includes('datadome')))
+        return 'datadome';
+    if (all.length <= 20000 && /<script[^>]+src="([^"]+\?v=[0-9a-f-]{36}[^"]*)"/i.test(sample))
+        return 'akamai-sbsd';
+    if (challenged && /_pxappid|px-captcha|perimeterx|\/_px\d?\//i.test(sample))
+        return 'perimeterx';
+    if (challenged && /kpsdk/i.test(sample))
+        return 'kasada';
+    return null;
+}
+/** A step may only go to the target page's own host or to captcha-delivery.com, over https. */
+function stepAllowed(stepUrl, targetUrl) {
+    try {
+        const step = new URL(stepUrl);
+        const target = new URL(targetUrl);
+        if (step.protocol !== 'https:')
+            return false;
+        const host = step.hostname.toLowerCase();
+        return host === target.hostname.toLowerCase() || host === 'captcha-delivery.com' || host.endsWith('.captcha-delivery.com');
+    }
+    catch {
+        return false;
+    }
+}
+function isBlocked(response, vendor) {
+    const found = detectVendor(response.status, response.body);
+    return !vendor || vendor === 'auto' ? found !== null : found === vendor;
+}
+function degradedStatusMessage(skipped, total) {
+    return skipped !== undefined && total !== undefined ? `${exports.DEGRADED_STATUS_MESSAGE} (${skipped} of ${total} items skipped)` : exports.DEGRADED_STATUS_MESSAGE;
+}
+const statusCache = new Map();
+function unknownStatus(code = null) {
+    return { status: 'unknown', usable: code === null, code, successRate30m: null, since: null, recheckAfterSecs: 300 };
+}
+/** Vendor status from the platform (free, cached for 15 s). Never throws. */
+async function solverStatus(vendor) {
+    const name = (vendor || '').trim().toLowerCase();
+    const hit = statusCache.get(name);
+    if (hit && Date.now() - hit.at < STATUS_TTL_MS)
+        return hit.value;
+    const gw = gateway();
+    if (!gw)
+        return unknownStatus(solverEnv() ? null : 'solver_not_enabled');
+    try {
+        const res = await fetch(`${gw.base}/status?vendors=${encodeURIComponent(name)}`, {
+            headers: { authorization: `Bearer ${gw.key}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return unknownStatus();
+        const data = (await res.json());
+        const value = data.vendors?.[name] ?? unknownStatus();
+        statusCache.set(name, { at: Date.now(), value });
+        return value;
+    }
+    catch {
+        return unknownStatus();
+    }
+}
+async function api(path, body, key, base, timeoutMs) {
+    let res;
+    try {
+        res = await fetch(`${base}${path}`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        // Gateway unreachable or timed out: one failed try, retried on a fresh session.
+        throw new SolveAttemptError(`solver gateway unreachable: ${err.name}`);
+    }
+    let data = {};
+    try {
+        data = await res.json();
+    }
+    catch {
+        data = {};
+    }
+    return { status: res.status, data, retryAfter: res.headers.get('retry-after') };
+}
+function handle(r, vendor) {
+    const { status, data } = r;
+    if (status === 503 && UNAVAILABLE_CODES.has(String(data.code ?? '')))
+        throw new VendorUnavailable(String(data.code), data.vendor ?? vendor, data.retryAfterSecs ?? null);
+    if (status === 429)
+        throw new SolverRateLimited(r.retryAfter ? Number(r.retryAfter) : (data.retryAfterSecs ?? null));
+    if (status === 401 || status === 403) {
+        if (data.code === 'solver_not_enabled')
+            throw new VendorUnavailable('solver_not_enabled', vendor, null, 'the anti-bot solver is not enabled for this Actor');
+        throw new SolverAuthError(`solver refused the run token (HTTP ${status})`);
+    }
+    if (status >= 400)
+        throw new SolveAttemptError(`solver HTTP ${status}: ${data.message ?? ''}`.trim());
+    return data;
+}
+/** Solves one challenge on the Actor's session through the platform. */
+async function solve(options) {
+    const gw = gateway();
+    const vendor = options.vendor ?? 'auto';
+    if (!gw)
+        throw new VendorUnavailable('solver_not_enabled', vendor, null, 'the platform solver is not available to this run');
+    const timeoutMs = (options.timeoutMs ?? 60_000) + 30_000;
+    const identity = typeof options.identity === 'string' ? { profile: options.identity } : (options.identity ?? { profile: 'chrome-146-macos' });
+    const cookieHeader = async () => (options.cookieHeader ? await options.cookieHeader() : null);
+    let data = handle(await api('/solve', {
+        vendor,
+        url: options.url,
+        blocked: { status: options.response.status, body: (options.response.body ?? '').slice(0, MAX_BODY) },
+        identity,
+        timeoutMs: options.timeoutMs ?? 60_000,
+        session: { id: options.sessionId, cookieHeader: await cookieHeader() },
+    }, gw.key, gw.base, timeoutMs), vendor);
+    for (let step = 0; step < 8; step++) {
+        if (data.action === 'done') {
+            const clearance = {
+                solveId: data.solveId ?? null,
+                cookies: data.cookies ?? [],
+                ttlHintSecs: Number(data.ttlHintSecs) || 0,
+                cached: !!data.cached,
+                verified: null,
+            };
+            if (options.verify) {
+                const ok = !!(await options.verify(clearance.cookies));
+                clearance.verified = ok;
+                if (clearance.solveId) {
+                    await api(`/solves/${clearance.solveId}/outcome`, { verified: ok }, gw.key, gw.base, 15_000).catch(() => undefined);
+                }
+                if (!ok)
+                    throw new SolveAttemptError('still blocked after the clearance was applied');
+            }
+            return clearance;
+        }
+        if (data.action === 'failed') {
+            const message = String(data.message ?? data.reason ?? 'solve failed');
+            if (data.reason === 'ip_banned')
+                throw new IpBanned(message);
+            throw new SolveAttemptError(message);
+        }
+        if (data.action !== 'fetch' && data.action !== 'submit')
+            throw new SolveAttemptError(`unexpected solver answer: ${data.action}`);
+        const results = [];
+        for (const req of (data.requests ?? [])) {
+            if (!req || !stepAllowed(String(req.url ?? ''), options.url) || (req.method !== 'GET' && req.method !== 'POST')) {
+                throw new SolveAttemptError('the solver asked for a request outside the target site; refused');
+            }
+            let r;
+            try {
+                r = await options.fetch(req);
+            }
+            catch (err) {
+                throw new SolveAttemptError(`challenge request failed: ${err.name}`);
+            }
+            results.push({ id: req.id, status: r.status, body: (r.body ?? '').slice(0, MAX_BODY) });
+        }
+        data = handle(await api('/solve', { solveId: data.solveId, results, session: { id: options.sessionId, cookieHeader: await cookieHeader() } }, gw.key, gw.base, timeoutMs), vendor);
+    }
+    throw new SolveAttemptError('the solve did not finish');
+}
+/** Reports your own verification of a clearance (when `verify` was not passed to solve). */
+async function reportSolveOutcome(clearance, verified) {
+    const gw = gateway();
+    if (!gw || !clearance.solveId)
+        return;
+    clearance.verified = verified;
+    await api(`/solves/${clearance.solveId}/outcome`, { verified }, gw.key, gw.base, 15_000).catch(() => undefined);
+}
+/** Test hook. */
+function clearSolverStatusCache() {
+    statusCache.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "scrapely",
-    "version": "1.2.19",
+    "version": "1.2.20",
     "description": "Scrapely SDK for building JavaScript and TypeScript Actors",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -45,7 +45,8 @@
         "test:terminal-status": "npx tsx --test tests/terminal-status-message.test.ts",
         "test:cdp-retry": "npx tsx --test tests/cdp-retry.test.ts",
         "test:proxy-input-aliases": "npx tsx --test tests/proxy-input-aliases.test.ts",
-        "test:charge-retries": "npx tsx --test tests/charge-retries.test.ts"
+        "test:charge-retries": "npx tsx --test tests/charge-retries.test.ts",
+        "test:solver": "npx tsx --test tests/solver.test.ts"
     },
     "author": "SandeepDev1",
     "license": "ISC AND Apache-2.0",