@apifuse/provider-sdk 2.2.0-beta.44 → 2.2.0-beta.46

package/dist/runtime/stealth.js

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto";
 import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, policyResolvesRegistryVendorChain, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
-import { getStealthProfile } from "../stealth/profiles.js";
+import { getStealthProfile, getStealthProfileIntentAlias } from "../stealth/profiles.js";
 import { StealthCookieJar } from "./stealth-cookies.js";
 import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
 import { evaluateRedirectHop, isRedirectStatus, nextRedirectMethod, resolveRedirectUrl, } from "./redirects.js";
 import { isSensitiveKey, normalizeSensitiveParams, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, serializeRequestUrl, } from "./request-options.js";
-export const DEFAULT_PROFILE = "chrome-146";
+export const DEFAULT_PROFILE = "chrome-desktop";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
@@ -108,7 +108,11 @@ function resolveDefaultWreqProfileMapping() {
     }
     return { identifier, os: profile.platform };
 }
-const DEFAULT_WREQ_PROFILE_MAPPING = resolveDefaultWreqProfileMapping();
+let defaultWreqProfileMapping;
+function getDefaultWreqProfileMapping() {
+    defaultWreqProfileMapping ??= resolveDefaultWreqProfileMapping();
+    return defaultWreqProfileMapping;
+}
 export function resolveWreqProfile(profileName, wreqProfiles) {
     if (REMOVED_CHROME_PROFILE_NAMES.has(profileName)) {
         throw new SDKError(`Unknown stealth profile: ${profileName}`);
@@ -125,8 +129,9 @@ export function resolveWreqProfile(profileName, wreqProfiles) {
         // profile strings still run with the transport default instead of failing
         // before the request starts. Removed built-in profile aliases above remain
         // explicit errors so callers do not accidentally pin retired fingerprints.
-        identifier = DEFAULT_WREQ_PROFILE_MAPPING.identifier;
-        os = DEFAULT_WREQ_PROFILE_MAPPING.os;
+        const defaultMapping = getDefaultWreqProfileMapping();
+        identifier = defaultMapping.identifier;
+        os = defaultMapping.os;
     }
     const browser = closestWreqProfile(identifier, wreqProfiles);
     if (!browser) {
@@ -201,11 +206,14 @@ function splitCombinedSetCookieHeader(headerValue) {
     return cookieStrings;
 }
 export async function normalizeResponse(response, requestUrl, maxBodyBytes) {
+    return normalizeResponseWithSignal(response, requestUrl, maxBodyBytes);
+}
+async function normalizeResponseWithSignal(response, requestUrl, maxBodyBytes, signal) {
     const headers = Object.fromEntries(response.headers.entries());
     const cookies = new StealthCookieJar(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
     const bodyBytes = maxBodyBytes === undefined
-        ? await response.arrayBuffer()
-        : await readResponseBodyWithLimit(response, maxBodyBytes);
+        ? await readResponseArrayBuffer(response, signal)
+        : await readResponseBodyWithLimit(response, maxBodyBytes, signal);
     const body = new TextDecoder().decode(bodyBytes);
     return {
         status: response.status,
@@ -231,6 +239,40 @@ export async function normalizeResponse(response, requestUrl, maxBodyBytes) {
         },
     };
 }
+async function readResponseArrayBuffer(response, signal) {
+    if (!signal)
+        return response.arrayBuffer();
+    throwIfAmbientAborted(signal);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (operation) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            operation();
+        };
+        const onAbort = () => {
+            const error = toAmbientCancellationError(signal);
+            try {
+                void response.body?.cancel().catch(() => undefined);
+            }
+            catch {
+                // Preserve the cancellation error if accessing or cancelling the body fails.
+            }
+            settle(() => reject(error));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            void response.arrayBuffer().then((body) => settle(() => resolve(body)), (error) => settle(() => reject(error)));
+        }
+        catch (error) {
+            settle(() => reject(error));
+        }
+        if (signal.aborted)
+            onAbort();
+    });
+}
 function responseTooLargeError(maxBodyBytes, observedBytes) {
     return new TransportError(`Response body exceeded maxBodyBytes limit of ${maxBodyBytes} bytes (observed ${observedBytes} bytes)`, {
         code: "response_too_large",
@@ -246,7 +288,8 @@ function declaredContentLength(headers) {
     const parsed = Number(contentLength);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
-async function readResponseBodyWithLimit(response, maxBodyBytes) {
+async function readResponseBodyWithLimit(response, maxBodyBytes, signal) {
+    throwIfAmbientAborted(signal);
     const contentLength = declaredContentLength(response.headers);
     if (contentLength !== undefined && contentLength > maxBodyBytes) {
         await response.body?.cancel().catch(() => undefined);
@@ -264,7 +307,7 @@ async function readResponseBodyWithLimit(response, maxBodyBytes) {
     let receivedBytes = 0;
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            const { done, value } = await readResponseBodyChunk(reader, signal);
             if (done)
                 break;
             if (!value)
@@ -280,6 +323,9 @@ async function readResponseBodyWithLimit(response, maxBodyBytes) {
     finally {
         reader.releaseLock();
     }
+    return concatenateResponseBodyChunks(chunks, receivedBytes);
+}
+function concatenateResponseBodyChunks(chunks, receivedBytes) {
     const bodyBytes = new Uint8Array(receivedBytes);
     let offset = 0;
     for (const chunk of chunks) {
@@ -288,6 +334,30 @@ async function readResponseBodyWithLimit(response, maxBodyBytes) {
     }
     return bodyBytes.buffer;
 }
+function readResponseBodyChunk(reader, signal) {
+    if (!signal)
+        return reader.read();
+    throwIfAmbientAborted(signal);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (operation) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            operation();
+        };
+        const onAbort = () => {
+            const error = toAmbientCancellationError(signal);
+            void reader.cancel().catch(() => undefined);
+            settle(() => reject(error));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        void reader.read().then((chunk) => settle(() => resolve(chunk)), (error) => settle(() => reject(error)));
+        if (signal.aborted)
+            onAbort();
+    });
+}
 function normalizeBody(body) {
     if (body === undefined) {
         return "";
@@ -420,8 +490,38 @@ function normalizeStealthTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function toAmbientCancellationError(signal, error = signal.reason) {
+    if (error instanceof TransportError && error.code === "transport_cancelled") {
+        return error;
+    }
+    return new TransportError("Request cancelled", {
+        code: "transport_cancelled",
+        status: 0,
+        retryable: false,
+        ...(error !== undefined
+            ? { cause: error instanceof Error ? error : new Error(String(error)) }
+            : {}),
+    });
+}
+function throwIfAmbientAborted(signal) {
+    if (signal?.aborted)
+        throw toAmbientCancellationError(signal);
+}
+function sleep(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    throwIfAmbientAborted(signal);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(toAmbientCancellationError(signal));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
 }
 function normalizeMethod(method) {
     switch (method.toUpperCase()) {
@@ -475,7 +575,7 @@ function discardStealthRedirectBody(response) {
         // failure must not replace or delay that decision.
     }
 }
-async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options) {
+async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options, signal) {
     let currentUrl = requestUrl;
     let currentMethod = method;
     let currentBody = options.body === undefined ? undefined : normalizeBody(options.body);
@@ -484,6 +584,7 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
     let response;
     const deadline = options.timeout ? performance.now() + options.timeout : undefined;
     while (true) {
+        throwIfAmbientAborted(signal);
         const headers = { ...currentHeaders };
         if (!hasHeader(headers, "Cookie")) {
             const cookieHeader = cookieJar.toHeader(currentUrl);
@@ -494,10 +595,12 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
             headers: normalizeHeaders(headers),
             method: currentMethod,
             redirect: "manual",
+            ...(signal ? { signal } : {}),
         };
         if (currentBody !== undefined)
             requestInit.body = currentBody;
         await transport.clearCookies();
+        throwIfAmbientAborted(signal);
         const remainingTimeout = deadline === undefined ? undefined : Math.ceil(deadline - performance.now());
         if (remainingTimeout !== undefined && remainingTimeout <= 0) {
             throw new TransportError("Request timed out", {
@@ -508,6 +611,10 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
         if (remainingTimeout !== undefined)
             requestInit.timeout = remainingTimeout;
         response = await transport.fetch(currentUrl, requestInit);
+        if (signal?.aborted) {
+            discardStealthRedirectBody(response);
+            throw toAmbientCancellationError(signal);
+        }
         cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers), response.url ?? currentUrl);
         if (!isRedirectStatus(response.status) || options.redirect === "manual")
             break;
@@ -536,7 +643,7 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
         currentUrl = nextUrl;
         followedHops += 1;
     }
-    const normalized = await normalizeResponse(response, currentUrl, options.maxBodyBytes);
+    const normalized = await normalizeResponseWithSignal(response, currentUrl, options.maxBodyBytes, signal);
     if (followedHops > 0)
         normalized.redirected = true;
     return { normalized, response };
@@ -546,6 +653,10 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     let closed = false;
     let hasWarnedMissingProxy = false;
     const warn = clientOptions.warn ?? console.warn;
+    const intentAlias = getStealthProfileIntentAlias(defaultProfile);
+    if (intentAlias) {
+        warn(`[provider-sdk] Stealth profile "${defaultProfile}" pins a browser version and is deprecated. Use the intent profile "${intentAlias}" so TLS, headers, and User-Agent stay aligned with SDK updates; derive an explicit User-Agent with getStealthProfile("${intentAlias}").userAgent instead of hardcoding one.`);
+    }
     const cookieJar = new StealthCookieJar([], baseUrl);
     async function getClientEntry(profileName, proxyUrl, ignoreTlsErrors) {
         if (closed) {
@@ -570,21 +681,57 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         }
         return entry;
     }
-    async function withClient(profileName, proxyUrl, ignoreTlsErrors, operation) {
+    async function withClient(profileName, proxyUrl, ignoreTlsErrors, operation, signal) {
+        throwIfAmbientAborted(signal);
         const entry = await getClientEntry(profileName, proxyUrl, ignoreTlsErrors);
+        throwIfAmbientAborted(signal);
         const previous = entry.tail;
         let release;
         entry.tail = new Promise((resolve) => {
             release = resolve;
         });
-        await previous;
+        let acquired = false;
         try {
-            return await operation(await entry.session);
+            await waitForClientTurn(previous, signal);
+            acquired = true;
+            throwIfAmbientAborted(signal);
+            const client = await entry.session;
+            throwIfAmbientAborted(signal);
+            const result = await operation(client);
+            throwIfAmbientAborted(signal);
+            return result;
         }
         finally {
-            release();
+            if (acquired) {
+                release();
+            }
+            else {
+                void previous.then(release, release);
+            }
         }
     }
+    async function waitForClientTurn(previous, signal) {
+        if (!signal) {
+            await previous;
+            return;
+        }
+        throwIfAmbientAborted(signal);
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (operation) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener("abort", onAbort);
+                operation();
+            };
+            const onAbort = () => settle(() => reject(toAmbientCancellationError(signal)));
+            signal.addEventListener("abort", onAbort, { once: true });
+            void previous.then(() => settle(resolve), (error) => settle(() => reject(error)));
+            if (signal.aborted)
+                onAbort();
+        });
+    }
     async function resolveRequestProxy(options, proxyAttempt, refreshEpoch) {
         const resolvedProxy = await resolveProxyConfigAsync({
             proxy: options?.proxy ?? clientOptions.proxy,
@@ -637,6 +784,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     throw redactSensitiveRequestError(error, url, options.sensitiveParams);
                 }
             })();
+            throwIfAmbientAborted(clientOptions.signal);
             const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
             const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
             const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
@@ -666,6 +814,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 let stalePoolDiagnosticProxy;
                 const attemptedProxies = new Set();
                 for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+                    throwIfAmbientAborted(clientOptions.signal);
                     let proxy;
                     let attemptProxy;
                     // Reuse the exact serialization used by this outbound attempt in its catch path.
@@ -693,6 +842,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         });
                     };
                     try {
+                        throwIfAmbientAborted(clientOptions.signal);
                         const sensitiveParams = normalizeSensitiveParams(options.sensitiveParams);
                         const structural = redactUrlQueryParams(url, Object.keys(sensitiveParams ?? {}));
                         fallbackSensitiveValues = [
@@ -705,6 +855,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         fallbackRedactedUrl = structural.redactedUrl;
                         assertNoUnsupportedFingerprintOverrides(options);
                         attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
+                        throwIfAmbientAborted(clientOptions.signal);
                         proxy = attemptProxy.url;
                         if (proxy && dedupeAllocatorEndpoints) {
                             // An under-filled allocation repeats endpoints (via the modulo
@@ -722,7 +873,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const profileName = options.profile ?? defaultProfile;
                         serializedUrl = serializeRequestUrl(resolveUrl(baseUrl, url), options.params, sensitiveParams);
                         const { requestUrl } = serializedUrl;
-                        const { normalized, response } = await withClient(profileName, proxy, ignoreTlsErrors, (transport) => fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options));
+                        const { normalized, response } = await withClient(profileName, proxy, ignoreTlsErrors, (transport) => fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options, clientOptions.signal), clientOptions.signal);
                         if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
                         }
@@ -757,10 +908,16 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
                         let normalizedError;
                         try {
+                            throwIfAmbientAborted(clientOptions.signal);
                             normalizedError = normalizeStealthTransportError(error);
                         }
                         catch (normalizationError) {
-                            throw redactSensitiveError(normalizationError, sensitiveValues, serializedUrl?.requestUrl ?? fallbackRequestUrl, serializedUrl?.redactedUrl ?? fallbackRedactedUrl);
+                            const redactedNormalizationError = redactSensitiveError(normalizationError, sensitiveValues, serializedUrl?.requestUrl ?? fallbackRequestUrl, serializedUrl?.redactedUrl ?? fallbackRedactedUrl);
+                            if (normalizationError instanceof TransportError &&
+                                normalizationError.code === "transport_cancelled") {
+                                recordProxyAttempt("error", proxyAttemptErrorCode(normalizationError), proxyAttemptStatus(normalizationError));
+                            }
+                            throw redactedNormalizationError;
                         }
                         const retryErrorCode = proxyAttemptErrorCode(normalizedError);
                         const refreshableProxyError = isProxyPoolRefreshableError(normalizedError);
@@ -807,8 +964,9 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                                 proxyUsed: Boolean(proxy),
                             })) {
                             if (stealthRetryOptions) {
-                                await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1));
+                                await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1), clientOptions.signal);
                             }
+                            throwIfAmbientAborted(clientOptions.signal);
                             continue;
                         }
                         throw normalizedError;
@@ -817,11 +975,13 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 if (rotatesRegistryChain &&
                     stalePoolError &&
                     refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES) {
+                    throwIfAmbientAborted(clientOptions.signal);
                     await invalidateProxyResolutionCacheAsync({
                         proxyPolicy: clientOptions.proxyPolicy,
                         upstream: clientOptions.upstream,
                         affinityKey: clientOptions.affinityKey,
                     });
+                    throwIfAmbientAborted(clientOptions.signal);
                     continue;
                 }
                 const proxyAuthDiagnostic = stalePoolError && stalePoolDiagnosticProxy
@@ -842,6 +1002,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 }
                 break;
             }
+            throwIfAmbientAborted(clientOptions.signal);
             throw normalizeStealthTransportError(lastError);
         },
         cookies: cookieJar,
@@ -1034,16 +1195,20 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     async function classifyProxyAuthDiagnostic(profileName, proxy) {
         try {
             return await withClient(profileName, proxy, false, async (client) => {
+                throwIfAmbientAborted(clientOptions.signal);
                 await client.clearCookies();
+                throwIfAmbientAborted(clientOptions.signal);
                 const response = await client.fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
                     method: "GET",
                     timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+                    ...(clientOptions.signal ? { signal: clientOptions.signal } : {}),
                 });
-                const normalized = await normalizeResponse(response);
+                const normalized = await normalizeResponseWithSignal(response, undefined, undefined, clientOptions.signal);
                 return classifyProxyAuthDiagnosticMessage(normalized.body);
-            });
+            }, clientOptions.signal);
         }
         catch (error) {
+            throwIfAmbientAborted(clientOptions.signal);
             const message = error instanceof Error
                 ? [error.message, error.cause instanceof Error ? error.cause.message : ""]
                     .filter(Boolean)

package/dist/server/serve-implementation.js

@@ -409,6 +409,7 @@ function createProviderContext(provider, request, operationId, options, state =
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: proxyTelemetry,
+        ...(signal ? { signal } : {}),
     };
     const { capabilityModules } = options;
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "operation", operationId, request.requestId, "stealth", error);
@@ -446,10 +447,10 @@ function createProviderContext(provider, request, operationId, options, state =
         stealth: stealthBaseUrl
             ? capabilityModules.stealth
                 ? stealthProfile
-                    ? capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
+                    ? capabilityModules.stealth.createStealthClient(stealthBaseUrl, provider.stealth.profile, stealthClientOptions)
                     : capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
                 : stealthProfile
-                    ? createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthProfile.name, stealthClientOptions)
+                    ? createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, provider.stealth.profile, stealthClientOptions)
                     : createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
             : createStealthStub(),
         browser: provider.runtime === "browser"
@@ -566,6 +567,7 @@ function createAuthFlowContext(provider, request, options, state, proxyTelemetry
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
         telemetry: proxyTelemetry,
+        ...(signal ? { signal } : {}),
     };
     const { capabilityModules } = options;
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "auth", "flow", request.requestId, "stealth", error);
@@ -593,10 +595,10 @@ function createAuthFlowContext(provider, request, options, state, proxyTelemetry
             stealth: stealthBaseUrl
                 ? capabilityModules.stealth
                     ? stealthProfile
-                        ? capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
+                        ? capabilityModules.stealth.createStealthClient(stealthBaseUrl, provider.stealth.profile, stealthClientOptions)
                         : capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
                     : stealthProfile
-                        ? createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthProfile.name, stealthClientOptions)
+                        ? createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, provider.stealth.profile, stealthClientOptions)
                         : createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
                 : createStealthStub(),
             ...(provider.native

package/dist/stealth/profiles.d.ts

@@ -1,4 +1,8 @@
 import type { StealthProfile } from "../types.js";
 export declare function generateLayer2Headers(profile: StealthProfile): Record<string, string>;
 export declare function getStealthProfile(name: string): StealthProfile;
+/** Returns the intent alias that replaces a registered version-pinned profile. */
+export declare function getStealthProfileIntentAlias(name: string): string | undefined;
+/** Internal compatibility catalog used by transport-parity tests. */
+export declare function listRegisteredStealthProfiles(): string[];
 export declare function listStealthProfiles(): string[];

package/dist/stealth/profiles.js

@@ -1,4 +1,11 @@
+import { createRequire } from "node:module";
 import { SDKError } from "../errors.js";
+const requireModule = createRequire(import.meta.url);
+let wreqProfileApi;
+function getWreqProfileApi() {
+    wreqProfileApi ??= requireModule("wreq-js");
+    return wreqProfileApi;
+}
 const CHROMIUM_HEADER_ORDER = [
     ":method",
     ":authority",
@@ -65,6 +72,50 @@ const SAFARI_H2_SETTINGS = {
 const CHROMIUM_JA3 = "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-65037,29-23-24,0";
 const FIREFOX_JA3 = "771,4865-4867-4866-49195-49199-52393-52392-49196-49200-49162-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-28-27-43-45-51,29-23-24-25,0";
 const SAFARI_JA3 = "771,4865-4866-4867-49196-49195-52393-49200-49199-49188-49192-159-158-107-103-57-51-157-156-61-60-53-47-255,0-23-65281-10-11-16-5-13-18-51-45-43-27,29-23-24-25,0";
+/**
+ * The newest Chromium build wreq-js can emulate, resolved on first profile use.
+ *
+ * A literal version here rots: it went stale twice (146 was six releases behind
+ * stable when an upstream integrity analyzer flagged it), and a fingerprint that
+ * advertises an old Chrome is exactly what bot managers score against. wreq-js
+ * already ships the profile table, so the newest entry is derived from it rather
+ * than restated. `resolveProfile("chrome")` is deliberately NOT used because its
+ * conservative default can lag newer entries in that table.
+ *
+ * package.json pins wreq-js exactly on purpose. Even a semver-minor wreq-js update
+ * can change the profile table, emitted headers, native bindings, and therefore
+ * the wire fingerprint inherited by every provider. Upgrade that exact version
+ * only in a dedicated change with profile-parity and packed-native verification.
+ */
+function resolveLatestChromiumProfile() {
+    const { getProfiles } = getWreqProfileApi();
+    let newest;
+    for (const name of getProfiles()) {
+        const match = /^chrome_(\d+)$/.exec(name);
+        if (!match)
+            continue;
+        const version = Number(match[1]);
+        if (!newest || version > newest.version)
+            newest = { name, version };
+    }
+    if (!newest) {
+        throw new SDKError("wreq-js exposes no chrome_<version> emulation profile.", {
+            code: "STEALTH_PROFILE_UNAVAILABLE",
+        });
+    }
+    return { wreqName: newest.name, version: `${newest.version}.0.0.0` };
+}
+/** The user agent wreq-js itself emits for that profile, so the two never disagree. */
+function chromiumUserAgent(latest) {
+    const { getEmulationHeaders } = getWreqProfileApi();
+    for (const [name, value] of getEmulationHeaders(latest.wreqName, "macos")) {
+        if (String(name).toLowerCase() === "user-agent")
+            return String(value);
+    }
+    throw new SDKError(`wreq-js profile ${latest.wreqName} exposes no user-agent header.`, {
+        code: "STEALTH_PROFILE_UNAVAILABLE",
+    });
+}
 function createProfile(name, definition) {
     return {
         name,
@@ -120,10 +171,21 @@ export function generateLayer2Headers(profile) {
     }
     return headers;
 }
-const STEALTH_PROFILE_ALIASES = {
-    "chrome-desktop": "chrome-146",
+const STATIC_STEALTH_PROFILE_ALIASES = {
+    "firefox-desktop": "firefox-147",
+    "safari-desktop": "safari-17",
+    "safari-mobile": "ios-safari-26",
 };
-const STEALTH_PROFILES = {
+const PUBLIC_STEALTH_PROFILE_NAMES = [
+    "chrome-desktop",
+    "firefox-desktop",
+    "safari-desktop",
+    "safari-mobile",
+    "generic-desktop",
+    "generic-mobile",
+];
+const PUBLIC_STEALTH_PROFILE_NAME_SET = new Set(PUBLIC_STEALTH_PROFILE_NAMES);
+const STATIC_STEALTH_PROFILES = {
     "chrome-146": createProfile("chrome-146", {
         platform: "macos",
         version: "146.0.0.0",
@@ -223,15 +285,6 @@ const STEALTH_PROFILES = {
         h2Settings: SAFARI_H2_SETTINGS,
         headerOrder: SAFARI_HEADER_ORDER,
     }),
-    "generic-desktop": createProfile("generic-desktop", {
-        platform: "macos",
-        version: "146.0.0.0",
-        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
-        tlsClientIdentifier: "chrome_146",
-        ja3: CHROMIUM_JA3,
-        h2Settings: CHROMIUM_H2_SETTINGS,
-        headerOrder: CHROMIUM_HEADER_ORDER,
-    }),
     "generic-mobile": createProfile("generic-mobile", {
         platform: "ios",
         version: "26.0",
@@ -242,9 +295,38 @@ const STEALTH_PROFILES = {
         headerOrder: SAFARI_HEADER_ORDER,
     }),
 };
+let stealthProfileCatalog;
+function getStealthProfileCatalog() {
+    if (stealthProfileCatalog)
+        return stealthProfileCatalog;
+    const latest = resolveLatestChromiumProfile();
+    const currentName = `chrome-${latest.version.split(".")[0]}`;
+    const currentProfile = createProfile(currentName, {
+        platform: "macos",
+        version: latest.version,
+        userAgent: chromiumUserAgent(latest),
+        tlsClientIdentifier: latest.wreqName,
+        ja3: CHROMIUM_JA3,
+        h2Settings: CHROMIUM_H2_SETTINGS,
+        headerOrder: CHROMIUM_HEADER_ORDER,
+    });
+    stealthProfileCatalog = {
+        aliases: {
+            "chrome-desktop": currentName,
+            ...STATIC_STEALTH_PROFILE_ALIASES,
+        },
+        profiles: {
+            [currentName]: currentProfile,
+            ...STATIC_STEALTH_PROFILES,
+            "generic-desktop": createProfile("generic-desktop", currentProfile),
+        },
+    };
+    return stealthProfileCatalog;
+}
 export function getStealthProfile(name) {
-    const canonicalName = STEALTH_PROFILE_ALIASES[name] ?? name;
-    const profile = STEALTH_PROFILES[canonicalName];
+    const catalog = getStealthProfileCatalog();
+    const canonicalName = catalog.aliases[name] ?? name;
+    const profile = catalog.profiles[canonicalName];
     if (!profile) {
         throw new SDKError(`Unknown stealth profile: ${name}`);
     }
@@ -254,6 +336,27 @@ export function getStealthProfile(name) {
         headerOrder: profile.headerOrder ? [...profile.headerOrder] : undefined,
     };
 }
+/** Returns the intent alias that replaces a registered version-pinned profile. */
+export function getStealthProfileIntentAlias(name) {
+    if (PUBLIC_STEALTH_PROFILE_NAME_SET.has(name))
+        return undefined;
+    if (/^(?:chrome|chromium|edge)[-_]\d/i.test(name)) {
+        return "chrome-desktop";
+    }
+    if (/^firefox[-_]\d/i.test(name))
+        return "firefox-desktop";
+    if (/^(?:ios[-_]safari|safari[-_](?:ios|ipad))[-_]\d/i.test(name)) {
+        return "safari-mobile";
+    }
+    if (/^safari[-_]\d/i.test(name))
+        return "safari-desktop";
+    return undefined;
+}
+/** Internal compatibility catalog used by transport-parity tests. */
+export function listRegisteredStealthProfiles() {
+    const catalog = getStealthProfileCatalog();
+    return [...Object.keys(catalog.profiles), ...Object.keys(catalog.aliases)];
+}
 export function listStealthProfiles() {
-    return [...Object.keys(STEALTH_PROFILES), ...Object.keys(STEALTH_PROFILE_ALIASES)];
+    return [...PUBLIC_STEALTH_PROFILE_NAMES];
 }

package/dist/types.d.ts

@@ -956,6 +956,10 @@ export interface ProviderMeta {
     publicProfile?: ProviderPublicProfile;
     contract?: {
         publicSchemaFieldNames?: "normalized";
+        readonly pinnedWireFieldPaths?: readonly {
+            readonly path: string;
+            readonly reason: string;
+        }[];
     };
 }
 export type RequestParamPrimitive = string | number | boolean | null | undefined;