@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/dist/runtime/browser.js

@@ -1,8 +1,109 @@
 import { createRequire } from "node:module";
-import { ProviderError } from "../errors";
+import { ProviderError } from "../errors.js";
 const require = createRequire(import.meta.url);
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const SELECTOR_POLL_INTERVAL_MS = 100;
+const RESOURCE_POLICY_ROUTE_PATTERN = "**/*";
+const DEFAULT_RESOURCE_METHODS = ["GET", "HEAD"];
+function toResourceBody(body) {
+    if (body === undefined || typeof body === "string" || Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (body instanceof ArrayBuffer) {
+        return Buffer.from(new Uint8Array(body));
+    }
+    return Buffer.from(body);
+}
+function isResourceMethod(method) {
+    return method === "GET" || method === "HEAD";
+}
+async function toResourceRequest(request) {
+    const method = request.method().toUpperCase();
+    if (!isResourceMethod(method)) {
+        return null;
+    }
+    return {
+        headers: await request.allHeaders(),
+        method,
+        resourceType: request.resourceType(),
+        url: request.url(),
+    };
+}
+function toCdpResourceRequest(params) {
+    if (!isRecord(params)) {
+        return null;
+    }
+    const requestId = params.requestId;
+    const rawRequest = params.request;
+    if (typeof requestId !== "string" || !isRecord(rawRequest)) {
+        return null;
+    }
+    const url = rawRequest.url;
+    const method = String(rawRequest.method ?? "").toUpperCase();
+    if (typeof url !== "string" || !isResourceMethod(method)) {
+        return null;
+    }
+    return {
+        requestId,
+        request: {
+            headers: toCdpResourceHeaders(rawRequest.headers),
+            method,
+            resourceType: typeof params.resourceType === "string" ? params.resourceType : undefined,
+            url,
+        },
+    };
+}
+function getCdpPausedRequestId(params) {
+    if (!isRecord(params) || typeof params.requestId !== "string") {
+        return null;
+    }
+    return params.requestId;
+}
+function toCdpResourceHeaders(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const headers = {};
+    for (const [name, headerValue] of Object.entries(value)) {
+        if (typeof headerValue === "string") {
+            headers[name] = headerValue;
+        }
+    }
+    return headers;
+}
+function matchesResourceRoute(match, request) {
+    if (typeof match === "string") {
+        return request.url === match;
+    }
+    if (match instanceof RegExp) {
+        return match.test(request.url);
+    }
+    return match(request);
+}
+function toCdpFulfillParams(requestId, decision) {
+    const body = toResourceBody(decision.body);
+    return {
+        ...(body === undefined ? {} : { body: Buffer.from(body).toString("base64") }),
+        ...(decision.headers === undefined
+            ? {}
+            : {
+                responseHeaders: Object.entries(decision.headers).map(([name, value]) => ({
+                    name,
+                    value,
+                })),
+            }),
+        requestId,
+        responseCode: decision.status ?? 200,
+    };
+}
+async function fulfillResourceRoute(route, decision) {
+    const body = toResourceBody(decision.body);
+    await route.fulfill({
+        ...(body === undefined ? {} : { body }),
+        ...(decision.headers === undefined ? {} : { headers: decision.headers }),
+        status: decision.status ?? 200,
+    });
+}
 function getDefaultCdpPoolUrl(env = process.env) {
     return env.APIFUSE__CDP_POOL__URL;
 }
@@ -256,6 +357,38 @@ class PlaywrightBrowserPage {
     async close() {
         await this.page.close();
     }
+    async withResourcePolicy(policy, run) {
+        const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
+        const handler = async (route) => {
+            const request = await toResourceRequest(route.request());
+            if (!request || !allowedMethods.has(request.method)) {
+                await route.abort("blockedbyclient");
+                return;
+            }
+            for (const resourceRoute of policy.routes) {
+                if (!matchesResourceRoute(resourceRoute.match, request)) {
+                    continue;
+                }
+                const decision = await resourceRoute.handle(request);
+                switch (decision.action) {
+                    case "fulfill":
+                        await fulfillResourceRoute(route, decision);
+                        return;
+                    case "block":
+                        await route.abort("blockedbyclient");
+                        return;
+                }
+            }
+            await route.abort("blockedbyclient");
+        };
+        await this.page.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+        try {
+            return await run();
+        }
+        finally {
+            await this.page.unroute(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+        }
+    }
 }
 class PlaywrightBrowserClient {
     options;
@@ -442,16 +575,13 @@ function parsePoolAcquireResponse(value) {
             code: "BROWSER_RUNTIME_UNSUPPORTED",
         });
     }
-    if (value.browserContextId !== undefined &&
-        typeof value.browserContextId !== "string") {
+    if (value.browserContextId !== undefined && typeof value.browserContextId !== "string") {
         throw new ProviderError("CDP Pool returned an invalid acquire response", {
             code: "BROWSER_RUNTIME_UNSUPPORTED",
         });
     }
     return {
-        ...(value.browserContextId
-            ? { browserContextId: value.browserContextId }
-            : {}),
+        ...(value.browserContextId ? { browserContextId: value.browserContextId } : {}),
         pageId: value.pageId,
         wsEndpoint: value.wsEndpoint,
     };
@@ -473,9 +603,7 @@ function parseCdpFrameTreeNode(value) {
         frame: {
             id: frameId,
             name: typeof value.frame.name === "string" ? value.frame.name : undefined,
-            parentId: typeof value.frame.parentId === "string"
-                ? value.frame.parentId
-                : undefined,
+            parentId: typeof value.frame.parentId === "string" ? value.frame.parentId : undefined,
             url: typeof value.frame.url === "string" ? value.frame.url : undefined,
         },
         ...(childFrames ? { childFrames } : {}),
@@ -488,9 +616,7 @@ function getCdpExecutionContext(params) {
     const contextId = params.context.id;
     const auxData = params.context.auxData;
     return {
-        frameId: isRecord(auxData) && typeof auxData.frameId === "string"
-            ? auxData.frameId
-            : undefined,
+        frameId: isRecord(auxData) && typeof auxData.frameId === "string" ? auxData.frameId : undefined,
         id: typeof contextId === "number" ? contextId : undefined,
     };
 }
@@ -641,8 +767,7 @@ class CdpPoolBrowserPage {
             returnByValue: true,
         });
         if (result.exceptionDetails) {
-            throw new Error(String(result.exceptionDetails.text ??
-                "Browser evaluation failed"));
+            throw new Error(String(result.exceptionDetails.text ?? "Browser evaluation failed"));
         }
         return result.result?.value;
     }
@@ -727,9 +852,7 @@ class CdpPoolBrowserPage {
         this.closed = true;
         try {
             await this.release({
-                ...(this.browserContextId
-                    ? { browserContextId: this.browserContextId }
-                    : {}),
+                ...(this.browserContextId ? { browserContextId: this.browserContextId } : {}),
                 pageId: this.pageId,
             });
         }
@@ -737,6 +860,77 @@ class CdpPoolBrowserPage {
             await this.pageClient.close();
         }
     }
+    async withResourcePolicy(policy, run) {
+        const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
+        const handlePausedRequest = (params) => {
+            void this.handleResourcePolicyPausedRequest(params, policy, allowedMethods);
+        };
+        const unsubscribe = this.pageClient.on("Fetch.requestPaused", handlePausedRequest);
+        try {
+            await this.pageClient.send("Fetch.enable", {
+                patterns: [{ requestStage: "Request", urlPattern: "*" }],
+            });
+        }
+        catch (error) {
+            unsubscribe();
+            throw new ProviderError("CDP browser target does not support BrowserPage.withResourcePolicy()", {
+                cause: error instanceof Error ? error : undefined,
+                code: "BROWSER_RUNTIME_UNSUPPORTED",
+                fix: "Use a Chromium CDP target with the Fetch domain enabled, or use the local Playwright browser runtime.",
+            });
+        }
+        try {
+            return await run();
+        }
+        finally {
+            unsubscribe();
+            await this.pageClient.send("Fetch.disable");
+        }
+    }
+    async handleResourcePolicyPausedRequest(params, policy, allowedMethods) {
+        const requestId = getCdpPausedRequestId(params);
+        if (requestId === null) {
+            return;
+        }
+        try {
+            const parsed = toCdpResourceRequest(params);
+            if (!parsed || !allowedMethods.has(parsed.request.method)) {
+                await this.failCdpResourceRequest(requestId);
+                return;
+            }
+            for (const resourceRoute of policy.routes) {
+                if (!matchesResourceRoute(resourceRoute.match, parsed.request)) {
+                    continue;
+                }
+                const decision = await resourceRoute.handle(parsed.request);
+                switch (decision.action) {
+                    case "fulfill":
+                        await this.pageClient.send("Fetch.fulfillRequest", toCdpFulfillParams(parsed.requestId, decision));
+                        return;
+                    case "block":
+                        await this.failCdpResourceRequest(parsed.requestId);
+                        return;
+                }
+            }
+            await this.failCdpResourceRequest(parsed.requestId);
+        }
+        catch {
+            await this.failCdpResourceRequest(requestId);
+        }
+    }
+    async failCdpResourceRequest(requestId) {
+        try {
+            await this.pageClient.send("Fetch.failRequest", {
+                errorReason: "BlockedByClient",
+                requestId,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                return;
+            }
+        }
+    }
     async initialize() {
         if (this.initialized) {
             return;
@@ -799,12 +993,8 @@ class CdpPoolBrowserClient {
     }
     async acquirePage(options) {
         const acquireResult = parsePoolAcquireResponse(await this.poolClient.send("acquire", {
-            ...(this.allowedHosts.length > 0
-                ? { allowedHosts: this.allowedHosts }
-                : {}),
-            ...(options?.isolatedContext
-                ? { isolationMode: "browserContext" }
-                : {}),
+            ...(this.allowedHosts.length > 0 ? { allowedHosts: this.allowedHosts } : {}),
+            ...(options?.isolatedContext ? { isolationMode: "browserContext" } : {}),
         }));
         const pageClient = new JsonRpcWebSocketClient(acquireResult.wsEndpoint);
         const page = new CdpPoolBrowserPage(acquireResult.pageId, acquireResult.browserContextId, pageClient, async (request) => {
@@ -1020,8 +1210,7 @@ async function solveRecaptchaChallenge(page, request) {
 async function findRecaptchaFrame(frames, siteKey) {
     for (const frame of frames) {
         const url = await frame.url();
-        const matchesRecaptcha = url.includes("google.com/recaptcha") ||
-            url.includes("recaptcha.net/recaptcha");
+        const matchesRecaptcha = url.includes("google.com/recaptcha") || url.includes("recaptcha.net/recaptcha");
         const matchesSiteKey = !siteKey || url.includes(siteKey);
         if (matchesRecaptcha && matchesSiteKey) {
             return frame;

package/dist/runtime/cache.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderCache } from "../types";
+import type { ProviderCache } from "../types.js";
 export type ProviderCacheOptions = {
     providerId: string;
     redisUrl?: string;

package/dist/runtime/cache.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { providerCacheRedisUrlFromEnv } from "../config/loader";
-import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis";
+import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
+import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
 const DEFAULT_PREFIX = "apifuse:provider-cache:v1";
 const DEFAULT_MEMORY_MAX_ENTRIES = 1_000;
 const DEFAULT_REDIS_TIMEOUT_MS = 150;
@@ -71,10 +71,7 @@ function normalizeKeyPart(value, extra) {
     return value;
 }
 function stableHash(value) {
-    return createHash("sha256")
-        .update(JSON.stringify(value))
-        .digest("hex")
-        .slice(0, 32);
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 32);
 }
 function jitteredTtlMs(ttlMs, jitterPct) {
     if (!jitterPct || jitterPct <= 0)
@@ -282,8 +279,7 @@ export function createProviderCache(options) {
         async delete(key) {
             backend.memory.delete(key);
             const redis = backend.redis;
-            if (!redis ||
-                !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+            if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
                 return;
             }
             await withRedisFallback(() => redis.del(key));

package/dist/runtime/choice.d.ts

@@ -1,4 +1,4 @@
-import type { CredentialContext, EnvContext, ProviderChoiceContext, ProviderRequestContext, ProviderRuntimeState } from "../types";
+import type { CredentialContext, EnvContext, ProviderChoiceContext, ProviderRequestContext, ProviderRuntimeState } from "../types.js";
 export declare const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
 export type CreateProviderChoiceContextOptions = {
     readonly providerId: string;

package/dist/runtime/choice.js

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
-import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token";
-import { ProviderError } from "../errors";
+import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token.js";
+import { isProviderError, ProviderError } from "../errors.js";
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
 const PRIMARY_CHOICE_TOKEN_KID = "v1";
 const MANAGED_CHOICE_TOKEN_VERSION = 1;
@@ -53,7 +53,7 @@ export function createProviderChoiceContext(options) {
         });
     }
     function parse(parseOptions) {
-        const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature,] = parseManagedChoiceTokenParts(parseOptions.token);
+        const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature] = parseManagedChoiceTokenParts(parseOptions.token);
         if (actualPrefix !== parseOptions.prefix ||
             tokenKid !== kid ||
             !encodedIv ||
@@ -68,13 +68,7 @@ export function createProviderChoiceContext(options) {
             purpose: parseOptions.purpose,
             kid: tokenKid,
         });
-        const signedBody = [
-            parseOptions.prefix,
-            tokenKid,
-            encodedIv,
-            encryptedPayload,
-            authTag,
-        ].join(".");
+        const signedBody = [parseOptions.prefix, tokenKid, encodedIv, encryptedPayload, authTag].join(".");
         assertManagedChoiceSignature({
             signedBody,
             signature,
@@ -117,13 +111,11 @@ export function createProviderChoiceContext(options) {
 export function createTestProviderChoiceContext(options) {
     return createProviderChoiceContext({
         ...options,
-        masterSecret: options.masterSecret ??
-            "apifuse-test-provider-runtime-choice-token-master-secret",
+        masterSecret: options.masterSecret ?? "apifuse-test-provider-runtime-choice-token-master-secret",
     });
 }
 function resolveChoiceMasterSecret(options) {
-    const configured = options.masterSecret ??
-        options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
+    const configured = options.masterSecret ?? options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
     const trimmed = configured?.trim();
     if (trimmed)
         return trimmed;
@@ -165,13 +157,7 @@ function encryptManagedChoiceToken(options) {
     ]).toString("base64url");
     const authTag = cipher.getAuthTag().toString("base64url");
     const encodedIv = iv.toString("base64url");
-    const signedBody = [
-        options.prefix,
-        options.kid,
-        encodedIv,
-        encryptedPayload,
-        authTag,
-    ].join(".");
+    const signedBody = [options.prefix, options.kid, encodedIv, encryptedPayload, authTag].join(".");
     const signature = createHmac("sha256", options.keys.signing)
         .update(signedBody)
         .digest("base64url");
@@ -223,7 +209,25 @@ async function parseServerStoredChoice(options) {
         storage,
         contextState: options.contextState,
     });
-    const record = await namespace.get(optionsStateKey(options.handle.state_id));
+    // Reading a server-stored choice back deserializes a persisted value. A
+    // corrupt/undecodable value would otherwise surface as a raw JSON.parse
+    // SyntaxError (or another unexpected throwable) that escapes the choice error
+    // taxonomy, gets masked as internal_error 500, and is treated as retryable by
+    // the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+    // Convert any non-branded throwable into a branded invalid_payload so it maps
+    // to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+    // ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+    // their category/retryable semantics are preserved.
+    let record;
+    try {
+        record = await namespace.get(optionsStateKey(options.handle.state_id));
+    }
+    catch (error) {
+        if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+            throw error;
+        }
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload could not be decoded.");
+    }
     if (!record) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload is missing.");
     }
@@ -345,9 +349,7 @@ function isManagedChoiceEnvelope(value) {
         typeof value.issued_at_ms === "number" &&
         "ttl_ms" in value &&
         typeof value.ttl_ms === "number" &&
-        (!("binding" in value) ||
-            value.binding === undefined ||
-            isChoiceBinding(value.binding)));
+        (!("binding" in value) || value.binding === undefined || isChoiceBinding(value.binding)));
 }
 function isChoicePayload(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -355,29 +357,23 @@ function isChoicePayload(value) {
 function isChoiceBinding(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
-    return ((!("connection_hash" in value) ||
-        typeof value.connection_hash === "string") &&
+    return ((!("connection_hash" in value) || typeof value.connection_hash === "string") &&
         (!("credential_hash" in value) || typeof value.credential_hash === "string"));
 }
 function assertManagedChoiceEnvelope(envelope, options) {
-    if (envelope.provider_id !== options.providerId ||
-        envelope.purpose !== options.purpose) {
+    if (envelope.provider_id !== options.providerId || envelope.purpose !== options.purpose) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token payload is invalid.");
     }
     assertFreshProviderChoiceIssuedAt(envelope.issued_at_ms, {
         // Clamp to the issuer's embedded TTL so a caller-supplied value cannot
         // silently extend token validity past the deadline the issuer intended.
-        ttlMs: options.ttlMs != null
-            ? Math.min(options.ttlMs, envelope.ttl_ms)
-            : envelope.ttl_ms,
+        ttlMs: options.ttlMs != null ? Math.min(options.ttlMs, envelope.ttl_ms) : envelope.ttl_ms,
         nowMs: options.nowMs,
         futureToleranceMs: options.futureToleranceMs,
     });
 }
 function createChoiceBinding(options) {
-    const connectionHash = options.options?.connection
-        ? hashRequiredConnection(options)
-        : undefined;
+    const connectionHash = options.options?.connection ? hashRequiredConnection(options) : undefined;
     const credentialHash = options.options?.credentialKeys?.length
         ? hashCredentialKeys(options)
         : undefined;

package/dist/runtime/credential.d.ts

@@ -1,4 +1,4 @@
-import type { AuthMode, CredentialContext } from "../types";
+import type { AuthMode, CredentialContext } from "../types.js";
 export interface CreateCredentialContextOptions {
     allowedKeys?: string[];
     mode?: AuthMode;

package/dist/runtime/credential.js

@@ -1,4 +1,4 @@
-import { CredentialModeError } from "../errors";
+import { CredentialModeError } from "../errors.js";
 function getAllowedKeys(allowedKeys, values) {
     if (allowedKeys) {
         return allowedKeys;

package/dist/runtime/env.d.ts

@@ -1,2 +1,2 @@
-import type { EnvContext } from "../types";
+import type { EnvContext } from "../types.js";
 export declare function createEnvContext(allowedKeys?: string[]): EnvContext;

package/dist/runtime/executor.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderContext, ProviderDefinition } from "../types";
+import type { ProviderContext, ProviderDefinition } from "../types.js";
 export declare function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean;
 /**
  * Execute a provider operation by calling its handler.

package/dist/runtime/executor.js

@@ -1,5 +1,6 @@
-import { ProviderError, SessionExpiredError } from "../errors";
-import { parseSchema } from "../schema";
+import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
+import { parseSchema } from "../schema.js";
+import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
     const kind = provider.operations[operationId]?.transport?.kind ?? "json";
     return kind !== "json";
@@ -23,6 +24,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }
+    // SDK-owned secret presence gate (single source of truth): declared
+    // `required: true` secrets are validated here, before input parsing and the
+    // handler, so every invocation path (serve /v1, self-test probes, perf,
+    // record) fails with the same structured MISSING_SECRET error instead of a
+    // handler-specific crash. Providers must not re-check presence locally.
+    assertRequiredSecretsPresent(provider, ctx.env);
     const validatedInput = await parseSchema(operation.input, input, `operations.${operationId}.input`);
     const execute = () => ctx.trace.span(`handler:${operationId}`, () => Promise.resolve(operation.handler(ctx, validatedInput)));
     let result;
@@ -39,7 +46,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
         // operation is safe to re-drive after refresh, which we signal by marking
         // the surfaced error retryable; non-idempotent operations (the default)
         // stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
-        if (error instanceof SessionExpiredError && operation.retryOnAuthRefresh) {
+        // Use the branded guard, not `instanceof`: a handler loaded through a
+        // duplicate/published SDK module can throw a correctly branded
+        // SessionExpiredError whose constructor identity differs from this
+        // executor's, which `instanceof` would miss — dropping the retryable
+        // upgrade and stranding an operation that opted into auth refresh.
+        if (isSessionExpiredError(error) && operation.retryOnAuthRefresh) {
             throw new SessionExpiredError(error.message, { retryable: true });
         }
         throw error;

package/dist/runtime/http.d.ts

@@ -1,5 +1,5 @@
-import type { ProxyResolutionOptions } from "../config/loader";
-import type { HttpClient, HttpRetrySummary } from "../types";
+import type { ProxyResolutionOptions } from "../config/loader.js";
+import type { HttpClient, HttpRetrySummary } from "../types.js";
 export type HttpClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
     userAgent?: string;