@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.5

package/dist/auth.js

@@ -1,4 +1,4 @@
-import { AuthError, ProviderError } from "./errors";
+import { AuthError, ProviderError } from "./errors.js";
 const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
 const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
 const DEFAULT_ABORT_TURN_ID = "auth.abort";
@@ -97,7 +97,7 @@ export function createAuthFlowHelpers(options = {}) {
                 },
             };
         },
-        abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt, }) {
+        abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt }) {
             return {
                 kind: "abort",
                 ...authTurnBase({ turnId, defaultTurnId: DEFAULT_ABORT_TURN_ID, expiresAt }),
@@ -169,12 +169,8 @@ function expectedInputFromFields(fields) {
                 ...(field.type === "password" ? { format: "password" } : {}),
                 ...(field.type === "otp" ? { format: "otp" } : {}),
                 ...(field.labelKey ? { nameKey: field.labelKey } : {}),
-                ...(field.descriptionKey
-                    ? { descriptionKey: field.descriptionKey }
-                    : {}),
-                ...(field.placeholderKey
-                    ? { placeholderKey: field.placeholderKey }
-                    : {}),
+                ...(field.descriptionKey ? { descriptionKey: field.descriptionKey } : {}),
+                ...(field.placeholderKey ? { placeholderKey: field.placeholderKey } : {}),
                 ...(field.sensitive || field.type === "password" || field.type === "otp"
                     ? { sensitive: true }
                     : {}),
@@ -291,17 +287,15 @@ function completeTurn(credentialKeys, result, defaultTurnId) {
     };
 }
 function challengeTurn(definition, request) {
-    const expectedInput = definition.fields
-        ? expectedInputFromFields(definition.fields)
-        : undefined;
+    const expectedInput = definition.fields ? expectedInputFromFields(definition.fields) : undefined;
     return {
         kind: expectedInput ? "form" : "pending",
         turnId: request.turnId ?? definition.turnId ?? `credentials.${request.challengeId}`,
         ...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
-        ...(request.hintKey ?? definition.hintKey
+        ...((request.hintKey ?? definition.hintKey)
             ? { hintKey: request.hintKey ?? definition.hintKey }
             : {}),
-        ...(request.timing ?? definition.timing
+        ...((request.timing ?? definition.timing)
             ? { timing: request.timing ?? definition.timing }
             : {}),
         ...(expectedInput ? { expectedInput } : {}),
@@ -378,7 +372,7 @@ async function pollPendingChallenge(ctx, credentialKeys, challenges, pending, co
 export function defineCredentialsAuth(options) {
     if (Object.keys(options.fields).length === 0) {
         throw new ProviderError("defineCredentialsAuth requires at least one field", {
-            fix: "Pass fields such as { email: { type: \"email\" }, password: { type: \"password\" } }.",
+            fix: 'Pass fields such as { email: { type: "email" }, password: { type: "password" } }.',
         });
     }
     const expectedInput = expectedInputFromFields(options.fields);
@@ -427,10 +421,7 @@ export function defineCredentialsAuth(options) {
             ...(options.justification ? { justification: options.justification } : {}),
         },
         context: {
-            keys: Array.from(new Set([
-                CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY,
-                ...(options.contextKeys ?? []),
-            ])),
+            keys: Array.from(new Set([CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, ...(options.contextKeys ?? [])])),
         },
     };
 }

package/dist/ceremonies/index.d.ts

@@ -1,4 +1,4 @@
-import type { AuthFlowDefinition, AuthTurn } from "../types";
+import type { AuthFlowDefinition, AuthTurn } from "../types.js";
 type JsonObject = Record<string, unknown>;
 export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
 export declare function createOAuth2Ceremony(options: {

package/dist/ceremonies/index.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import Ajv2020 from "ajv/dist/2020.js";
-import { AUTH_TURN_SCHEMA } from "../auth-turn";
-import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors";
+import { AUTH_TURN_SCHEMA } from "../auth-turn/index.js";
+import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors.js";
 const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
 // Runtime ceremony-output validation derives from the exported versioned
 // contract: it compiles the exact AUTH_TURN_SCHEMA document shipped at
@@ -38,11 +38,7 @@ function getRequiredEnv(ctx, key) {
     return value;
 }
 function toBase64Url(input) {
-    return input
-        .toString("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/g, "");
+    return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
 function createCodeVerifier() {
     return toBase64Url(randomBytes(32));
@@ -100,8 +96,7 @@ function withDeclaredFormFieldOrder(expectedInput) {
         return expectedInput;
     }
     const existingOrder = expectedInput[FORM_FIELD_ORDER_EXTENSION];
-    if (Array.isArray(existingOrder) &&
-        existingOrder.every((value) => typeof value === "string")) {
+    if (Array.isArray(existingOrder) && existingOrder.every((value) => typeof value === "string")) {
         return expectedInput;
     }
     return {
@@ -218,8 +213,7 @@ export function createDeviceFlowCeremony(options) {
             });
             const data = ensureRecord(response.data);
             const errorCode = getString(data, "error");
-            if (errorCode === "authorization_pending" ||
-                errorCode === "slow_down") {
+            if (errorCode === "authorization_pending" || errorCode === "slow_down") {
                 return createTurn("poll", {
                     data,
                     hint: "Authorization pending.",
@@ -345,7 +339,7 @@ export function createFormCeremony(options) {
     return {
         start: async () => validateCeremonyOutput(buildJsonSchemaForm(options.schema, options.hint ?? "Provide the required input to continue.")),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
-            const { prevalidate } = await import("../runtime/prevalidate");
+            const { prevalidate } = await import("../runtime/prevalidate.js");
             const result = prevalidate(options.schema, input);
             if (!result.valid) {
                 throw new ValidationError("Form input failed validation.", {
@@ -354,9 +348,7 @@ export function createFormCeremony(options) {
             }
             return createTurn("complete", {
                 data: {
-                    credential: options.mapCredential
-                        ? options.mapCredential(input)
-                        : input,
+                    credential: options.mapCredential ? options.mapCredential(input) : input,
                 },
                 hint: "Form completed.",
             });
@@ -428,9 +420,7 @@ export function createSwitchCeremony(options) {
         })),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const storedChoice = ctx.context.get(SWITCH_SELECTION_KEY);
-            const choice = typeof storedChoice === "string"
-                ? storedChoice
-                : getString(input, "choice");
+            const choice = typeof storedChoice === "string" ? storedChoice : getString(input, "choice");
             if (!choice || !options.choices[choice]) {
                 throw new ValidationError("A valid choice is required.");
             }

package/dist/config/loader.d.ts

@@ -1,5 +1,5 @@
-import Redis from "ioredis";
-import type { ProviderProxyPolicy, TraceConfig } from "../types";
+import { Redis } from "ioredis";
+import type { ProviderProxyPolicy, TraceConfig } from "../types.js";
 export declare const SMARTPROXY_APP_KEY_ENV = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 export declare const SMARTPROXY_MAX_LIFETIME_MINUTES = 2000;
 export declare const DEFAULT_SMARTPROXY_POOL_SIZE = 20;

package/dist/config/loader.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 export const SMARTPROXY_APP_KEY_ENV = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 export const SMARTPROXY_MAX_LIFETIME_MINUTES = 2000;
 export const DEFAULT_SMARTPROXY_POOL_SIZE = 20;
@@ -160,9 +160,7 @@ function toProxyDiagnostics(value) {
         return undefined;
     const diagnostics = {};
     for (const [key, item] of Object.entries(value)) {
-        if (typeof item === "string" ||
-            typeof item === "number" ||
-            typeof item === "boolean") {
+        if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
             diagnostics[key] = item;
         }
     }
@@ -249,9 +247,7 @@ function applyStickyProxySession(proxyUrl) {
 }
 function buildSmartproxyUsername(username, sessionId, sessionDuration) {
     const parts = username.split("_");
-    const configuredLife = parts
-        .find((part) => part.startsWith("life-"))
-        ?.slice("life-".length);
+    const configuredLife = parts.find((part) => part.startsWith("life-"))?.slice("life-".length);
     const baseUsername = parts
         .filter((part) => !part.startsWith("session-") && !part.startsWith("life-"))
         .join("_");
@@ -259,9 +255,7 @@ function buildSmartproxyUsername(username, sessionId, sessionDuration) {
 }
 function buildDecodoUsername(username, sessionId, sessionDuration) {
     const withoutSticky = username.replace(/-session-.+-sessionduration-\d+$/, "");
-    const baseUsername = withoutSticky.startsWith("user-")
-        ? withoutSticky
-        : `user-${withoutSticky}`;
+    const baseUsername = withoutSticky.startsWith("user-") ? withoutSticky : `user-${withoutSticky}`;
     return `${baseUsername}-session-${sessionId}-sessionduration-${sessionDuration}`;
 }
 function syncProxyEnv(config) {
@@ -358,18 +352,13 @@ function resolvePolicy(options) {
     return undefined;
 }
 function resolveProxyProvider(policy) {
-    return (policy.provider ??
-        process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase() ??
-        "custom");
+    return (policy.provider ?? process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase() ?? "custom");
 }
 function resolveSmartproxyCountry(policy) {
-    return (policy.geo?.country ??
-        process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ??
-        undefined);
+    return (policy.geo?.country ?? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ?? undefined);
 }
 function resolveSmartproxyLifetime(policy) {
-    const configuredLifetime = policy.session?.lifetimeMinutes ??
-        readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30);
+    const configuredLifetime = policy.session?.lifetimeMinutes ?? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30);
     return Math.min(SMARTPROXY_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configuredLifetime)));
 }
 function readPositiveNumberEnv(name, fallback) {
@@ -389,9 +378,7 @@ function selectProxyPoolIndex(poolSize, attempt = 0) {
     if (poolSize <= 1) {
         return 0;
     }
-    const normalizedAttempt = Number.isFinite(attempt)
-        ? Math.max(0, Math.floor(attempt))
-        : 0;
+    const normalizedAttempt = Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
     return normalizedAttempt % poolSize;
 }
 function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes) {
@@ -400,9 +387,7 @@ function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes) {
         provider: "smartproxy",
         country: resolveSmartproxyCountry(policy),
         affinity: policy.session?.affinity ?? "request",
-        affinityKey: (policy.session?.affinity ?? "request") === "request"
-            ? undefined
-            : affinityKey,
+        affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
         lifetimeMinutes,
         poolSize,
     });
@@ -499,9 +484,7 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
         if (acquired === "OK") {
             try {
                 return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, {
-                    cacheStatus: options.background
-                        ? "soft_stale_refresh"
-                        : "allocator",
+                    cacheStatus: options.background ? "soft_stale_refresh" : "allocator",
                     redis,
                     poolKey,
                 });
@@ -526,8 +509,7 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
         if (typeof pttl === "number" && pttl <= 0) {
             continue;
         }
-        if (Date.now() - startedAt >
-            SMARTPROXY_LOCK_POLL_MAX_MS - SMARTPROXY_DEADLINE_MARGIN_MS) {
+        if (Date.now() - startedAt > SMARTPROXY_LOCK_POLL_MAX_MS - SMARTPROXY_DEADLINE_MARGIN_MS) {
             break;
         }
         await sleep(Math.min(500, Math.max(50, typeof pttl === "number" ? pttl : 100)));
@@ -559,7 +541,7 @@ function sleep(ms, signal) {
     });
 }
 function smartproxyAllocatorDeadlineMs() {
-    return (smartproxyAllocatorDeadlineMsForTests ?? SMARTPROXY_ALLOCATOR_DEADLINE_MS);
+    return smartproxyAllocatorDeadlineMsForTests ?? SMARTPROXY_ALLOCATOR_DEADLINE_MS;
 }
 function createDeadlineAbortController(deadlineAt) {
     const controller = new AbortController();
@@ -649,9 +631,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
         }
     }
     const allocatorMs = Math.max(0, Date.now() - allocatorStartedAt);
-    const allocatorAttempts = allocation?.attempt ??
-        lastFailure?.attempt ??
-        SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS;
+    const allocatorAttempts = allocation?.attempt ?? lastFailure?.attempt ?? SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS;
     const allocatorBodyClass = lastFailure?.bodyClass ?? allocation?.bodyClass ?? "usable_proxy_endpoints";
     const allocatorStatus = lastFailure ? lastFailure.status : allocation?.status;
     if (!allocation) {
@@ -804,7 +784,9 @@ function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize)
     if (country) {
         params.set("cc", country);
     }
-    return `https://www.smartproxy.org/web_v1/ip/get-ip-v3?${params.toString()}`;
+    // www.smartproxy.org stopped serving the extraction API on 2026-07-21 (the
+    // old path 404s into the marketing site); the API lives on the api host.
+    return `https://api.smartproxy.org/web_v1/ip/get-ip-v3?${params.toString()}`;
 }
 function parseSmartproxyAllocatorProxies(body) {
     const trimmed = body.trim();
@@ -813,12 +795,8 @@ function parseSmartproxyAllocatorProxies(body) {
     }
     try {
         const parsed = JSON.parse(trimmed);
-        const data = parsed && typeof parsed === "object" && "data" in parsed
-            ? parsed.data
-            : undefined;
-        const list = data && typeof data === "object" && "list" in data
-            ? data.list
-            : undefined;
+        const data = parsed && typeof parsed === "object" && "data" in parsed ? parsed.data : undefined;
+        const list = data && typeof data === "object" && "list" in data ? data.list : undefined;
         if (Array.isArray(list)) {
             return list
                 .map((item) => {
@@ -826,8 +804,7 @@ function parseSmartproxyAllocatorProxies(body) {
                     return null;
                 }
                 const ip = "ip" in item && typeof item.ip === "string" ? item.ip : "";
-                const port = "port" in item &&
-                    (typeof item.port === "string" || typeof item.port === "number")
+                const port = "port" in item && (typeof item.port === "string" || typeof item.port === "number")
                     ? item.port
                     : "";
                 return ip && port ? `http://${ip}:${port}` : null;

package/dist/contract-serialization.d.ts

@@ -1,4 +1,4 @@
-import { type JsonValue } from "./contract-json";
-import type { SchemaLike } from "./types";
+import { type JsonValue } from "./contract-json.js";
+import type { SchemaLike } from "./types.js";
 export declare function describeSchema(schema: SchemaLike): JsonValue;
 export declare function serializeSmsMatcher(value: Record<string, unknown>): Record<string, unknown>;

package/dist/contract-serialization.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import { canonicalJson, compactObject, isRecord, toJsonValue, } from "./contract-json";
+import { canonicalJson, compactObject, isRecord, toJsonValue, } from "./contract-json.js";
 export function describeSchema(schema) {
     if (isZodSchema(schema)) {
         const jsonSchema = zodJsonSchema(schema);
@@ -9,9 +9,7 @@ export function describeSchema(schema) {
             vendor: "zod",
             typeName: getSchemaTypeName(schema),
             jsonSchema,
-            jsonSchemaHash: jsonSchema === undefined
-                ? undefined
-                : digest(canonicalJson(jsonSchema)),
+            jsonSchemaHash: jsonSchema === undefined ? undefined : digest(canonicalJson(jsonSchema)),
         });
     }
     const standard = isRecord(schema) ? schema["~standard"] : undefined;
@@ -20,8 +18,7 @@ export function describeSchema(schema) {
             kind: "schema",
             standard: "standard-schema-v1",
             vendor: typeof standard.vendor === "string" ? standard.vendor : "unknown",
-            version: typeof standard.version === "number" ||
-                typeof standard.version === "string"
+            version: typeof standard.version === "number" || typeof standard.version === "string"
                 ? standard.version
                 : undefined,
         });

package/dist/contract-types.d.ts

@@ -1,5 +1,5 @@
-import type { JsonValue } from "./contract-json";
-import type { ProviderDefinition } from "./types";
+import type { JsonValue } from "./contract-json.js";
+import type { ProviderDefinition } from "./types.js";
 export declare const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";
 export interface ProviderContractSnapshot {
     readonly schemaVersion: typeof PROVIDER_CONTRACT_SCHEMA_VERSION;

package/dist/contract.d.ts

@@ -1,6 +1,6 @@
-import { canonicalJson, type JsonPrimitive, type JsonValue } from "./contract-json";
-import { PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot } from "./contract-types";
-import type { ProviderDefinition } from "./types";
+import { canonicalJson, type JsonPrimitive, type JsonValue } from "./contract-json.js";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot } from "./contract-types.js";
+import type { ProviderDefinition } from "./types.js";
 export { canonicalJson, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, };
 export declare function extractProviderContract(provider: ProviderDefinition): ProviderContractSnapshot;
 export declare function digestProviderContract(snapshot: ProviderContractSnapshot): string;

package/dist/contract.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { canonicalJson, compactObject, copyRecordWithout, toJsonValue, } from "./contract-json";
-import { describeSchema, serializeSmsMatcher } from "./contract-serialization";
-import { PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract-types";
+import { canonicalJson, compactObject, copyRecordWithout, toJsonValue, } from "./contract-json.js";
+import { describeSchema, serializeSmsMatcher } from "./contract-serialization.js";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract-types.js";
 export { canonicalJson, PROVIDER_CONTRACT_SCHEMA_VERSION, };
 export function extractProviderContract(provider) {
     const auth = extractAuth(provider.auth);
@@ -27,9 +27,7 @@ export function extractProviderContract(provider) {
         operations: Object.entries(provider.operations)
             .sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
             .map(([operationId, operation]) => extractOperation(operationId, operation)),
-        ...(provider.allowedHosts
-            ? { allowedHosts: [...provider.allowedHosts].sort() }
-            : {}),
+        ...(provider.allowedHosts ? { allowedHosts: [...provider.allowedHosts].sort() } : {}),
         ...(stealth === undefined ? {} : { stealth }),
         ...(proxy === undefined ? {} : { proxy }),
         ...(stt === undefined ? {} : { stt }),

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -41,6 +41,13 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
+    /**
+     * Optional deployment overrides, passed through verbatim onto the returned
+     * provider definition. The SDK types this field but does not deep-validate
+     * it — the APIFuse registry builder owns deployment validation and
+     * resolves omitted fields against the runtime deployment profiles.
+     */
+    deployment?: ProviderDeploymentOverrides;
     allowedHosts?: string[];
     stealth?: {
         profile: string;