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

package/src/runtime/insights.ts

@@ -1,5 +1,5 @@
-import { computePercentile } from "./perf";
-import type { Span, SpanAttributeValue } from "./trace";
+import { computePercentile } from "./perf.js";
+import type { Span, SpanAttributeValue } from "./trace.js";
 
 export type InsightSeverity = "info" | "warning" | "error";
 
@@ -115,11 +115,7 @@ function parseHostname(url: string | undefined): string | undefined {
 	}
 }
 
-function makeInsight(
-	id: string,
-	severity: InsightSeverity,
-	result: InsightResult,
-): Insight {
+function makeInsight(id: string, severity: InsightSeverity, result: InsightResult): Insight {
 	return {
 		id,
 		severity,
@@ -266,8 +262,7 @@ function getDnsRepeatedCandidate(spans: Span[]): DnsHostInsight | null {
 		}
 
 		const avgDnsMs =
-			entry.dnsDurations.reduce((sum, value) => sum + value, 0) /
-			entry.dnsDurations.length;
+			entry.dnsDurations.reduce((sum, value) => sum + value, 0) / entry.dnsDurations.length;
 		const reuseRate = entry.reuseCount / entry.totalCount;
 
 		if (avgDnsMs > DNS_WARN_MS && reuseRate < 0.2) {
@@ -301,9 +296,7 @@ function getDnsRepeatedInsight(spans: Span[]): InsightResult {
 
 function getProxyOverheadInsight(spans: Span[]): InsightResult {
 	const requestSpans = spans.filter(isRequestSpan);
-	const proxiedDurations = requestSpans
-		.filter(hasProxy)
-		.map((span) => span.duration_ms);
+	const proxiedDurations = requestSpans.filter(hasProxy).map((span) => span.duration_ms);
 	const directDurations = requestSpans
 		.filter((span) => !hasProxy(span))
 		.map((span) => span.duration_ms);
@@ -316,11 +309,8 @@ function getProxyOverheadInsight(spans: Span[]): InsightResult {
 	}
 
 	const proxyAvg =
-		proxiedDurations.reduce((sum, value) => sum + value, 0) /
-		proxiedDurations.length;
-	const directAvg =
-		directDurations.reduce((sum, value) => sum + value, 0) /
-		directDurations.length;
+		proxiedDurations.reduce((sum, value) => sum + value, 0) / proxiedDurations.length;
+	const directAvg = directDurations.reduce((sum, value) => sum + value, 0) / directDurations.length;
 
 	if (directAvg > 0 && proxyAvg >= directAvg * 2) {
 		return {
@@ -345,9 +335,7 @@ function getBrowserIdleInsight(spans: Span[]): InsightResult {
 				return waitMs;
 			}
 
-			return span.name.toLowerCase().includes("wait")
-				? span.duration_ms
-				: undefined;
+			return span.name.toLowerCase().includes("wait") ? span.duration_ms : undefined;
 		})
 		.filter((value): value is number => value !== undefined);
 
@@ -374,9 +362,7 @@ function getBrowserIdleInsight(spans: Span[]): InsightResult {
 }
 
 function getSessionExpiryInsight(spans: Span[]): InsightResult {
-	const refreshCount = spans.filter(
-		(span) => span.name === "credential.refresh",
-	).length;
+	const refreshCount = spans.filter((span) => span.name === "credential.refresh").length;
 	const requestCount = spans.filter(isRequestSpan).length;
 
 	if (requestCount === 0) {
@@ -415,36 +401,12 @@ export function generateInsights(spans: Span[]): Insight[] {
 	const sessionExpiry = getSessionExpiryInsight(spans);
 
 	const rules = [
-		makeInsight(
-			"tls_reuse_failure",
-			tlsReuse.triggered ? "warning" : "info",
-			tlsReuse,
-		),
-		makeInsight(
-			"slow_transform",
-			slowTransform.triggered ? "warning" : "info",
-			slowTransform,
-		),
-		makeInsight(
-			"large_response",
-			largeResponse.triggered ? "warning" : "info",
-			largeResponse,
-		),
-		makeInsight(
-			"dns_repeated",
-			dnsRepeated.triggered ? "warning" : "info",
-			dnsRepeated,
-		),
-		makeInsight(
-			"proxy_overhead",
-			proxyOverhead.triggered ? "warning" : "info",
-			proxyOverhead,
-		),
-		makeInsight(
-			"browser_idle",
-			browserIdle.triggered ? "warning" : "info",
-			browserIdle,
-		),
+		makeInsight("tls_reuse_failure", tlsReuse.triggered ? "warning" : "info", tlsReuse),
+		makeInsight("slow_transform", slowTransform.triggered ? "warning" : "info", slowTransform),
+		makeInsight("large_response", largeResponse.triggered ? "warning" : "info", largeResponse),
+		makeInsight("dns_repeated", dnsRepeated.triggered ? "warning" : "info", dnsRepeated),
+		makeInsight("proxy_overhead", proxyOverhead.triggered ? "warning" : "info", proxyOverhead),
+		makeInsight("browser_idle", browserIdle.triggered ? "warning" : "info", browserIdle),
 		makeInsight(
 			"session_expiry_frequent",
 			sessionExpiry.triggered ? "warning" : "info",

package/src/runtime/instrumentation.ts

@@ -1,34 +1,20 @@
-import type { ProviderContext } from "../types";
+import type { ProviderContext } from "../types.js";
 import {
 	type CreateTraceContextOptions,
 	createTraceContext,
 	getTraceRecorder,
 	type TraceContext,
-} from "./trace";
+} from "./trace.js";
 
 export interface InstrumentationOptions extends CreateTraceContextOptions {}
 
-export type InstrumentedProviderContext<T extends ProviderContext> = Omit<
-	T,
-	"trace"
-> & {
+export type InstrumentedProviderContext<T extends ProviderContext> = Omit<T, "trace"> & {
 	trace: TraceContext;
 };
 
-type InstrumentedNamespace =
-	| "http"
-	| "stealth"
-	| "browser"
-	| "session"
-	| "state";
-
-const BROWSER_PAGE_METHODS = new Set([
-	"goto",
-	"fill",
-	"click",
-	"type",
-	"waitForSelector",
-]);
+type InstrumentedNamespace = "http" | "stealth" | "browser" | "session" | "state";
+
+const BROWSER_PAGE_METHODS = new Set(["goto", "fill", "click", "type", "waitForSelector"]);
 
 function getErrorStatus(error: unknown): number | undefined {
 	if (
@@ -59,10 +45,7 @@ function getResponseDuration(result: unknown): number | undefined {
 	return undefined;
 }
 
-function getResponseStatus(
-	namespace: InstrumentedNamespace,
-	result: unknown,
-): number | undefined {
+function getResponseStatus(namespace: InstrumentedNamespace, result: unknown): number | undefined {
 	if (
 		typeof result === "object" &&
 		result !== null &&
@@ -111,8 +94,7 @@ function getMethod(
 	}
 
 	if (namespace === "stealth") {
-		const options =
-			typeof args[1] === "object" && args[1] !== null ? args[1] : undefined;
+		const options = typeof args[1] === "object" && args[1] !== null ? args[1] : undefined;
 		if (options && "method" in options && typeof options.method === "string") {
 			return options.method.toUpperCase();
 		}
@@ -133,9 +115,7 @@ function buildSpanAttributes(
 	const attributes: Record<string, string | number | boolean> = {};
 	const url = getUrl(namespace, args, result);
 	const method = getMethod(namespace, methodName, args);
-	const status = error
-		? getErrorStatus(error)
-		: getResponseStatus(namespace, result);
+	const status = error ? getErrorStatus(error) : getResponseStatus(namespace, result);
 	const duration = error ? undefined : getResponseDuration(result);
 
 	if (url) {
@@ -146,10 +126,7 @@ function buildSpanAttributes(
 		attributes.method = method;
 	}
 
-	if (
-		status !== undefined &&
-		(namespace === "http" || namespace === "stealth")
-	) {
+	if (status !== undefined && (namespace === "http" || namespace === "stealth")) {
 		attributes.status = status;
 	}
 
@@ -241,10 +218,8 @@ function wrapPage<T extends object>(page: T, trace: TraceContext): T {
 						return result;
 					},
 					{
-						onSuccess: () =>
-							getBrowserPageAttributes(methodName, args, elapsedMs),
-						onError: (error) =>
-							getBrowserPageAttributes(methodName, args, undefined, error),
+						onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
+						onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
 					},
 				);
 			};
@@ -310,18 +285,14 @@ function wrapNamespace<T extends object>(
 									namespaceTarget &&
 									typeof namespaceTarget === "object" &&
 									"engine" in namespaceTarget &&
-									typeof (namespaceTarget as { engine?: unknown }).engine ===
-										"string"
+									typeof (namespaceTarget as { engine?: unknown }).engine === "string"
 								) {
-									attributes.engine = (
-										namespaceTarget as { engine: string }
-									).engine;
+									attributes.engine = (namespaceTarget as { engine: string }).engine;
 								}
 
 								return attributes;
 							},
-							onError: (error) =>
-								getBrowserPageAttributes("newPage", args, undefined, error),
+							onError: (error) => getBrowserPageAttributes("newPage", args, undefined, error),
 						},
 					);
 				};
@@ -348,10 +319,8 @@ function wrapNamespace<T extends object>(
 							return result;
 						},
 						{
-							onSuccess: () =>
-								getBrowserPageAttributes(methodName, args, elapsedMs),
-							onError: (error) =>
-								getBrowserPageAttributes(methodName, args, undefined, error),
+							onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
+							onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
 						},
 					);
 				};
@@ -365,16 +334,8 @@ function wrapNamespace<T extends object>(
 					`${namespace}.${methodName}`,
 					() => Reflect.apply(value, namespaceTarget, args),
 					{
-						onSuccess: (result) =>
-							buildSpanAttributes(namespace, methodName, args, result),
-						onError: (error) =>
-							buildSpanAttributes(
-								namespace,
-								methodName,
-								args,
-								undefined,
-								error,
-							),
+						onSuccess: (result) => buildSpanAttributes(namespace, methodName, args, result),
+						onError: (error) => buildSpanAttributes(namespace, methodName, args, undefined, error),
 					},
 				);
 

package/src/runtime/keyring.ts

@@ -1,4 +1,4 @@
-import { ConfigurationError, decodeMasterKey } from "./key-derivation";
+import { ConfigurationError, decodeMasterKey } from "./key-derivation.js";
 
 export interface KeyRingOptions {
 	env: NodeJS.ProcessEnv;
@@ -16,16 +16,12 @@ export interface KeyRing {
 	accept(version: number): KeyRingEntry;
 	activeWriter(): KeyRingEntry;
 	versions(): number[];
-	purgeVersion(
-		version: number,
-		isActiveInStore: (v: number) => Promise<boolean>,
-	): Promise<void>;
+	purgeVersion(version: number, isActiveInStore: (v: number) => Promise<boolean>): Promise<void>;
 }
 
 const DEFAULT_KEY_PREFIX = "APIFUSE__KEYRING__MASTER_KEY_V";
 const DEFAULT_ACCEPT_LIST_VAR = "APIFUSE__KEYRING__MASTER_KEY_ACCEPT_LIST";
-const DEFAULT_WRITER_VERSION_VAR =
-	"APIFUSE__KEYRING__MASTER_KEY_WRITER_VERSION";
+const DEFAULT_WRITER_VERSION_VAR = "APIFUSE__KEYRING__MASTER_KEY_WRITER_VERSION";
 
 function parseAcceptList(raw: string | undefined): number[] {
 	if (!raw || raw.trim().length === 0) {
@@ -56,19 +52,14 @@ function parseAcceptList(raw: string | undefined): number[] {
 	return versions;
 }
 
-function parseWriterVersion(
-	raw: string | undefined,
-	acceptList: number[],
-): number {
+function parseWriterVersion(raw: string | undefined, acceptList: number[]): number {
 	if (!raw || raw.trim().length === 0) {
 		throw new ConfigurationError("writer-version env var is empty");
 	}
 	const trimmed = raw.trim();
 	const v = Number.parseInt(trimmed, 10);
 	if (!Number.isInteger(v) || v <= 0 || String(v) !== trimmed) {
-		throw new ConfigurationError(
-			`writer-version "${trimmed}" is not a positive integer`,
-		);
+		throw new ConfigurationError(`writer-version "${trimmed}" is not a positive integer`);
 	}
 	if (!acceptList.includes(v)) {
 		throw new ConfigurationError(
@@ -90,8 +81,7 @@ export function loadKeyRing(options: KeyRingOptions): KeyRing {
 	const env = options.env;
 	const prefix = options.envPrefix ?? DEFAULT_KEY_PREFIX;
 	const acceptListVar = options.acceptListVar ?? DEFAULT_ACCEPT_LIST_VAR;
-	const writerVersionVar =
-		options.writerVersionVar ?? DEFAULT_WRITER_VERSION_VAR;
+	const writerVersionVar = options.writerVersionVar ?? DEFAULT_WRITER_VERSION_VAR;
 
 	const acceptList = parseAcceptList(env[acceptListVar]);
 	const writerVersion = parseWriterVersion(env[writerVersionVar], acceptList);
@@ -100,9 +90,7 @@ export function loadKeyRing(options: KeyRingOptions): KeyRing {
 	for (const version of acceptList) {
 		const raw = env[`${prefix}${version}`];
 		if (raw === undefined) {
-			throw new ConfigurationError(
-				`${prefix}${version} is missing (listed in accept-list)`,
-			);
+			throw new ConfigurationError(`${prefix}${version} is missing (listed in accept-list)`);
 		}
 		const key = decodeMasterKey(raw);
 		entries.set(version, { version, key });

package/src/runtime/namespace.ts

@@ -1,6 +1,6 @@
 import { createHmac } from "node:crypto";
 
-import { deriveSubkey } from "./key-derivation";
+import { deriveSubkey } from "./key-derivation.js";
 
 const HMAC_HEX_LENGTH = 16;
 
@@ -22,12 +22,7 @@ export function deriveContextNamespace(
 		throw new Error("sessionId is empty");
 	}
 
-	const subkey = deriveSubkey(
-		masterSecret,
-		providerId,
-		"context-namespace",
-		keyVersion,
-	);
+	const subkey = deriveSubkey(masterSecret, providerId, "context-namespace", keyVersion);
 	const hmac = createHmac("sha256", subkey).update(providerId).digest("hex");
 	return `provider:${hmac.slice(0, HMAC_HEX_LENGTH)}:${sessionId}`;
 }

package/src/runtime/otlp.ts

@@ -1,4 +1,4 @@
-import type { TraceSpan } from "../types";
+import type { TraceSpan } from "../types.js";
 
 export interface OTLPExportOptions {
 	endpoint: string;
@@ -32,10 +32,7 @@ function createTraceId(signature: string): string {
 	return traceId;
 }
 
-function normalizeHexId(
-	value: string | undefined,
-	length: number,
-): string | undefined {
+function normalizeHexId(value: string | undefined, length: number): string | undefined {
 	if (!value) {
 		return undefined;
 	}
@@ -44,9 +41,7 @@ function normalizeHexId(
 	return normalized.padStart(length, "0").slice(-length);
 }
 
-function toAttributeValue(
-	value: unknown,
-): Record<string, string | number | boolean> {
+function toAttributeValue(value: unknown): Record<string, string | number | boolean> {
 	if (typeof value === "string") {
 		return { stringValue: value };
 	}
@@ -92,20 +87,16 @@ export function spansToOTLP(
 		}>;
 	}>;
 } {
-	const traceId = createTraceId(
-		createBatchSignature(spans, resourceAttributes),
-	);
+	const traceId = createTraceId(createBatchSignature(spans, resourceAttributes));
 
 	return {
 		resourceSpans: [
 			{
 				resource: {
-					attributes: Object.entries(resourceAttributes ?? {}).map(
-						([key, value]) => ({
-							key,
-							value: { stringValue: value },
-						}),
-					),
+					attributes: Object.entries(resourceAttributes ?? {}).map(([key, value]) => ({
+						key,
+						value: { stringValue: value },
+					})),
 				},
 				scopeSpans: [
 					{
@@ -122,12 +113,10 @@ export function spansToOTLP(
 							startTimeUnixNano: String(span.startedAt * 1_000_000),
 							endTimeUnixNano: String(span.endedAt * 1_000_000),
 							status: { code: span.status === "ok" ? 1 : 2 },
-							attributes: Object.entries(span.attributes ?? {}).map(
-								([key, value]) => ({
-									key,
-									value: toAttributeValue(value),
-								}),
-							),
+							attributes: Object.entries(span.attributes ?? {}).map(([key, value]) => ({
+								key,
+								value: toAttributeValue(value),
+							})),
 						})),
 					},
 				],

package/src/runtime/perf.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 
 export type PerfStats = {
 	p50: number;

package/src/runtime/provider.ts

@@ -1,15 +1,10 @@
-import type { ProviderDefinition } from "../types";
+import type { ProviderDefinition } from "../types.js";
 
-export function getProviderBaseUrl(
-	provider: ProviderDefinition,
-): string | undefined {
-	const operations = Object.values(
-		provider.operations as Record<string, unknown>,
-	);
+export function getProviderBaseUrl(provider: ProviderDefinition): string | undefined {
+	const operations = Object.values(provider.operations as Record<string, unknown>);
 
 	for (const operation of operations) {
-		const baseUrl = (operation as { upstream?: { baseUrl?: unknown } }).upstream
-			?.baseUrl;
+		const baseUrl = (operation as { upstream?: { baseUrl?: unknown } }).upstream?.baseUrl;
 
 		if (typeof baseUrl === "string" && baseUrl.length > 0) {
 			return baseUrl;

package/src/runtime/proxy-errors.ts

@@ -1,4 +1,4 @@
-import { TransportError } from "../errors";
+import { TransportError } from "../errors.js";
 
 export const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
 export const PROXY_AUTH_IP_DENIED_MESSAGE =
@@ -39,9 +39,7 @@ export function isProxyEdgeAuthRejectedMessage(message: string): boolean {
 	return PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message);
 }
 
-export function createProxyEdgeAuthRejectedError(
-	cause?: Error,
-): TransportError {
+export function createProxyEdgeAuthRejectedError(cause?: Error): TransportError {
 	return new TransportError(PROXY_EDGE_AUTH_REJECTED_MESSAGE, {
 		code: PROXY_EDGE_AUTH_REJECTED_CODE,
 		cause,
@@ -52,10 +50,7 @@ export function isProxyPoolStaleStatus(status: number): boolean {
 	return PROXY_POOL_STALE_STATUS_CODES.has(status);
 }
 
-export function isProxyEdgeTlsRejectedResponse(
-	status: number,
-	evidence: string,
-): boolean {
+export function isProxyEdgeTlsRejectedResponse(status: number, evidence: string): boolean {
 	return (
 		PROXY_EDGE_TLS_REJECTED_STATUS_CODES.has(status) &&
 		PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN.test(evidence)
@@ -67,10 +62,7 @@ export function isProxyPoolStaleMessage(message: string): boolean {
 }
 
 export function isProxyPoolRefreshableError(error: unknown): boolean {
-	if (
-		error instanceof TransportError &&
-		error.code === PROXY_AUTH_IP_DENIED_CODE
-	) {
+	if (error instanceof TransportError && error.code === PROXY_AUTH_IP_DENIED_CODE) {
 		return false;
 	}
 
@@ -89,39 +81,26 @@ export function isProxyPoolRefreshableError(error: unknown): boolean {
 		cause instanceof Error ? cause.message : "",
 	].join(" ");
 	return (
-		PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) ||
-		PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message)
+		PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) || PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message)
 	);
 }
 
 export const isProxyPoolStaleError = isProxyPoolRefreshableError;
 
-export function createProxyPoolStaleError(
-	status: number,
-	cause?: Error,
-): TransportError {
-	return new TransportError(
-		`Proxy provider pool failed with status ${status}`,
-		{
-			code: PROXY_POOL_STALE_CODE,
-			status,
-			cause,
-		},
-	);
+export function createProxyPoolStaleError(status: number, cause?: Error): TransportError {
+	return new TransportError(`Proxy provider pool failed with status ${status}`, {
+		code: PROXY_POOL_STALE_CODE,
+		status,
+		cause,
+	});
 }
 
-export function createProxyEdgeTlsRejectedError(
-	status: number,
-	cause?: Error,
-): TransportError {
-	return new TransportError(
-		`Proxy edge TLS request was rejected with status ${status}`,
-		{
-			code: PROXY_EDGE_TLS_REJECTED_CODE,
-			status,
-			cause,
-		},
-	);
+export function createProxyEdgeTlsRejectedError(status: number, cause?: Error): TransportError {
+	return new TransportError(`Proxy edge TLS request was rejected with status ${status}`, {
+		code: PROXY_EDGE_TLS_REJECTED_CODE,
+		status,
+		cause,
+	});
 }
 
 export function createProxyPoolExhaustedError(cause?: Error): TransportError {

package/src/runtime/proxy-retry-policy.ts

@@ -1,12 +1,12 @@
-import { ProviderError, TransportError } from "../errors";
-import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types";
+import { ProviderError, TransportError } from "../errors.js";
+import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types.js";
 import {
 	HttpRetryAfterPolicy,
 	HttpRetryDelayStrategy,
 	HttpRetryJitter,
 	HttpRetryPreset,
 	HttpRetryUnsafeMethodPolicy,
-} from "../types";
+} from "../types.js";
 
 export type NormalizedProxyTransportRetryOptions = Required<
 	Pick<