@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/dev.d.ts

@@ -1,7 +1,12 @@
+import type { ProviderEngine, ProviderEngineMode } from "./engine.js";
 import type { ProviderDefinition } from "./types.js";
 export interface DevServerOptions {
     port?: number;
     sessionDbPath?: string;
+    /** Override the default in-process engine attachment. */
+    engine?: ProviderEngine;
+    /** Explicit engine mode; `APIFUSE__ENGINE__MODE` outranks it when both are set. */
+    engineMode?: ProviderEngineMode;
 }
 export declare function createDevServer(provider: ProviderDefinition, options?: DevServerOptions): {
     start: () => void;

package/dist/dev.js

@@ -3,7 +3,14 @@ export function createDevServer(provider, options) {
     const port = options?.port ?? 3900;
     return {
         start: () => {
-            void serve(provider, { port });
+            // Local development has no Redis by default; handles (ADR-0012) need a
+            // state backend, so fall back to memory state when none is configured.
+            void serve(provider, {
+                port,
+                engine: options?.engine,
+                engineMode: options?.engineMode,
+                allowMemoryStateFallback: true,
+            });
             console.log(`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`);
             console.log(`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`);
             console.log(`[apifuse dev] Health: http://localhost:${port}/health`);

package/dist/engine.d.ts

@@ -0,0 +1,129 @@
+import type { HandleContext } from "./handle.js";
+import type { AuthContext, BrowserClient, CredentialContext, EnvContext, HttpClient, NativeContext, OcrContext, ProviderCache, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRequestContext, ProviderRuntimeState, ResolverContext, StealthClient, SttContext, TraceContext } from "./types.js";
+/** Versioned envelope protocol used by out-of-process engine transports. */
+export declare const PROVIDER_ENGINE_PROTOCOL_VERSION: "provider-engine.v1";
+/**
+ * Environment variable that selects how a provider process attaches its capability
+ * bindings. Engine-owned by prefix (`APIFUSE__ENGINE__*`): never declarable as a
+ * provider secret and never projected into `ctx.env`.
+ *
+ * Values are trimmed and case-folded; absent or blank means "unset". An
+ * unrecognized value is reported on the `provider_engine_mode` boot event and
+ * ignored — a deployment-authored typo must never turn into CrashLoopBackOff.
+ */
+export declare const PROVIDER_ENGINE_MODE_ENV = "APIFUSE__ENGINE__MODE";
+/**
+ * How a provider process attaches its capability bindings: `"in-process"` today,
+ * `"remote"` for the authenticated engine (ADR-0011).
+ *
+ * The union is intentionally open so further lanes (for example a provider hosted
+ * inside the engine) can be named without a breaking change. Unknown values are
+ * rejected at runtime, not by the type.
+ */
+export type ProviderEngineMode = "in-process" | "remote" | (string & {});
+/** Credential names owned by the engine and forbidden in provider declarations. */
+export declare const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__PROXY__SMARTPROXY_APP_KEY", "APIFUSE__PROXY__NODEMAVEN_USERNAME", "APIFUSE__PROXY__NODEMAVEN_PASSWORD"];
+export declare function isEngineOwnedProxyCredentialName(name: string): boolean;
+/** Hosted resolver credentials owned by the engine and never projected to providers. */
+export declare const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__RESOLVER__2CAPTCHA__API_KEY", "APIFUSE__RESOLVER__CAPSOLVER__API_KEY", "APIFUSE__RESOLVER__CAPMONSTER__API_KEY", "APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY"];
+/**
+ * Engine variable a provider-declared secret name resolves to, or `undefined` when the
+ * name is not an engine-owned resolver credential. Provider-scoped Hyper aliases
+ * (`APIFUSE__PROVIDER__<ID>__HYPER_API_KEY`, measured on zozotown) map to the shared key.
+ */
+export declare function engineOwnedResolverCredentialTarget(name: string): string | undefined;
+export declare function isEngineOwnedResolverCredentialName(name: string): boolean;
+/**
+ * Trace-export configuration owned by the engine and forbidden in provider
+ * declarations. The header variables carry collector credentials; the rest are
+ * engine deployment settings a provider has no reason to read.
+ */
+export declare const ENGINE_OWNED_TELEMETRY_ENV_NAMES: readonly ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_HEADERS", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_SERVICE_NAME", "OTEL_RESOURCE_ATTRIBUTES"];
+export declare function isEngineOwnedTelemetryEnvName(name: string): boolean;
+/**
+ * Hosted runtime settings the engine reads for OCR, STT, cache keying, and
+ * the CDP pool. Providers never own them: declarations are rejected
+ * and projections drop them, like the vendor credentials above.
+ */
+export declare const ENGINE_OWNED_RUNTIME_ENV_NAMES: readonly ["APIFUSE__STT__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__API_KEY", "APIFUSE__CLOUDFLARE__ACCOUNT_ID", "APIFUSE__CACHE__KEY_PEPPER"];
+export declare function isEngineOwnedRuntimeEnvName(name: string): boolean;
+/** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
+export declare function isEngineOwnedEnvName(name: string): boolean;
+/** Capture credentials in the engine host before constructing provider bindings. */
+export declare function readEngineProxyCredentials(environment?: Readonly<Record<string, string | undefined>>): Readonly<Record<string, string>>;
+/** Build the exact environment projection permitted to enter a provider runtime. */
+export declare function createProviderEnvironment(environment: Readonly<Record<string, string | undefined>>, declaredNames: readonly string[]): Readonly<Record<string, string>>;
+/**
+ * Request/response is the first remote transport lane. Stream and session
+ * handles are separate lanes so lifecycle-bearing capabilities are never
+ * disguised as ordinary JSON calls.
+ */
+export interface ProviderEngineTransport {
+    request<TResponse = unknown>(request: ProviderEngineRequest): Promise<TResponse>;
+    openStream?(request: ProviderEngineRequest): Promise<ReadableStream<Uint8Array>>;
+    openSession?(request: ProviderEngineRequest): Promise<ProviderEngineSession>;
+}
+export interface ProviderEngineRequest {
+    readonly version: typeof PROVIDER_ENGINE_PROTOCOL_VERSION;
+    readonly providerId: string;
+    readonly requestId: string;
+    readonly capability: ProviderCapabilityKey;
+    readonly method: string;
+    readonly payload: unknown;
+}
+export interface ProviderEngineSession {
+    request<TResponse = unknown>(method: string, payload: unknown): Promise<TResponse>;
+    close(): Promise<void>;
+}
+/** Capability implementations owned by the engine rather than provider code. */
+export interface ProviderEngineCapabilitySurface {
+    readonly http: HttpClient;
+    readonly browser: BrowserClient;
+    readonly stealth: StealthClient;
+    readonly stt: SttContext;
+    readonly ocr: OcrContext;
+    readonly resolver: ResolverContext;
+    readonly cache: ProviderCache;
+    readonly state: ProviderRuntimeState;
+}
+/** Engine-resident-only capabilities, kept separate from the portable surface. */
+export interface ProviderEngineResidentSurface {
+    readonly native: NativeContext;
+}
+export declare const PROVIDER_CAPABILITY_KEYS: readonly ["env", "credential", "http", "files", "native", "cache", "state", "stealth", "browser", "auth", "ocr", "stt", "resolver", "handle"];
+export type ProviderCapabilityKey = (typeof PROVIDER_CAPABILITY_KEYS)[number];
+export type ProviderEngineBindingCandidates = Partial<ProviderEngineCapabilitySurface & ProviderEngineResidentSurface & {
+    readonly env: EnvContext;
+    readonly credential: CredentialContext;
+    readonly files: ProviderFilesContext;
+    readonly auth: AuthContext;
+    readonly handle: HandleContext;
+}> & {
+    readonly request?: ProviderRequestContext;
+    readonly trace: TraceContext;
+};
+export interface ProviderEngineAttachmentInput {
+    readonly provider: ProviderDefinition;
+    readonly bindings: ProviderEngineBindingCandidates;
+}
+/** Attachment boundary shared by in-process development and remote RPC bridges. */
+export interface ProviderEngine {
+    /**
+     * Which attachment this engine performs. Lets the server report a truthful
+     * mode at boot and compare an explicit engine object against a requested
+     * `engineMode`; omit for opaque host engines (reported as `custom`).
+     */
+    readonly kind?: ProviderEngineMode;
+    attach<TDeclaration extends object = Record<string, unknown>>(input: ProviderEngineAttachmentInput): ProviderContext<TDeclaration>;
+}
+/**
+ * Local engine attachment; deployed bridges implement the same interface with RPC clients.
+ *
+ * ADR-0011 makes the authenticated remote engine the only attachment, so this one
+ * is scheduled for removal — but not deprecated yet: the remote client ships in a
+ * later release, and deprecating the only working constructor before its
+ * replacement exists would flag every current caller with no fix available. Until
+ * then it stays the default, and the server reports each in-process boot as
+ * `provider_engine_mode` with `deprecated: true`.
+ */
+export declare function createInProcessProviderEngine(): ProviderEngine;

package/dist/engine.js

@@ -0,0 +1,209 @@
+import { readDiagnosticEnv } from "./runtime/diagnostic-env.js";
+import { ProviderError } from "./errors.js";
+import { APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, } from "./runtime/resolver-config.js";
+import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME, } from "./runtime/otlp.js";
+/** Versioned envelope protocol used by out-of-process engine transports. */
+export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1";
+/**
+ * Environment variable that selects how a provider process attaches its capability
+ * bindings. Engine-owned by prefix (`APIFUSE__ENGINE__*`): never declarable as a
+ * provider secret and never projected into `ctx.env`.
+ *
+ * Values are trimmed and case-folded; absent or blank means "unset". An
+ * unrecognized value is reported on the `provider_engine_mode` boot event and
+ * ignored — a deployment-authored typo must never turn into CrashLoopBackOff.
+ */
+export const PROVIDER_ENGINE_MODE_ENV = "APIFUSE__ENGINE__MODE";
+/** Credential names owned by the engine and forbidden in provider declarations. */
+export const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES = [
+    "APIFUSE__PROXY__SMARTPROXY_APP_KEY",
+    "APIFUSE__PROXY__NODEMAVEN_USERNAME",
+    "APIFUSE__PROXY__NODEMAVEN_PASSWORD",
+];
+const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET = new Set(ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES);
+/**
+ * Environment names are compared case-insensitively: Windows resolves `otel_exporter_otlp_headers`
+ * to the same variable as `OTEL_EXPORTER_OTLP_HEADERS`, so a mixed-case alias must be treated as
+ * the engine-owned name it resolves to.
+ */
+function canonicalEnvName(name) {
+    return name.toUpperCase();
+}
+export function isEngineOwnedProxyCredentialName(name) {
+    return ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET.has(canonicalEnvName(name));
+}
+/** Hosted resolver credentials owned by the engine and never projected to providers. */
+export const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES = [
+    APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+    APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+    APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+    APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
+];
+const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET = new Set(ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES);
+/**
+ * Engine variable a provider-declared secret name resolves to, or `undefined` when the
+ * name is not an engine-owned resolver credential. Provider-scoped Hyper aliases
+ * (`APIFUSE__PROVIDER__<ID>__HYPER_API_KEY`, measured on zozotown) map to the shared key.
+ */
+export function engineOwnedResolverCredentialTarget(name) {
+    const canonical = canonicalEnvName(name);
+    if (ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET.has(canonical))
+        return canonical;
+    if (/^APIFUSE__PROVIDER__.+__HYPER_API_KEY$/u.test(canonical)) {
+        return APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY;
+    }
+    return undefined;
+}
+export function isEngineOwnedResolverCredentialName(name) {
+    return engineOwnedResolverCredentialTarget(name) !== undefined;
+}
+/**
+ * Trace-export configuration owned by the engine and forbidden in provider
+ * declarations. The header variables carry collector credentials; the rest are
+ * engine deployment settings a provider has no reason to read.
+ */
+export const ENGINE_OWNED_TELEMETRY_ENV_NAMES = [
+    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+    OTEL_EXPORTER_OTLP_ENDPOINT,
+    OTEL_EXPORTER_OTLP_TRACES_HEADERS,
+    OTEL_EXPORTER_OTLP_HEADERS,
+    OTEL_SERVICE_NAME,
+    OTEL_RESOURCE_ATTRIBUTES,
+];
+const ENGINE_OWNED_TELEMETRY_ENV_NAME_SET = new Set(ENGINE_OWNED_TELEMETRY_ENV_NAMES);
+export function isEngineOwnedTelemetryEnvName(name) {
+    return ENGINE_OWNED_TELEMETRY_ENV_NAME_SET.has(canonicalEnvName(name));
+}
+/** Engine control-plane configuration is never declarable or visible to provider code. */
+function isEngineOwnedEngineEnvName(name) {
+    return canonicalEnvName(name).startsWith("APIFUSE__ENGINE__");
+}
+/**
+ * Hosted runtime settings the engine reads for OCR, STT, cache keying, and
+ * the CDP pool. Providers never own them: declarations are rejected
+ * and projections drop them, like the vendor credentials above.
+ */
+export const ENGINE_OWNED_RUNTIME_ENV_NAMES = [
+    "APIFUSE__STT__CLOUDFLARE_API_TOKEN",
+    "APIFUSE__OCR__CLOUDFLARE_API_TOKEN",
+    "APIFUSE__OCR__API_KEY",
+    "APIFUSE__CLOUDFLARE__ACCOUNT_ID",
+    "APIFUSE__CACHE__KEY_PEPPER",
+];
+const ENGINE_OWNED_RUNTIME_ENV_NAME_SET = new Set(ENGINE_OWNED_RUNTIME_ENV_NAMES);
+/** CDP pool settings form a prefix family (`APIFUSE__CDP_POOL__URL` today); the whole prefix is engine-owned. */
+const ENGINE_OWNED_CDP_POOL_ENV_PREFIX = "APIFUSE__CDP_POOL__";
+export function isEngineOwnedRuntimeEnvName(name) {
+    const canonical = canonicalEnvName(name);
+    return (ENGINE_OWNED_RUNTIME_ENV_NAME_SET.has(canonical) ||
+        canonical.startsWith(ENGINE_OWNED_CDP_POOL_ENV_PREFIX));
+}
+/** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
+export function isEngineOwnedEnvName(name) {
+    return (isEngineOwnedEngineEnvName(name) ||
+        isEngineOwnedProxyCredentialName(name) ||
+        isEngineOwnedResolverCredentialName(name) ||
+        isEngineOwnedRuntimeEnvName(name) ||
+        isEngineOwnedTelemetryEnvName(name));
+}
+/** Capture credentials in the engine host before constructing provider bindings. */
+export function readEngineProxyCredentials(environment = process.env) {
+    return Object.fromEntries(ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES.flatMap((name) => {
+        const value = readDiagnosticEnv(name, environment)?.trim();
+        return value ? [[name, value]] : [];
+    }));
+}
+/** Build the exact environment projection permitted to enter a provider runtime. */
+export function createProviderEnvironment(environment, declaredNames) {
+    return Object.fromEntries(declaredNames.flatMap((name) => {
+        if (isEngineOwnedEnvName(name))
+            return [];
+        const value = readDiagnosticEnv(name, environment);
+        return value === undefined ? [] : [[name, value]];
+    }));
+}
+export const PROVIDER_CAPABILITY_KEYS = [
+    "env",
+    "credential",
+    "http",
+    "files",
+    "native",
+    "cache",
+    "state",
+    "stealth",
+    "browser",
+    "auth",
+    "ocr",
+    "stt",
+    "resolver",
+    "handle",
+];
+const CAPABILITY_KEY_SET = new Set(PROVIDER_CAPABILITY_KEYS);
+function declaresCapability(provider, capability) {
+    if (capability === "credential" && provider.auth?.mode === "platform-managed")
+        return true;
+    return Object.hasOwn(provider, capability) && provider[capability] !== undefined;
+}
+function attachmentError(provider, capability) {
+    return new ProviderError(`Provider engine could not attach declared capability "${capability}" for provider "${provider.id}"`, {
+        code: "PROVIDER_ENGINE_ATTACHMENT_FAILED",
+        details: { providerId: provider.id, capability },
+        fix: `Configure the engine binding for "${capability}" before starting the provider.`,
+    });
+}
+function undeclaredCapabilityError(provider, capability) {
+    return new ProviderError(`Provider "${provider.id}" accessed undeclared capability "${capability}"; add the "${capability}" declaration`, {
+        code: "PROVIDER_CAPABILITY_UNDECLARED",
+        details: { providerId: provider.id, capability },
+        fix: `Add ${capability}: {} to the provider declaration, or remove the access.`,
+    });
+}
+function attachInProcess(input) {
+    const { provider, bindings } = input;
+    if (provider.runtimeTarget === "vanilla" && declaresCapability(provider, "native")) {
+        throw new ProviderError(`Provider "${provider.id}" cannot attach capability "native" to runtime target "vanilla"; native requires an engine-resident runtime`, {
+            code: "PROVIDER_RUNTIME_CAPABILITY_CONFLICT",
+            details: { providerId: provider.id, capability: "native", runtimeTarget: "vanilla" },
+        });
+    }
+    const context = { trace: bindings.trace };
+    if (bindings.request !== undefined)
+        context.request = bindings.request;
+    for (const capability of PROVIDER_CAPABILITY_KEYS) {
+        if (!declaresCapability(provider, capability))
+            continue;
+        const binding = bindings[capability];
+        if (binding === undefined || binding === null)
+            throw attachmentError(provider, capability);
+        context[capability] = binding;
+    }
+    return new Proxy(context, {
+        get(target, property, receiver) {
+            if (typeof property === "string" &&
+                CAPABILITY_KEY_SET.has(property) &&
+                !declaresCapability(provider, property)) {
+                throw undeclaredCapabilityError(provider, property);
+            }
+            return Reflect.get(target, property, receiver);
+        },
+        has(target, property) {
+            if (typeof property === "string" && CAPABILITY_KEY_SET.has(property)) {
+                return declaresCapability(provider, property);
+            }
+            return Reflect.has(target, property);
+        },
+    });
+}
+/**
+ * Local engine attachment; deployed bridges implement the same interface with RPC clients.
+ *
+ * ADR-0011 makes the authenticated remote engine the only attachment, so this one
+ * is scheduled for removal — but not deprecated yet: the remote client ships in a
+ * later release, and deprecating the only working constructor before its
+ * replacement exists would flag every current caller with no fix available. Until
+ * then it stays the default, and the server reports each in-process boot as
+ * `provider_engine_mode` with `deprecated: true`.
+ */
+export function createInProcessProviderEngine() {
+    return { kind: "in-process", attach: attachInProcess };
+}

package/dist/error-observability.d.ts

@@ -0,0 +1,7 @@
+import { type ProviderErrorObservability } from "./errors.js";
+/**
+ * Extracts only own data properties from branded provider errors. In
+ * particular, descriptor reads reject options/observability accessors without
+ * invoking provider-controlled getters.
+ */
+export declare function safeProviderErrorObservability(error: unknown): ProviderErrorObservability | undefined;

package/dist/error-observability.js

@@ -0,0 +1,61 @@
+import { isProviderError } from "./errors.js";
+const PROVIDER_OBSERVABILITY_TOKEN_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+const PROVIDER_OBSERVABILITY_FINGERPRINT_PATTERN = /^[A-Fa-f0-9]{12}$/;
+const MAX_PROVIDER_OBSERVABILITY_MESSAGE_LENGTH = 10_000_000;
+/**
+ * Extracts only own data properties from branded provider errors. In
+ * particular, descriptor reads reject options/observability accessors without
+ * invoking provider-controlled getters.
+ */
+export function safeProviderErrorObservability(error) {
+    if (!isProviderError(error))
+        return undefined;
+    let candidate;
+    let reason;
+    let fingerprint;
+    let messageLength;
+    try {
+        const optionsDescriptor = Object.getOwnPropertyDescriptor(error, "options");
+        if (optionsDescriptor === undefined || !Object.hasOwn(optionsDescriptor, "value")) {
+            return undefined;
+        }
+        const options = optionsDescriptor.value;
+        if (options === null || typeof options !== "object" || Array.isArray(options)) {
+            return undefined;
+        }
+        const observabilityDescriptor = Object.getOwnPropertyDescriptor(options, "observability");
+        if (observabilityDescriptor === undefined || !Object.hasOwn(observabilityDescriptor, "value")) {
+            return undefined;
+        }
+        candidate = observabilityDescriptor.value;
+        if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+            return undefined;
+        }
+        const ownValue = (key) => {
+            const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+            return descriptor && Object.hasOwn(descriptor, "value") ? descriptor.value : undefined;
+        };
+        reason = ownValue("reason");
+        fingerprint = ownValue("fingerprint");
+        messageLength = ownValue("messageLength");
+    }
+    catch {
+        return undefined;
+    }
+    const safe = {
+        ...(typeof reason === "string" && PROVIDER_OBSERVABILITY_TOKEN_PATTERN.test(reason)
+            ? { reason }
+            : {}),
+        ...(typeof fingerprint === "string" &&
+            PROVIDER_OBSERVABILITY_FINGERPRINT_PATTERN.test(fingerprint)
+            ? { fingerprint }
+            : {}),
+        ...(typeof messageLength === "number" &&
+            Number.isInteger(messageLength) &&
+            messageLength >= 0 &&
+            messageLength <= MAX_PROVIDER_OBSERVABILITY_MESSAGE_LENGTH
+            ? { messageLength }
+            : {}),
+    };
+    return Object.keys(safe).length > 0 ? safe : undefined;
+}

package/dist/error-resolution.d.ts

@@ -0,0 +1,18 @@
+import type { ProviderErrorCategory } from "./observability.js";
+import type { ProviderErrorStatus } from "./types.js";
+export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
+export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;
+/** One registered upstream code: the status the SDK serves and who failed. */
+export type SdkUpstreamErrorCodeRegistration = {
+    readonly status: ProviderErrorStatus;
+    readonly category: ProviderErrorCategory;
+};
+export declare const SDK_UPSTREAM_ERROR_CODE_REGISTRY: ReadonlyMap<string, SdkUpstreamErrorCodeRegistration>;
+/**
+ * The category a registered upstream code carries when its `ProviderError`
+ * sets none. `undefined` for every other code, which keeps its existing
+ * default.
+ */
+export declare function registeredUpstreamErrorCategory(code: string | undefined): ProviderErrorCategory | undefined;
+export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;
+export declare const SDK_CANONICAL_ERROR_CODE_RETRYABILITY: ReadonlyMap<string, boolean>;