@apifuse/provider-sdk 2.1.0-beta.5 → 2.1.0-beta.8

package/dist/types.js

@@ -0,0 +1,61 @@
+export const OPERATION_TIMEOUT_MS_MIN = 1;
+export const OPERATION_TIMEOUT_MS_MAX = 60_000;
+export const STREAM_HEARTBEAT_MS_MIN = 1_000;
+export const STREAM_HEARTBEAT_MS_MAX = 60_000;
+export const STREAM_IDLE_TIMEOUT_MS_MIN = 1_000;
+export const STREAM_IDLE_TIMEOUT_MS_MAX = 300_000;
+export const STREAM_MAX_DURATION_MS_MIN = 1_000;
+export const STREAM_MAX_DURATION_MS_MAX = 1_800_000;
+export const STREAM_CHUNK_BYTES_MIN = 1;
+export const STREAM_CHUNK_BYTES_MAX = 1_048_576;
+export const DEFAULT_OPERATION_TRANSPORT = {
+    kind: "json",
+};
+/**
+ * Common probe interval examples retained for discoverability/backwards
+ * compatibility. This list is not exhaustive; any positive `ms`-style duration
+ * string accepted by `@types/ms` (for example `2m`, `8h`, or `1 day`) is valid.
+ */
+export const PROBE_INTERVALS = [
+    "30s",
+    "1m",
+    "3m",
+    "5m",
+    "15m",
+    "30m",
+    "1h",
+    "2h",
+    "8h",
+    "24h",
+];
+export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
+export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
+export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
+export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+export const HttpRetryPreset = {
+    Off: "off",
+    TransportTransient: "transport_transient",
+    SafeRead: "safe_read",
+    AggressiveRead: "aggressive_read",
+    RateLimitAware: "rate_limit_aware",
+};
+export const HttpRetryJitter = {
+    None: "none",
+    Full: "full",
+    Equal: "equal",
+};
+export const HttpRetryDelayStrategy = {
+    Fixed: "fixed",
+    Exponential: "exponential",
+};
+export const HttpRetryAfterPolicy = {
+    Ignore: "ignore",
+    /** Honor Retry-After up to maxDelayMs. */
+    Respect: "respect",
+    /** Honor Retry-After but also cap it to the SDK-computed backoff delay. */
+    Cap: "cap",
+};
+export const HttpRetryUnsafeMethodPolicy = {
+    Reject: "reject",
+    AllowExplicitUnsafe: "allow_explicit_unsafe",
+};

package/dist/utils/date.d.ts

@@ -0,0 +1,6 @@
+/** Convert various date formats to ISO 8601 string */
+export declare function toISODate(v: unknown, timezone: string): string;
+/** Get today's date as ISO 8601 string in given timezone */
+export declare function today(timezone: string): string;
+/** Get current hour as string in given timezone */
+export declare function currentHour(timezone: string): string;

package/dist/utils/date.js

@@ -0,0 +1,101 @@
+function getDateParts(date, timezone) {
+    const formatter = new Intl.DateTimeFormat("en-CA", {
+        timeZone: timezone,
+        hour12: false,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    const parts = Object.fromEntries(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+    return {
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: parts.hour,
+        minute: parts.minute,
+        second: parts.second,
+    };
+}
+function getTimezoneOffsetMinutes(date, timezone) {
+    const parts = getDateParts(date, timezone);
+    const asUTC = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute), Number(parts.second));
+    return (asUTC - date.getTime()) / 60000;
+}
+function buildUtcInstantFromLocalParts(year, month, day, hour, minute, second, timezone) {
+    const guess = Date.UTC(year, month - 1, day, hour, minute, second);
+    let utc = guess;
+    for (let i = 0; i < 2; i += 1) {
+        const offset = getTimezoneOffsetMinutes(new Date(utc), timezone);
+        const nextUtc = guess - offset * 60_000;
+        if (nextUtc === utc) {
+            break;
+        }
+        utc = nextUtc;
+    }
+    return new Date(utc);
+}
+function formatOffset(offsetMinutes) {
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const abs = Math.abs(offsetMinutes);
+    const hours = String(Math.floor(abs / 60)).padStart(2, "0");
+    const minutes = String(abs % 60).padStart(2, "0");
+    return `${sign}${hours}:${minutes}`;
+}
+function formatIso(date, timezone) {
+    const parts = getDateParts(date, timezone);
+    const offset = getTimezoneOffsetMinutes(date, timezone);
+    return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}:${parts.second}${formatOffset(offset)}`;
+}
+function parseDateValue(v, timezone) {
+    if (v instanceof Date) {
+        return Number.isNaN(v.getTime()) ? null : v;
+    }
+    if (typeof v === "number") {
+        const date = new Date(v);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    if (typeof v !== "string") {
+        return null;
+    }
+    const value = v.trim();
+    if (value === "") {
+        return null;
+    }
+    const compactDate = /^(\d{4})(\d{2})(\d{2})$/;
+    const compactDateTime = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})?$/;
+    const dashedDate = /^(\d{4})-(\d{2})-(\d{2})$/;
+    let match = value.match(compactDateTime);
+    if (match) {
+        const [, year, month, day, hour, minute, second = "00"] = match;
+        return buildUtcInstantFromLocalParts(Number(year), Number(month), Number(day), Number(hour), Number(minute), Number(second), timezone);
+    }
+    match = value.match(compactDate);
+    if (match) {
+        const [, year, month, day] = match;
+        return buildUtcInstantFromLocalParts(Number(year), Number(month), Number(day), 0, 0, 0, timezone);
+    }
+    match = value.match(dashedDate);
+    if (match) {
+        const [, year, month, day] = match;
+        return buildUtcInstantFromLocalParts(Number(year), Number(month), Number(day), 0, 0, 0, timezone);
+    }
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/** Convert various date formats to ISO 8601 string */
+export function toISODate(v, timezone) {
+    const date = parseDateValue(v, timezone);
+    return date ? formatIso(date, timezone) : "";
+}
+/** Get today's date as ISO 8601 string in given timezone */
+export function today(timezone) {
+    const parts = getDateParts(new Date(), timezone);
+    return `${parts.year}-${parts.month}-${parts.day}`;
+}
+/** Get current hour as string in given timezone */
+export function currentHour(timezone) {
+    return getDateParts(new Date(), timezone).hour;
+}

package/dist/utils/parse.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Unwrap nested envelope by dot-path
+ * e.g., unwrapEnvelope({response: {body: {items: [...]}}}, 'response.body.items')
+ */
+export declare function unwrapEnvelope(data: unknown, path?: string): unknown;
+/**
+ * Pivot array by field — generalized version of pivotByCategory
+ * e.g., pivotByField([{type:'A', val:1},{type:'B', val:2}], 'type', 'val')
+ * → { A: 1, B: 2 }
+ */
+export declare function pivotByField(items: unknown[], keyField: string, valueField: string): Record<string, unknown>;
+/**
+ * Parse XML items from string — returns array
+ * Uses simple regex (no DOM), suitable for structured XML
+ */
+export declare function parseXmlItems(xml: string, tag: string): string[];

package/dist/utils/parse.js

@@ -0,0 +1,51 @@
+/**
+ * Unwrap nested envelope by dot-path
+ * e.g., unwrapEnvelope({response: {body: {items: [...]}}}, 'response.body.items')
+ */
+export function unwrapEnvelope(data, path) {
+    if (!path || path.trim() === "") {
+        return data;
+    }
+    const segments = path.split(".").filter(Boolean);
+    let current = data;
+    for (const segment of segments) {
+        if (!current || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Pivot array by field — generalized version of pivotByCategory
+ * e.g., pivotByField([{type:'A', val:1},{type:'B', val:2}], 'type', 'val')
+ * → { A: 1, B: 2 }
+ */
+export function pivotByField(items, keyField, valueField) {
+    const result = {};
+    for (const item of items) {
+        if (!item || typeof item !== "object") {
+            continue;
+        }
+        const record = item;
+        const key = record[keyField];
+        const value = record[valueField];
+        if (key === undefined || key === null || value === undefined) {
+            continue;
+        }
+        result[String(key)] = value;
+    }
+    return result;
+}
+/**
+ * Parse XML items from string — returns array
+ * Uses simple regex (no DOM), suitable for structured XML
+ */
+export function parseXmlItems(xml, tag) {
+    const matches = [
+        ...xml.matchAll(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, "gi")),
+    ];
+    return matches
+        .map((match) => match[1].replace(/<[^>]+>/g, "").trim())
+        .filter((item) => item.length > 0);
+}

package/dist/utils/text.d.ts

@@ -0,0 +1,4 @@
+/** Remove HTML tags from string */
+export declare function stripHtml(html: string): string;
+/** Truncate string to maxLength with optional suffix */
+export declare function truncate(str: string, maxLength: number, suffix?: string): string;

package/dist/utils/text.js

@@ -0,0 +1,14 @@
+/** Remove HTML tags from string */
+export function stripHtml(html) {
+    return html
+        .replace(/<[^>]*>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Truncate string to maxLength with optional suffix */
+export function truncate(str, maxLength, suffix = "...") {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return `${str.slice(0, maxLength)}${suffix}`;
+}

package/dist/utils/transform.d.ts

@@ -0,0 +1,8 @@
+/** Parse any value to number (returns 0 if not parseable) */
+export declare function toNumber(v: unknown): number;
+/** Parse any value to float */
+export declare function toFloat(v: unknown, decimals?: number): number;
+/** Parse any value to integer */
+export declare function toInt(v: unknown): number;
+/** Parse any value to boolean (handles "true", "1", "yes", true, 1) */
+export declare function toBoolean(v: unknown): boolean;

package/dist/utils/transform.js

@@ -0,0 +1,48 @@
+/** Parse any value to number (returns 0 if not parseable) */
+export function toNumber(v) {
+    if (typeof v === "number") {
+        return Number.isFinite(v) ? v : 0;
+    }
+    if (typeof v === "boolean") {
+        return v ? 1 : 0;
+    }
+    if (typeof v === "string") {
+        const cleaned = v.replaceAll(",", "").trim();
+        if (cleaned === "") {
+            return 0;
+        }
+        const parsed = Number(cleaned);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+/** Parse any value to float */
+export function toFloat(v, decimals) {
+    const parsed = toNumber(v);
+    if (!Number.isFinite(parsed)) {
+        return 0;
+    }
+    if (decimals === undefined) {
+        return parsed;
+    }
+    const factor = 10 ** decimals;
+    return Math.round(parsed * factor) / factor;
+}
+/** Parse any value to integer */
+export function toInt(v) {
+    return Math.round(toNumber(v));
+}
+/** Parse any value to boolean (handles "true", "1", "yes", true, 1) */
+export function toBoolean(v) {
+    if (typeof v === "boolean") {
+        return v;
+    }
+    if (typeof v === "number") {
+        return v === 1;
+    }
+    if (typeof v === "string") {
+        const normalized = v.trim().toLowerCase();
+        return ["true", "1", "yes", "y"].includes(normalized);
+    }
+    return false;
+}

package/package.json

@@ -1,16 +1,17 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.5",
+	"version": "2.1.0-beta.8",
 	"private": false,
 	"type": "module",
-	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",
+	"description": "APIFuse Provider SDK \u2014 Build providers with zero architectural constraints",
 	"license": "MIT",
-	"main": "./src/index.ts",
-	"types": "./src/index.ts",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"publishConfig": {
 		"access": "public"
 	},
 	"files": [
+		"dist",
 		"src",
 		"!src/__tests__",
 		"!src/__tests__/**",
@@ -35,46 +36,54 @@
 	},
 	"exports": {
 		".": {
-			"default": "./src/index.ts",
-			"import": "./src/index.ts",
-			"types": "./src/index.ts"
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
 		},
 		"./provider": {
-			"default": "./src/provider.ts",
-			"import": "./src/provider.ts",
-			"types": "./src/provider.ts"
+			"types": "./dist/provider.d.ts",
+			"import": "./dist/provider.js",
+			"default": "./dist/provider.js"
+		},
+		"./contract": {
+			"types": "./dist/contract.d.ts",
+			"import": "./dist/contract.js",
+			"default": "./dist/contract.js"
 		},
 		"./server": {
-			"default": "./src/server/index.ts",
-			"import": "./src/server/index.ts",
-			"types": "./src/server/index.ts"
+			"types": "./dist/server/index.d.ts",
+			"import": "./dist/server/index.js",
+			"default": "./dist/server/index.js"
 		},
 		"./testing": {
-			"default": "./src/testing/index.ts",
-			"import": "./src/testing/index.ts",
-			"types": "./src/testing/index.ts"
+			"types": "./dist/testing/index.d.ts",
+			"import": "./dist/testing/index.js",
+			"default": "./dist/testing/index.js"
 		},
 		"./create": {
-			"default": "./src/cli/create.ts",
-			"import": "./src/cli/create.ts",
-			"types": "./src/cli/create.ts"
+			"types": "./dist/cli/create.d.ts",
+			"import": "./dist/cli/create.js",
+			"default": "./dist/cli/create.js"
 		}
 	},
 	"scripts": {
-		"lint": "biome check",
+		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
 		"format": "biome format --write",
 		"type-check": "tsgo --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check",
-		"pack:check": "bun bin/apifuse-pack-check.ts",
-		"pack:smoke": "bun bin/apifuse-pack-smoke.ts"
+		"check": "bun run lint && bun run type-check && bun run build",
+		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
+		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
+		"release:guard": "bun scripts/guard-release-pr.ts",
+		"format:check": "biome format .",
+		"build": "tsgo -p tsconfig.build.json"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"typescript": "^6.0.3"
+		"@typescript/native-preview": "7.0.0-dev.20260419.1"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
@@ -90,5 +99,13 @@
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
 		"zod": "^4.4.3"
-	}
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/APIFuseHQ/provider-sdk.git"
+	},
+	"bugs": {
+		"url": "https://github.com/APIFuseHQ/provider-sdk/issues"
+	},
+	"homepage": "https://github.com/APIFuseHQ/provider-sdk#readme"
 }

package/src/ceremonies/index.ts

@@ -8,7 +8,12 @@ import {
 	TurnValidationError,
 	ValidationError,
 } from "../errors";
-import type { AuthFlowDefinition, AuthTurn, FlowContext } from "../types";
+import type {
+	AuthFlowDefinition,
+	AuthFlowInputHandler,
+	AuthTurn,
+	FlowContext,
+} from "../types";
 
 type TurnKind =
 	| "abort"
@@ -21,7 +26,7 @@ type TurnKind =
 	| "redirect"
 	| "retry";
 
-type CeremonyHandler = AuthFlowDefinition["start"];
+type CeremonyHandler = AuthFlowInputHandler;
 
 type JsonObject = Record<string, unknown>;
 
@@ -44,6 +49,7 @@ const authTurnSchema = {
 			additionalProperties: true,
 		},
 		hint: { type: "string" },
+		hintKey: { type: "string" },
 		timing: {
 			type: "object",
 			additionalProperties: false,

package/src/choice-token.ts

@@ -13,6 +13,7 @@ export type ProviderChoiceTokenErrorReason =
 	| "invalid_shape"
 	| "invalid_signature"
 	| "invalid_payload"
+	| "invalid_binding"
 	| "stale";
 
 export class ProviderChoiceTokenError extends Error {

package/src/cli/commands.ts

@@ -36,14 +36,14 @@ export const COMMAND_MANIFEST: Record<
 		summary:
 			"Start the local provider dev server with the standard provider server contract.",
 		usage: "apifuse dev [path]",
-		examples: ["apifuse dev .", "apifuse dev providers/airkorea"],
+		examples: ["apifuse dev .", "apifuse dev providers/korea-air-quality"],
 		modulePath: "./apifuse-dev",
 	},
 	check: {
 		name: "check",
 		summary: "Validate provider structure, metadata, fixtures, and schemas.",
 		usage: "apifuse check [path]",
-		examples: ["apifuse check .", "apifuse check providers/airkorea"],
+		examples: ["apifuse check .", "apifuse check providers/korea-air-quality"],
 		modulePath: "./apifuse-check",
 	},
 	"submit-check": {
@@ -72,7 +72,7 @@ export const COMMAND_MANIFEST: Record<
 		usage:
 			'apifuse record [path] --operation <operation> --params \'{"value":"hello"}\'',
 		examples: [
-			'apifuse record providers/airkorea --operation realtime --params \'{"stationName":"종로구"}\'',
+			'apifuse record providers/korea-air-quality --operation realtime --params \'{"stationName":"종로구"}\'',
 		],
 		modulePath: "./apifuse-record",
 	},
@@ -80,7 +80,10 @@ export const COMMAND_MANIFEST: Record<
 		name: "test",
 		summary: "Run provider-focused tests and surface actionable failures.",
 		usage: "apifuse test [path] [--json] [--verbose]",
-		examples: ["apifuse test .", "apifuse test providers/airkorea --json"],
+		examples: [
+			"apifuse test .",
+			"apifuse test providers/korea-air-quality --json",
+		],
 		modulePath: "./apifuse-test",
 	},
 	perf: {
@@ -90,7 +93,7 @@ export const COMMAND_MANIFEST: Record<
 		usage:
 			"apifuse perf <path> --operation <operation> [--params '<json>'] [options]",
 		examples: [
-			'apifuse perf providers/airkorea --operation realtime --params \'{"stationName":"종로구"}\' --runs 5',
+			'apifuse perf providers/korea-air-quality --operation realtime --params \'{"stationName":"종로구"}\' --runs 5',
 		],
 		modulePath: "./apifuse-perf",
 	},

package/src/cli/create.ts

@@ -502,6 +502,15 @@ export async function buildProviderCreatePlan(
 			path: resolve(providerRoot, "operations", "ping.ts"),
 			content: await renderTemplate("operations/ping.ts.tpl", {
 				DISPLAY_NAME: escapeTemplate(options.displayName),
+				HANDLER_CTX: options.runtime === "browser" ? "ctx" : "_ctx",
+				BROWSER_HANDLER_BLOCK:
+					options.runtime === "browser"
+						? '\n    const page = await ctx.browser.newPage();\n    await page.goto("https://example.com");\n    const title = await page.title();\n    const frames = await page.frames();\n    await page.close();\n'
+						: "",
+				BROWSER_RESPONSE_FIELDS:
+					options.runtime === "browser"
+						? ",\n      pageTitle: title,\n      frameCount: frames.length"
+						: "",
 			}),
 		},
 		{
@@ -701,6 +710,14 @@ function renderStarterLocaleCatalog(
 					locale === "ko"
 						? "생성된 provider가 샘플 payload를 round-trip했음을 보여주는 사람이 읽을 수 있는 확인 메시지"
 						: "Human-readable confirmation that the generated provider round-tripped the sample payload.",
+				pageTitle:
+					locale === "ko"
+						? "browser 런타임 provider일 때 로드된 페이지의 제목 (해당되지 않으면 생략)"
+						: "Title of the loaded page when the provider uses the browser runtime; omitted otherwise.",
+				frameCount:
+					locale === "ko"
+						? "browser 런타임 provider일 때 로드된 페이지의 frame 개수 (해당되지 않으면 생략)"
+						: "Number of frames in the loaded page when the provider uses the browser runtime; omitted otherwise.",
 			},
 		},
 	};
@@ -744,6 +761,17 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
         },
         hint: "Generated placeholder credential flow completed. Replace this with real auth logic.",
       }),
+      refresh: async () => ({
+        kind: "complete",
+        turnId: crypto.randomUUID(),
+        data: {
+          credential: {
+            username: "replace-with-refreshed-username",
+            password: "replace-with-refreshed-password",
+          },
+        },
+        hint: "Return refreshed credential data here, or throw AuthError with code AUTH_REQUIRED when silent refresh is not possible.",
+      }),
     },
   }`;
 		case "oauth2":

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -6,10 +6,11 @@ export const pingOperation = defineOperation({
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,
-  handler: async (_ctx, input) => {
+  handler: async ({{HANDLER_CTX}}, input) => {
+    {{BROWSER_HANDLER_BLOCK}}
     return {
       ok: true,
-      message: "{{DISPLAY_NAME}} received: " + input.value,
+      message: "{{DISPLAY_NAME}} received: " + input.value{{BROWSER_RESPONSE_FIELDS}},
     };
   },
   fixtures: {

package/src/cli/templates/provider/schemas/ping.ts.tpl

@@ -11,6 +11,14 @@ export const pingOutputSchema = describeKey(
   z.object({
     ok: describeKey(z.boolean(), "schemaDescriptions.output.ok"),
     message: describeKey(z.string(), "schemaDescriptions.output.message"),
+    pageTitle: describeKey(
+      z.string().optional(),
+      "schemaDescriptions.output.pageTitle",
+    ),
+    frameCount: describeKey(
+      z.number().int().nonnegative().optional(),
+      "schemaDescriptions.output.frameCount",
+    ),
   }),
   "schemaDescriptions.output.root",
 );

package/src/config/loader.ts

@@ -16,6 +16,8 @@ export const DEFAULT_PROXY_LIFETIME_ENV =
 	"APIFUSE__PROXY__DEFAULT_LIFETIME_MINUTES";
 export const PROVIDER_CACHE_REDIS_URL_ENV =
 	"APIFUSE__PROVIDER__CACHE_REDIS_URL";
+export const PROVIDER_STATE_REDIS_URL_ENV =
+	"APIFUSE__PROVIDER__STATE_REDIS_URL";
 export const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
 
 export type ProxyOptions = {
@@ -175,6 +177,19 @@ const SMARTPROXY_EXTRACTION_SOFT_REFRESH_MS = 10_000;
 
 function redisUrlFromEnv(): string | undefined {
 	return (
+		process.env.APIFUSE__PROVIDER__CACHE_REDIS_URL?.trim() ||
+		process.env[REDIS_URL_ENV]?.trim() ||
+		undefined
+	);
+}
+
+export function providerCacheRedisUrlFromEnv(): string | undefined {
+	return redisUrlFromEnv();
+}
+
+export function providerStateRedisUrlFromEnv(): string | undefined {
+	return (
+		process.env[PROVIDER_STATE_REDIS_URL_ENV]?.trim() ||
 		process.env[PROVIDER_CACHE_REDIS_URL_ENV]?.trim() ||
 		process.env[REDIS_URL_ENV]?.trim() ||
 		undefined
@@ -620,7 +635,10 @@ function selectProxyPoolIndex(poolSize: number, attempt = 0): number {
 	if (poolSize <= 1) {
 		return 0;
 	}
-	return Math.max(0, Math.floor(attempt)) % poolSize;
+	const normalizedAttempt = Number.isFinite(attempt)
+		? Math.max(0, Math.floor(attempt))
+		: 0;
+	return normalizedAttempt % poolSize;
 }
 
 function buildSmartproxyCacheKey(