@apifuse/provider-sdk 2.2.0-beta.47 → 2.2.0-beta.48

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.48
+
+- Release candidate for main commit ba6636fa8dd53a35af3091ae6efd797f5ef3d836.
+
 ## 2.2.0-beta.47
 
 - Release candidate for main commit 0ff0c6c90153af3aab75978eb73040c9adaa2609.

package/dist/runtime/resolver-public.d.ts

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, type ResolverSolutionSource, } from "./resolver.js";

package/dist/runtime/resolver-public.js

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";

package/dist/runtime/resolver-vendors/capsolver.js

@@ -7,6 +7,11 @@ const CAPSOLVER_VENDOR_ID = "capsolver";
 const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
+const SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND = {
+    // CapSolver omits expiry, so use one conservative hour despite measured
+    // AWS WAF lifetimes of days.
+    aws_waf: 60 * 60 * 1_000,
+};
 class CapsolverSolveTimeoutError extends Error {
     constructor() {
         super("Capsolver resolver solve budget elapsed");
@@ -483,6 +488,7 @@ export function createCapsolverResolverVendorAdapter(options) {
                                 form: "cookies",
                                 cookies: { "aws-waf-token": solutionValue },
                                 userAgent: identity?.userAgent ?? getStealthProfile(DEFAULT_PROFILE).userAgent,
+                                sdkEstimatedExpires: (now() + SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND.aws_waf) / 1_000,
                             }
                             : { form: "token", token: solutionValue };
                     }

package/dist/runtime/resolver-vendors/twocaptcha.js

@@ -365,6 +365,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         if (!token?.trim()) {
                             throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
                         }
+                        // AWS WAF remains a token solution here, so resolver cookie caching does not apply.
                         return { form: "token", token };
                     }
                 };

package/dist/runtime/resolver.d.ts

@@ -31,6 +31,7 @@ export interface ResolverRuntimeOptions {
         readonly identityScope?: string;
     }) => ResolverVendorTransport;
 }
+export type ResolverSolutionSource = "cache" | "vendor";
 export type ResolverInstrumentationMetadata = {
     readonly target: ResolverContext;
     readonly traceRecorder: TraceRecorder;
@@ -40,8 +41,19 @@ export declare const RESOLVER_ADAPTER_REGISTRY: Partial<Readonly<Record<Provider
 export declare function swapResolverAdapterFactoryForTests(vendor: ProviderResolverVendor, factory: ResolverAdapterFactory | undefined): () => void;
 /** Internal test seam; deliberately not re-exported from the package root. */
 export declare function swapResolverDefaultUserAgentForTests(resolver: (() => string | undefined) | undefined): () => void;
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export declare function getResolverSolutionSource(solution: ChallengeSolution): ResolverSolutionSource | undefined;
 /** Remove the cached entry for the exact solution object returned by this resolver. */
 export declare function invalidateResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<void>;
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export declare function invalidateCachedResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<boolean>;
 export declare function createResolverClient(options: {
     readonly kinds: readonly ProviderChallengeKind[];
     readonly adapters: readonly ResolverVendorAdapter[];

package/dist/runtime/resolver.js

@@ -19,6 +19,7 @@ const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
 const resolverCaches = new WeakMap();
 const solutionIssuerDigests = new WeakMap();
+const resolverSolutionSources = new WeakMap();
 const SAFE_CAUSE_MESSAGE_WORDS = new Set([
     "abort",
     "aborted",
@@ -376,7 +377,7 @@ function isResolverCacheIndex(value) {
 function solutionExpiryMs(solution) {
     if (solution.form !== "cookies")
         return undefined;
-    const expires = solution.expires;
+    const expires = solution.expires ?? solution.sdkEstimatedExpires;
     if (typeof expires !== "number" || !Number.isFinite(expires))
         return undefined;
     return expires * 1_000;
@@ -386,14 +387,33 @@ function rememberSolutionIssuer(solution, issuerDigest) {
         solutionIssuerDigests.set(solution, issuerDigest);
     }
 }
+function rememberSolutionSource(solution, source) {
+    if (typeof solution === "object" && solution !== null) {
+        resolverSolutionSources.set(solution, source);
+    }
+}
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export function getResolverSolutionSource(solution) {
+    return resolverSolutionSources.get(solution);
+}
 async function readCachedSolution(cache, challenge, issuerDigest, now) {
     const cached = await cache.get(resolverSolutionCacheKey(cache, challenge, issuerDigest));
     if (!cached || !isCachedResolverSolution(cached.value))
         return undefined;
     if (cached.value.issuerDigest !== issuerDigest || cached.value.expiresAtMs <= now)
         return undefined;
-    rememberSolutionIssuer(cached.value.solution, issuerDigest);
-    return cached.value.solution;
+    if (cached.value.solution.form !== "cookies")
+        return undefined;
+    const solution = {
+        ...cached.value.solution,
+        cookies: { ...cached.value.solution.cookies },
+    };
+    rememberSolutionIssuer(solution, issuerDigest);
+    rememberSolutionSource(solution, "cache");
+    return solution;
 }
 async function findCachedSolution(cache, challenge, identity, identityScope) {
     const now = Date.now();
@@ -457,8 +477,7 @@ async function cacheResolverSolution(cache, challenge, solution, identity, ident
         { direct: true, expiresAtMs, issuerDigest },
     ], now);
 }
-/** Remove the cached entry for the exact solution object returned by this resolver. */
-export async function invalidateResolverSolution(resolver, challenge, solution) {
+async function invalidateResolverSolutionWithOutcome(resolver, challenge, solution) {
     const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
     const cacheOwner = metadata?.target ?? resolver;
     const invalidate = async () => {
@@ -484,14 +503,28 @@ export async function invalidateResolverSolution(resolver, challenge, solution)
         return "index_entry_deleted";
     };
     if (!metadata) {
-        await invalidate();
-        return;
+        return await invalidate();
     }
-    await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+    return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
         attributes: { challenge_kind: challenge.kind },
         onSuccess: (outcome) => ({ outcome }),
     });
 }
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(resolver, challenge, solution) {
+    await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+}
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export async function invalidateCachedResolverSolution(resolver, challenge, solution) {
+    if (getResolverSolutionSource(solution) !== "cache")
+        return false;
+    const outcome = await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+    return outcome === "entry_deleted" || outcome === "index_entry_deleted";
+}
 async function resolveResolverIdentity(proxyIntent) {
     const userAgentSource = proxyIntent.userAgent ? "declared" : "defaulted";
     let proxyUrl;
@@ -618,6 +651,7 @@ function createResolverChainClient(options) {
                             await cacheResolverSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
                         }
                     }
+                    rememberSolutionSource(solution, "vendor");
                     return solution;
                 }
                 catch (error) {

package/dist/types.d.ts

@@ -338,6 +338,11 @@ export type ChallengeSolution = {
     readonly userAgent: string;
     /** Epoch seconds copied from the upstream cookie's own expiry attribute; never a constant. */
     readonly expires?: number;
+    /**
+     * Epoch seconds conservatively estimated by the SDK when a resolver vendor omits
+     * the upstream cookie's expiry. `expires` takes precedence when both are present.
+     */
+    readonly sdkEstimatedExpires?: number;
 };
 export interface ProviderResolverConfig {
     /** Optional ordered override for the SDK-owned vendor fallback chain. */

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.47",
+	"version": "2.2.0-beta.48",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/runtime/resolver-public.ts

@@ -10,6 +10,8 @@ export {
 	createUnsupportedResolverClient,
 	DEFAULT_RESOLVER_VENDOR_PREFERENCE,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
+	getResolverSolutionSource,
+	invalidateCachedResolverSolution,
 	invalidateResolverSolution,
 	RESOLVER_ADAPTER_REGISTRY,
 	RESOLVER_INSTRUMENTATION_METADATA,
@@ -17,4 +19,5 @@ export {
 	type ResolverAdapterFactory,
 	type ResolverInstrumentationMetadata,
 	type ResolverRuntimeOptions,
+	type ResolverSolutionSource,
 } from "./resolver.js";

package/src/runtime/resolver-vendors/capsolver.ts

@@ -1,5 +1,5 @@
 import { getStealthProfile } from "../../stealth/profiles.js";
-import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind } from "../../types.js";
 import { redactSensitiveText } from "../request-options.js";
 import { DEFAULT_PROFILE } from "../stealth.js";
 import type { TraceRecorder } from "../trace.js";
@@ -17,6 +17,11 @@ const CAPSOLVER_VENDOR_ID = "capsolver" as const;
 const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
+const SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND = {
+	// CapSolver omits expiry, so use one conservative hour despite measured
+	// AWS WAF lifetimes of days.
+	aws_waf: 60 * 60 * 1_000,
+} satisfies Partial<Record<ProviderChallengeKind, number>>;
 
 type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
 type CapsolverOperationPhase = "create_task" | "poll_result";
@@ -657,6 +662,8 @@ export function createCapsolverResolverVendorAdapter(
 									form: "cookies" as const,
 									cookies: { "aws-waf-token": solutionValue },
 									userAgent: identity?.userAgent ?? getStealthProfile(DEFAULT_PROFILE).userAgent,
+									sdkEstimatedExpires:
+										(now() + SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND.aws_waf) / 1_000,
 								}
 							: { form: "token" as const, token: solutionValue };
 					}

package/src/runtime/resolver-vendors/twocaptcha.ts

@@ -497,6 +497,7 @@ export function createTwoCaptchaResolverVendorAdapter(
 								{ phase },
 							);
 						}
+						// AWS WAF remains a token solution here, so resolver cookie caching does not apply.
 						return { form: "token" as const, token };
 					}
 				};

package/src/runtime/resolver.ts

@@ -143,11 +143,21 @@ type ResolverCacheIndex = {
 	}[];
 };
 
+export type ResolverSolutionSource = "cache" | "vendor";
+
+type ResolverSolutionInvalidationOutcome =
+	| "cache_disabled"
+	| "entry_deleted"
+	| "index_entry_deleted"
+	| "not_cookie_solution"
+	| "solution_not_cached";
+
 const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
 const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
 const resolverCaches = new WeakMap<object, ProviderCache | null>();
 const solutionIssuerDigests = new WeakMap<object, string>();
+const resolverSolutionSources = new WeakMap<object, ResolverSolutionSource>();
 const SAFE_CAUSE_MESSAGE_WORDS: ReadonlySet<string> = new Set([
 	"abort",
 	"aborted",
@@ -597,7 +607,7 @@ function isResolverCacheIndex(value: unknown): value is ResolverCacheIndex {
 
 function solutionExpiryMs(solution: ChallengeSolution): number | undefined {
 	if (solution.form !== "cookies") return undefined;
-	const expires = solution.expires;
+	const expires = solution.expires ?? solution.sdkEstimatedExpires;
 	if (typeof expires !== "number" || !Number.isFinite(expires)) return undefined;
 	return expires * 1_000;
 }
@@ -608,6 +618,22 @@ function rememberSolutionIssuer(solution: ChallengeSolution, issuerDigest: strin
 	}
 }
 
+function rememberSolutionSource(solution: ChallengeSolution, source: ResolverSolutionSource): void {
+	if (typeof solution === "object" && solution !== null) {
+		resolverSolutionSources.set(solution, source);
+	}
+}
+
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export function getResolverSolutionSource(
+	solution: ChallengeSolution,
+): ResolverSolutionSource | undefined {
+	return resolverSolutionSources.get(solution);
+}
+
 async function readCachedSolution(
 	cache: ProviderCache,
 	challenge: ProviderChallenge,
@@ -618,8 +644,14 @@ async function readCachedSolution(
 	if (!cached || !isCachedResolverSolution(cached.value)) return undefined;
 	if (cached.value.issuerDigest !== issuerDigest || cached.value.expiresAtMs <= now)
 		return undefined;
-	rememberSolutionIssuer(cached.value.solution, issuerDigest);
-	return cached.value.solution;
+	if (cached.value.solution.form !== "cookies") return undefined;
+	const solution = {
+		...cached.value.solution,
+		cookies: { ...cached.value.solution.cookies },
+	};
+	rememberSolutionIssuer(solution, issuerDigest);
+	rememberSolutionSource(solution, "cache");
+	return solution;
 }
 
 async function findCachedSolution(
@@ -720,25 +752,18 @@ async function cacheResolverSolution(
 	);
 }
 
-/** Remove the cached entry for the exact solution object returned by this resolver. */
-export async function invalidateResolverSolution(
+async function invalidateResolverSolutionWithOutcome(
 	resolver: ResolverContext,
 	challenge: ProviderChallenge,
 	solution: ChallengeSolution,
-): Promise<void> {
+): Promise<ResolverSolutionInvalidationOutcome> {
 	const metadata = (
 		resolver as ResolverContext & {
 			readonly [RESOLVER_INSTRUMENTATION_METADATA]?: ResolverInstrumentationMetadata;
 		}
 	)[RESOLVER_INSTRUMENTATION_METADATA];
 	const cacheOwner = metadata?.target ?? resolver;
-	const invalidate = async (): Promise<
-		| "cache_disabled"
-		| "entry_deleted"
-		| "index_entry_deleted"
-		| "not_cookie_solution"
-		| "solution_not_cached"
-	> => {
+	const invalidate = async (): Promise<ResolverSolutionInvalidationOutcome> => {
 		if (solution.form !== "cookies") return "not_cookie_solution";
 		if (!resolverCaches.has(cacheOwner)) {
 			throw new Error("Resolver cache registration lookup failed during solution invalidation");
@@ -764,15 +789,38 @@ export async function invalidateResolverSolution(
 	};
 
 	if (!metadata) {
-		await invalidate();
-		return;
+		return await invalidate();
 	}
-	await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+	return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
 		attributes: { challenge_kind: challenge.kind },
 		onSuccess: (outcome) => ({ outcome }),
 	});
 }
 
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(
+	resolver: ResolverContext,
+	challenge: ProviderChallenge,
+	solution: ChallengeSolution,
+): Promise<void> {
+	await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+}
+
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export async function invalidateCachedResolverSolution(
+	resolver: ResolverContext,
+	challenge: ProviderChallenge,
+	solution: ChallengeSolution,
+): Promise<boolean> {
+	if (getResolverSolutionSource(solution) !== "cache") return false;
+	const outcome = await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+	return outcome === "entry_deleted" || outcome === "index_entry_deleted";
+}
+
 async function resolveResolverIdentity(
 	proxyIntent: NonNullable<ResolverRuntimeOptions["proxyIntent"]>,
 ): Promise<{
@@ -938,6 +986,7 @@ function createResolverChainClient(options: {
 							);
 						}
 					}
+					rememberSolutionSource(solution, "vendor");
 					return solution;
 				} catch (error) {
 					signal.throwIfAborted();

package/src/types.ts

@@ -409,6 +409,11 @@ export type ChallengeSolution =
 			readonly userAgent: string;
 			/** Epoch seconds copied from the upstream cookie's own expiry attribute; never a constant. */
 			readonly expires?: number;
+			/**
+			 * Epoch seconds conservatively estimated by the SDK when a resolver vendor omits
+			 * the upstream cookie's expiry. `expires` takes precedence when both are present.
+			 */
+			readonly sdkEstimatedExpires?: number;
 		};
 
 export interface ProviderResolverConfig {