@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.63

package/dist/cli/migrate-provider-shape.d.ts

@@ -24,7 +24,11 @@ export type ProviderShapeKind =
 "single-phase-default-export"
 /** `const p = defineProvider({ ..., operations }); export default p;` */
  | "single-phase-variable-export"
-/** `const p = defineProvider({ ..., operations }); export default { ...p, deployment };` */
+/**
+ * `const p = defineProvider({ ..., operations }); export default { ...p, extra };`
+ * — extras stay on the spread export; a `deployment` extra is a legacy
+ * surface that `apifuse migrate-deployment` hoists into the declaration.
+ */
  | "single-phase-variable-spread-export"
 /** Already `const b = defineProvider(...); export default b({ operations })` */
  | "two-phase";

package/dist/cli/migrate-provider-shape.js

@@ -218,7 +218,7 @@ function defaultExportCallsBuilder(exportAssignment, declarationCall) {
  * resolves to a builder-call result. Covers the three migrated layouts —
  * `export default buildProvider({...})`, an intermediate
  * `const provider = buildProvider({...}); export default provider;`, and the
- * spread export `export default { ...provider, deployment }` over such a
+ * spread export `export default { ...provider, ...extras }` over such a
  * binding. Without the latter two, re-running the transform on its own
  * spread-shape output reports "ambiguous" instead of "unchanged", which
  * breaks idempotency for repeated fan-out runs.
@@ -376,7 +376,9 @@ function rewriteDefaultExport(source, exportAssignment, shape, builderName, oper
         ];
     }
     // Spread export: re-introduce the provider binding so the extra properties
-    // (currently `deployment`) still spread over a built provider.
+    // (e.g. `healthAccountSeedInputs`, or a legacy `deployment` that
+    // `apifuse migrate-deployment` later hoists) still spread over a built
+    // provider.
     const providerName = shape.variableName ?? "provider";
     const extras = shape.spreadExportExtras ?? "";
     const rebuilt = extras.length > 0

package/dist/cli/resolver-runtime.d.ts

@@ -0,0 +1,21 @@
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import type { ProviderCache, ProviderDefinition, ResolverContext } from "../types.js";
+export interface CliResolverRuntime {
+    readonly resolver: ResolverContext;
+    /** Per-context sink; `toLogPayload()` is the `resolver` sibling of the server request log. */
+    readonly resolverTelemetry: ResolverTelemetryCollector;
+    /**
+     * Extend the collector's redaction with values learned after construction (request-scoped
+     * `sensitiveParams` the recorder captures); the collector redacts at record time, before it
+     * truncates, so values must be registered before the vendor call that may echo them.
+     */
+    readonly registerSensitiveValues: (values: readonly string[]) => void;
+}
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export declare function createCliResolverRuntime(provider: ProviderDefinition, cache: ProviderCache): CliResolverRuntime;

package/dist/cli/resolver-runtime.js

@@ -0,0 +1,31 @@
+import { compileProcessDiagnosticSensitiveValues, createDiagnosticRedactor, } from "../runtime/diagnostic-redactor.js";
+import { createResolverClientFromEnv, createUnsupportedResolverClient, } from "../runtime/resolver.js";
+import { createResolverRuntimeOptions, resolveNativeProxyPolicy, } from "../runtime/resolver-runtime-options.js";
+import { ResolverTelemetryCollector } from "../runtime/resolver-telemetry.js";
+import { collectStaticDiagnosticSensitiveValues } from "../server/sensitive-values.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+/**
+ * Resolver chain for the CLI helper contexts (`apifuse record`, the `apifuse dev` helper), built
+ * like a server request scope: engine-owned solver keys, the CDP pool URL, and the resolver
+ * timeout come from the process environment, the runtime options come from the shared builder,
+ * and every vendor invocation lands in a collector redacted with the provider's static sensitive
+ * inventory. A CLI context has no server-owned identity scope and no proxy telemetry.
+ */
+export function createCliResolverRuntime(provider, cache) {
+    const sensitiveValues = createDiagnosticRedactor([], compileProcessDiagnosticSensitiveValues(collectStaticDiagnosticSensitiveValues(provider)));
+    const resolverTelemetry = new ResolverTelemetryCollector({ redact: sensitiveValues.redact });
+    const registerSensitiveValues = (values) => sensitiveValues.add(values);
+    if (!provider.resolver) {
+        return {
+            resolver: createUnsupportedResolverClient("Provider does not declare resolver capability"),
+            resolverTelemetry,
+            registerSensitiveValues,
+        };
+    }
+    const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+    return {
+        resolver: createResolverClientFromEnv(provider.resolver, process.env, createResolverRuntimeOptions(provider, cache, undefined, resolveNativeProxyPolicy(provider), { upstream: { proxy: provider.proxy } }, stealthProfile, resolverTelemetry)),
+        resolverTelemetry,
+        registerSensitiveValues,
+    };
+}

package/dist/define.d.ts

@@ -54,6 +54,9 @@ export interface ProviderDeclaration {
      * 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.
+     *
+     * This is the only authored deployment surface (no standalone
+     * `deploy.ts`); declare only the fields that differ from the profile.
      */
     deployment?: ProviderDeploymentOverrides;
     /** Declares the HTTP capability binding. A bare object states use without configuration. */

package/dist/define.js

@@ -636,6 +636,11 @@ function validateProviderImplementationShape(config) {
 }
 function validateProviderProxy(config) {
     for (const secret of config.secrets ?? []) {
+        if (secret.issuer !== undefined &&
+            secret.issuer !== "apifuse" &&
+            secret.issuer !== "contributor") {
+            throw new ValidationError(`Provider "${config.id}" secret "${secret.name}" has invalid issuer "${String(secret.issuer)}"`, { fix: `Set issuer to "apifuse" or "contributor", or omit it.` });
+        }
         const engineName = engineOwnedResolverCredentialTarget(secret.name);
         if (engineName !== undefined) {
             throw new ValidationError(`Provider "${config.id}" cannot declare engine-owned resolver credential "${secret.name}"`, {

package/dist/dev.d.ts

@@ -1,10 +1,12 @@
-import type { ProviderEngine } from "./engine.js";
+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

@@ -5,7 +5,12 @@ export function createDevServer(provider, options) {
         start: () => {
             // 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, allowMemoryStateFallback: true });
+            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

@@ -2,6 +2,25 @@ 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;
@@ -89,7 +108,22 @@ export interface ProviderEngineAttachmentInput {
 }
 /** 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. */
+/**
+ * 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

@@ -4,6 +4,16 @@ import { APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__AP
 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",
@@ -184,7 +194,16 @@ function attachInProcess(input) {
         },
     });
 }
-/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+/**
+ * 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 { attach: attachInProcess };
+    return { kind: "in-process", attach: attachInProcess };
 }

package/dist/error-resolution.d.ts

@@ -2,3 +2,4 @@ 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>;
 export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;
+export declare const SDK_CANONICAL_ERROR_CODE_RETRYABILITY: ReadonlyMap<string, boolean>;

package/dist/error-resolution.js

@@ -18,6 +18,14 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "refresh_not_supported",
     "RUNTIME_UNSUPPORTED",
     "PROVIDER_STATE_UNSUPPORTED",
+    // Engine attachment (ADR-0011). Registered here so an engine failure is served
+    // as a known SDK code instead of raising a false
+    // `unregistered_provider_error_code` signal on a 500.
+    "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+    "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+    "PROVIDER_ENGINE_UNAVAILABLE",
+    "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+    "PROVIDER_EGRESS_DENIED",
     "HANDLE_INVALID",
     "HANDLE_NOT_FOUND",
     "HANDLE_EXPIRED",
@@ -57,6 +65,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "http_redirect_missing_location",
     "http_redirect_loop",
     "transport_invalid_url",
+    "http_header_factory_failed",
     "EGRESS_LEASE_INVALID",
     "EGRESS_LEASE_BINDING_INVALID",
     "EGRESS_LEASE_KEY_MISSING",
@@ -84,6 +93,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
     "STATEFUL_FORWARDING_REQUEST_FAILED",
     "STATEFUL_FORWARDING_CONTEXT_MISSING",
+    "STATEFUL_FORWARDING_CONTEXT_INVALID",
     "STATEFUL_FORWARDING_BAD_RESPONSE",
     "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
     "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
@@ -144,9 +154,53 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES = new Map([
     ["HANDLE_BUSY", 409],
     ["UPSTREAM_ERROR", 502],
     ["BLOCKED", 502],
+    // Fleet-consensus provider codes. These are thrown by provider code, not
+    // by the SDK, so they are registered here (status mapping) and not in
+    // SDK_RUNTIME_OWNED_ERROR_CODES: an operation-declared status still wins,
+    // exactly as it does for UPSTREAM_ERROR and BLOCKED above. Registering
+    // them stops the fleet from re-declaring the same three rows on every
+    // operation, and stops an undeclared throw from being served as 500.
+    //
+    // A platform-managed upstream service key the upstream refuses. With
+    // `auth.mode: "platform-managed"` the caller holds no credential, so 401
+    // ("re-authenticate") tells the caller to do something it cannot do, and
+    // 502 ("upstream is sick") promises a recovery that will never come. It is
+    // a deployment/config defect — the same class as MISSING_SECRET above,
+    // which is already an explicit 400 for that reason.
+    ["UPSTREAM_AUTH_ERROR", 400],
+    // The upstream changed its response shape and the provider cannot
+    // normalize it. 502 because the fault is upstream of us, non-retryable
+    // because a retry returns the same broken payload.
+    ["UPSTREAM_SCHEMA_ERROR", 502],
+    // Caller-side bad input rejected by the provider. The minority spellings
+    // (INVALID_INPUT / VALIDATION_ERROR / BAD_REQUEST) are deliberately not
+    // registered: they migrate to this spelling on the contract track, and
+    // registering them here would freeze the divergence.
+    ["INVALID_REQUEST", 400],
     ["OCR_UNAVAILABLE", 503],
     ["UNSUPPORTED_OCR_BACKEND", 503],
     ["STT_UNAVAILABLE", 503],
     ["UNSUPPORTED_STT_BACKEND", 503],
     ["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+    // The engine is reachable-in-principle but not now: retryable, so the
+    // caller may retry once the engine recovers. Authentication, protocol
+    // mismatch, an unsupported mode and denied egress stay unmapped (500) and
+    // non-retryable: they are deployment or provider faults that no caller
+    // retry can clear, and a retryable 5xx there would turn one bad rollout
+    // into gateway-driven load.
+    ["PROVIDER_ENGINE_UNAVAILABLE", 503],
+]);
+// Canonical retryability for the fleet-consensus codes registered above.
+//
+// Runtime retryability still resolves as `instance option ?? declared ??
+// false`, so this map changes no served response: an undeclared throw already
+// defaults to false, which is what every entry here says. It exists so the
+// authoring lint can tell a provider that its declared `retryable` contradicts
+// the registered meaning of the code, instead of the fleet quietly shipping two
+// answers for the same code. Only codes whose retryability was fixed as part of
+// registration belong here — do not backfill opinions the SDK never made.
+export const SDK_CANONICAL_ERROR_CODE_RETRYABILITY = new Map([
+    ["UPSTREAM_AUTH_ERROR", false],
+    ["UPSTREAM_SCHEMA_ERROR", false],
+    ["INVALID_REQUEST", false],
 ]);

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
+import type { ProviderErrorMessageParams } from "./i18n/error-messages.js";
 import type { ProviderErrorCategory } from "./observability.js";
-import type { HttpRedirectFailureReason } from "./types.js";
+import type { HttpRedirectFailureReason, ProviderLocaleKeyInput } from "./types.js";
 export type ProviderErrorOptions = {
     fix?: string;
     code?: string;
@@ -9,6 +10,25 @@ export type ProviderErrorOptions = {
     retryable?: boolean;
     /** Provider-authored, bounded metadata safe for operational logs and error headers. */
     observability?: ProviderErrorObservability;
+    /**
+     * Locale catalog key for the client-facing `message`, e.g.
+     * `"errors.upstreamSchema.message"`. Resolved at serve time against the
+     * provider's `locales/{en,ko,ja}.json` with the caller's `Accept-Language`,
+     * falling back to `en` and then to the positional `message`.
+     *
+     * The positional `message` stays English: it is what `error.message`, cause
+     * frames, logs and OTLP attributes carry. Only the response envelope is
+     * localized.
+     */
+    messageKey?: ProviderLocaleKeyInput;
+    /** Locale catalog key for the client-facing `fix`. Same resolution as {@link ProviderErrorOptions.messageKey}. */
+    fixKey?: ProviderLocaleKeyInput;
+    /**
+     * Values substituted into `{name}` placeholders of the resolved text.
+     * Strings and finite numbers only; string values are scrubbed and length
+     * capped before substitution because upstream text routinely lands here.
+     */
+    params?: ProviderErrorMessageParams;
 };
 /**
  * Provider-authored error diagnostics whose runtime values are validated before emission.
@@ -33,6 +53,24 @@ export declare class ProviderError extends Error {
 export declare class SDKError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export declare class ProviderEngineProtocolVersionError extends SDKError {
+    readonly receivedVersion: unknown;
+    readonly expectedVersion: string;
+    constructor(receivedVersion: unknown, expectedVersion: string);
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export declare class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message?: string, options?: ProviderErrorOptions);
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export declare class ProviderEngineUnavailableError extends SDKError {
+    constructor(message?: string, cause?: Error);
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export declare class ProviderEgressDeniedError extends ProviderError {
+    constructor(message: string, details?: unknown);
+}
 /** Raised when persisted stealth cookies use a store version this SDK cannot read. */
 export declare class StealthCookieStoreVersionError extends SDKError {
     readonly version: unknown;

package/dist/errors.js

@@ -59,6 +59,56 @@ export class SDKError extends ProviderError {
         this.name = "SDKError";
     }
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export class ProviderEngineProtocolVersionError extends SDKError {
+    receivedVersion;
+    expectedVersion;
+    constructor(receivedVersion, expectedVersion) {
+        super(`Provider engine protocol version mismatch: expected ${expectedVersion}, received ${String(receivedVersion)}`, {
+            code: "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+            details: { receivedVersion, expectedVersion },
+            fix: "Update @apifuse/provider-sdk or use a compatible APIFuse provider engine.",
+        });
+        this.receivedVersion = receivedVersion;
+        this.expectedVersion = expectedVersion;
+        this.name = "ProviderEngineProtocolVersionError";
+    }
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message = "Provider engine authentication failed", options) {
+        super(message, {
+            code: "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+            fix: "Set APIFUSE__ENGINE__API_KEY to the workspace API key from your APIFuse bounty dashboard.",
+            ...options,
+        });
+        this.name = "ProviderEngineAuthenticationError";
+    }
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export class ProviderEngineUnavailableError extends SDKError {
+    constructor(message = "The remote APIFuse provider engine is unavailable", cause) {
+        super(message, {
+            code: "PROVIDER_ENGINE_UNAVAILABLE",
+            retryable: true,
+            fix: "Check network access and the provider engine endpoint, then retry.",
+            ...(cause ? { cause } : {}),
+        });
+        this.name = "ProviderEngineUnavailableError";
+    }
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export class ProviderEgressDeniedError extends ProviderError {
+    constructor(message, details) {
+        super(message, {
+            code: "PROVIDER_EGRESS_DENIED",
+            retryable: false,
+            details,
+            fix: "Use a host in the provider's pinned allowedHosts declaration, or request a trusted pin update.",
+        });
+        this.name = "ProviderEgressDeniedError";
+    }
+}
 /** Raised when persisted stealth cookies use a store version this SDK cannot read. */
 export class StealthCookieStoreVersionError extends SDKError {
     version;

package/dist/i18n/error-messages.d.ts

@@ -0,0 +1,86 @@
+import type { ProviderLocaleCatalogMap } from "./catalog.js";
+import { type ProviderLocale } from "./keys.js";
+/**
+ * Values interpolated into a localized provider error message or fix.
+ *
+ * Strings and finite numbers only. String values are treated as untrusted
+ * (upstream bodies frequently end up here), so they are scrubbed and capped by
+ * {@link interpolateProviderErrorText} before substitution.
+ */
+export type ProviderErrorMessageParams = Readonly<Record<string, string | number>>;
+/** Locales the SDK negotiates for client-facing provider text. */
+export declare const PROVIDER_ERROR_LOCALES: readonly ["en", "ko", "ja"];
+/** Locale used when the caller asks for nothing the provider catalog covers. */
+export declare const DEFAULT_PROVIDER_ERROR_LOCALE = "en";
+/** Catalog namespace for derived `errors.<code>.message` / `errors.<code>.fix` lookups. */
+export declare const PROVIDER_ERROR_CATALOG_NAMESPACE = "errors";
+/** Per-value cap applied to every interpolated param, before substitution. */
+export declare const MAX_INTERPOLATED_PARAM_LENGTH = 200;
+/** Cap applied to a rendered localized message or fix. */
+export declare const MAX_LOCALIZED_ERROR_TEXT_LENGTH = 2000;
+/**
+ * Negotiates an `Accept-Language` header against {@link PROVIDER_ERROR_LOCALES}.
+ *
+ * Quality values are honoured (`ko;q=0.1, ja;q=0.9` selects `ja`) and `q=0`
+ * means "not acceptable". Ranges are matched on the primary subtag, so `ko-KR`
+ * selects `ko`. Returns `undefined` when the header is absent or names no
+ * supported locale, so callers can consult a lower-precedence source before
+ * defaulting.
+ */
+export declare function providerLocaleFromAcceptLanguage(header: string | null | undefined): ProviderLocale | undefined;
+/** Reads `accept-language` from a case-insensitive header record. */
+export declare function acceptLanguageHeaderValue(headers: Readonly<Record<string, unknown>> | undefined): string | undefined;
+/**
+ * Picks the first supported locale across header sources, in precedence order,
+ * falling back to {@link DEFAULT_PROVIDER_ERROR_LOCALE}.
+ */
+export declare function resolveProviderErrorLocale(...headerValues: readonly (string | null | undefined)[]): ProviderLocale;
+/**
+ * Renders one param value as substitution text, or `undefined` when the value
+ * cannot be substituted (absent, non-finite, or not a string/number).
+ */
+export declare function interpolatedParamText(value: unknown): string | undefined;
+/**
+ * Substitutes `{name}` placeholders in a catalog template.
+ *
+ * - `{{` and `}}` are the literal `{` and `}` escapes.
+ * - A placeholder with no usable param is left verbatim, so an authoring gap is
+ *   visible in the response instead of silently deleting text.
+ * - Substituted text is never rescanned, so a param value containing `{other}`
+ *   cannot trigger a second round of interpolation.
+ */
+export declare function interpolateProviderErrorText(template: string, params?: ProviderErrorMessageParams): string;
+/** A key candidate considered by {@link localizeProviderErrorText}, in priority order. */
+export type ProviderErrorTextCandidate = 
+/** An explicit dot-path key from a throw site or an `errorCodes[]` declaration. */
+{
+    readonly kind: "key";
+    readonly key: string | undefined;
+}
+/** The `errors.<code>.<field>` convention; `code` is used verbatim as a segment. */
+ | {
+    readonly kind: "derived";
+    readonly code: string | undefined;
+    readonly field: string;
+};
+export interface LocalizeProviderErrorTextOptions {
+    readonly catalogs?: ProviderLocaleCatalogMap;
+    readonly locale: ProviderLocale;
+    readonly fallbackLocale?: ProviderLocale;
+    readonly candidates: readonly ProviderErrorTextCandidate[];
+    readonly params?: ProviderErrorMessageParams;
+    /** Literal text returned when no candidate resolves. May be `undefined` for `fix`. */
+    readonly fallback: string | undefined;
+}
+/**
+ * Resolves client-facing error text against the provider locale catalogs.
+ *
+ * Candidates are tried in order and each one is resolved in the caller's locale
+ * before the `en` catalog, so a more specific key always beats a more specific
+ * locale. Nothing here throws: a malformed key, an absent catalog, a
+ * non-string catalog value and a missing key all fall through to the next
+ * candidate and ultimately to `fallback`.
+ */
+export declare function localizeProviderErrorText(options: LocalizeProviderErrorTextOptions): string | undefined;
+/** The `errors.<code>.<field>` dot path this SDK derives for an undeclared key. */
+export declare function derivedProviderErrorCatalogPath(code: string, field: "message" | "fix"): string;