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

package/dist/i18n/error-messages.js

@@ -0,0 +1,192 @@
+import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import { getProviderLocaleSegments, isProviderLocaleKey, } from "./keys.js";
+/** Locales the SDK negotiates for client-facing provider text. */
+export const PROVIDER_ERROR_LOCALES = ["en", "ko", "ja"];
+/** Locale used when the caller asks for nothing the provider catalog covers. */
+export const DEFAULT_PROVIDER_ERROR_LOCALE = "en";
+/** Catalog namespace for derived `errors.<code>.message` / `errors.<code>.fix` lookups. */
+export const PROVIDER_ERROR_CATALOG_NAMESPACE = "errors";
+/** Per-value cap applied to every interpolated param, before substitution. */
+export const MAX_INTERPOLATED_PARAM_LENGTH = 200;
+/** Cap applied to a rendered localized message or fix. */
+export const MAX_LOCALIZED_ERROR_TEXT_LENGTH = 2_000;
+const TRUNCATION_SUFFIX = "…";
+// One pass, three alternatives: `{{` and `}}` are the literal-brace escapes and
+// `{name}` is a substitution. Named groups are deliberately not used so the
+// callback can distinguish an escape from a substitution by the matched text.
+const PLACEHOLDER_PATTERN = /\{\{|\}\}|\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+// Markup openers are removed outright rather than entity-escaped: the envelope
+// is plain text, so an escaped `&lt;` would be as wrong for a terminal as a raw
+// `<` is for an HTML surface. The `&` rule only fires in front of an
+// entity-shaped run, so ordinary prose ("Tom & Jerry") survives while
+// `&lt;script&gt;` cannot be revived by a consumer that decodes entities.
+const MARKUP_OPENER_PATTERN = /[<>`]/g;
+const HTML_ENTITY_AMPERSAND_PATTERN = /&(?=#?[0-9A-Za-z]{1,32};)/g;
+function isProviderErrorLocale(value) {
+    return PROVIDER_ERROR_LOCALES.some((locale) => locale === value);
+}
+/**
+ * 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 function providerLocaleFromAcceptLanguage(header) {
+    if (typeof header !== "string" || header.length === 0)
+        return undefined;
+    const ranges = [];
+    for (const [position, token] of header.split(",").entries()) {
+        const [rangeText, ...parameters] = token.split(";");
+        const primary = rangeText?.trim().split("-")[0]?.toLowerCase();
+        if (!primary)
+            continue;
+        const quality = parseQualityValue(parameters);
+        if (quality <= 0)
+            continue;
+        ranges.push({ primary, quality, position });
+    }
+    // Stable by construction: equal qualities keep header order.
+    ranges.sort((left, right) => left.quality === right.quality ? left.position - right.position : right.quality - left.quality);
+    for (const range of ranges) {
+        if (isProviderErrorLocale(range.primary))
+            return range.primary;
+    }
+    return undefined;
+}
+function parseQualityValue(parameters) {
+    for (const parameter of parameters) {
+        const [name, value] = parameter.split("=");
+        if (name?.trim().toLowerCase() !== "q")
+            continue;
+        const quality = Number.parseFloat(value?.trim() ?? "");
+        // A malformed `q` is not a rejection; RFC 9110 treats the range as
+        // fully acceptable when no usable quality is present.
+        if (!Number.isFinite(quality))
+            return 1;
+        return Math.min(Math.max(quality, 0), 1);
+    }
+    return 1;
+}
+/** Reads `accept-language` from a case-insensitive header record. */
+export function acceptLanguageHeaderValue(headers) {
+    if (!headers)
+        return undefined;
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === "accept-language" && typeof value === "string")
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Picks the first supported locale across header sources, in precedence order,
+ * falling back to {@link DEFAULT_PROVIDER_ERROR_LOCALE}.
+ */
+export function resolveProviderErrorLocale(...headerValues) {
+    for (const value of headerValues) {
+        const locale = providerLocaleFromAcceptLanguage(value);
+        if (locale)
+            return locale;
+    }
+    return DEFAULT_PROVIDER_ERROR_LOCALE;
+}
+function truncateText(value, limit) {
+    return value.length <= limit ? value : `${value.slice(0, limit)}${TRUNCATION_SUFFIX}`;
+}
+/**
+ * Renders one param value as substitution text, or `undefined` when the value
+ * cannot be substituted (absent, non-finite, or not a string/number).
+ */
+export function interpolatedParamText(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? String(value) : undefined;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    // sanitizeDiagnosticText scrubs credentials and encodes control, bidi and
+    // line-separator characters; the markup pass closes the HTML/markdown hole
+    // it deliberately leaves open for log text.
+    const scrubbed = sanitizeDiagnosticText(value)
+        .replace(MARKUP_OPENER_PATTERN, "")
+        .replace(HTML_ENTITY_AMPERSAND_PATTERN, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    return truncateText(scrubbed, MAX_INTERPOLATED_PARAM_LENGTH);
+}
+/**
+ * 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 function interpolateProviderErrorText(template, params) {
+    const rendered = template.replace(PLACEHOLDER_PATTERN, (match, name) => {
+        if (match === "{{")
+            return "{";
+        if (match === "}}")
+            return "}";
+        if (name === undefined)
+            return match;
+        const substitution = interpolatedParamText(params && Object.hasOwn(params, name) ? params[name] : undefined);
+        return substitution ?? match;
+    });
+    return truncateText(rendered, MAX_LOCALIZED_ERROR_TEXT_LENGTH);
+}
+function asCatalogText(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function readCatalogSegments(catalogs, segments, locale, fallbackLocale) {
+    return (asCatalogText(getProviderLocaleSegments(catalogs[locale] ?? {}, segments)) ??
+        asCatalogText(getProviderLocaleSegments(catalogs[fallbackLocale] ?? {}, segments)));
+}
+/**
+ * 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 function localizeProviderErrorText(options) {
+    const { catalogs } = options;
+    if (!catalogs)
+        return options.fallback;
+    const fallbackLocale = options.fallbackLocale ?? DEFAULT_PROVIDER_ERROR_LOCALE;
+    for (const candidate of options.candidates) {
+        const segments = candidateSegments(candidate);
+        if (!segments)
+            continue;
+        try {
+            const template = readCatalogSegments(catalogs, segments, options.locale, fallbackLocale);
+            if (template === undefined)
+                continue;
+            return interpolateProviderErrorText(template, options.params);
+        }
+        catch {
+            // A hostile catalog or params object (throwing getters, exotic proxies)
+            // must not turn a provider error into a masked 500. Fall through to the
+            // next candidate and ultimately to the English literal.
+        }
+    }
+    return options.fallback;
+}
+function candidateSegments(candidate) {
+    if (candidate.kind === "key") {
+        // Explicit keys must satisfy the dot-path grammar; a malformed key is a
+        // miss, never a throw at envelope time.
+        return isProviderLocaleKey(candidate.key) ? candidate.key.split(".") : undefined;
+    }
+    if (typeof candidate.code !== "string" || candidate.code.length === 0)
+        return undefined;
+    return [PROVIDER_ERROR_CATALOG_NAMESPACE, candidate.code, candidate.field];
+}
+/** The `errors.<code>.<field>` dot path this SDK derives for an undeclared key. */
+export function derivedProviderErrorCatalogPath(code, field) {
+    return `${PROVIDER_ERROR_CATALOG_NAMESPACE}.${code}.${field}`;
+}

package/dist/i18n/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./catalog.js";
+export * from "./error-messages.js";
 export * from "./keys.js";

package/dist/i18n/index.js

@@ -1,2 +1,3 @@
 export * from "./catalog.js";
+export * from "./error-messages.js";
 export * from "./keys.js";

package/dist/i18n/keys.d.ts

@@ -5,6 +5,18 @@ export declare function isProviderLocaleKey(value: unknown): value is ProviderLo
 export declare function assertProviderLocaleKey(value: unknown): asserts value is ProviderLocaleKey;
 export declare function qualifyProviderLocaleKey(providerId: string, key: ProviderLocaleKey | string): string;
 export declare function getProviderLocalePath(catalog: ProviderLocaleCatalog, key: ProviderLocaleKey | string): ProviderLocaleValue | undefined;
+/**
+ * Reads a catalog path from raw segments, bypassing the dot-path grammar.
+ *
+ * Derived error-message lookups address the catalog by the thrown error code
+ * (`errors.<code>.message`). The grammar now accepts the code shapes the SDK
+ * registers and the fleet throws, but `code` is provider data: a provider may
+ * throw anything, and an unusual code must still resolve its catalog entry
+ * rather than be dropped as malformed. Own properties only: a
+ * `__proto__`/`constructor` segment must read as a miss, not as the prototype
+ * chain.
+ */
+export declare function getProviderLocaleSegments(catalog: ProviderLocaleCatalog, segments: readonly string[]): ProviderLocaleValue | undefined;
 export type ProviderLocaleValue = string | readonly string[];
 export type ProviderLocaleCatalog = Record<string, unknown>;
 export declare function isProviderLocaleValue(value: unknown): value is ProviderLocaleValue;

package/dist/i18n/keys.js

@@ -1,14 +1,69 @@
-const PROVIDER_LOCALE_KEY_RE = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*|\.[0-9]+)*$/;
+/**
+ * An ordinary catalog name segment: camelCase, ASCII only.
+ *
+ * `[A-Z][a-z0-9]+` forces at least one character after each hump, so a
+ * screaming acronym (`errorsURL`) is not silently read as camelCase.
+ */
+const NAME_SEGMENT_RE = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*$/;
+/** An array-index segment, e.g. the `0` in `meta.tags.0`. */
+const INDEX_SEGMENT_RE = /^[0-9]+$/;
+/**
+ * An error-code segment: the thrown `code` used verbatim as a catalog key.
+ *
+ * Single-case underscore words only — `UPSTREAM_SCHEMA_ERROR`, `BLOCKED`,
+ * `reauth_required` — matching the shape the SDK registers and the fleet
+ * throws (a census of 91 provider repos found 224 distinct codes: 213
+ * SCREAMING_SNAKE, 11 lower_snake, none mixed-case, none with a leading digit).
+ * A leading letter is mandatory, so no error code can be spelled like the
+ * numeric array-index form and the two segment kinds stay disjoint.
+ * The lower_snake arm requires an underscore because a bare lowercase word is
+ * already a {@link NAME_SEGMENT_RE} segment.
+ */
+const ERROR_CODE_SEGMENT_RE = /^(?:[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*|[a-z][a-z0-9]*(?:_[a-z0-9]+)+)$/;
+/**
+ * The only parent under which an error-code segment is legal.
+ *
+ * Must stay equal to `PROVIDER_ERROR_CATALOG_NAMESPACE` in `error-messages.ts`
+ * (the derived-path test in `keys.test.ts` fails if they drift). Anchoring the
+ * code vocabulary to this one parent is what keeps the grammar from degrading
+ * into "any identifier anywhere": everywhere else a segment is still camelCase
+ * or an array index.
+ */
+const ERROR_CODE_PARENT_SEGMENT = "errors";
+/**
+ * Validates one segment in position.
+ *
+ * `parent` is the preceding segment, or `undefined` for the first segment. The
+ * first segment is always a plain name: catalogs are rooted in SDK-owned
+ * namespaces (`meta`, `operations`, `auth`, `errors`), never in an index or a
+ * code.
+ */
+function isValidProviderLocaleSegment(segment, parent) {
+    if (parent === undefined)
+        return NAME_SEGMENT_RE.test(segment);
+    if (NAME_SEGMENT_RE.test(segment) || INDEX_SEGMENT_RE.test(segment))
+        return true;
+    return parent === ERROR_CODE_PARENT_SEGMENT && ERROR_CODE_SEGMENT_RE.test(segment);
+}
 export function providerLocaleKey(key) {
     assertProviderLocaleKey(key);
     return key;
 }
 export function isProviderLocaleKey(value) {
-    return typeof value === "string" && PROVIDER_LOCALE_KEY_RE.test(value);
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    const segments = value.split(".");
+    for (const [index, segment] of segments.entries()) {
+        // `split(".")` yields "" for an empty segment ("a..b", ".a", "a."), which
+        // no segment pattern matches, so those stay rejected.
+        if (!isValidProviderLocaleSegment(segment, index === 0 ? undefined : segments[index - 1]))
+            return false;
+    }
+    return true;
 }
 export function assertProviderLocaleKey(value) {
     if (!isProviderLocaleKey(value)) {
-        throw new Error(`Provider locale key must be a dot path such as "meta.description" or "operations.search.description"; received ${JSON.stringify(value)}`);
+        throw new Error(`Provider locale key must be a camelCase dot path such as "meta.description" or "operations.search.description", optionally naming an error code under "${ERROR_CODE_PARENT_SEGMENT}." as in "errors.UPSTREAM_SCHEMA_ERROR.message"; received ${JSON.stringify(value)}`);
     }
 }
 export function qualifyProviderLocaleKey(providerId, key) {
@@ -17,9 +72,25 @@ export function qualifyProviderLocaleKey(providerId, key) {
 }
 export function getProviderLocalePath(catalog, key) {
     assertProviderLocaleKey(key);
+    return getProviderLocaleSegments(catalog, key.split("."));
+}
+/**
+ * Reads a catalog path from raw segments, bypassing the dot-path grammar.
+ *
+ * Derived error-message lookups address the catalog by the thrown error code
+ * (`errors.<code>.message`). The grammar now accepts the code shapes the SDK
+ * registers and the fleet throws, but `code` is provider data: a provider may
+ * throw anything, and an unusual code must still resolve its catalog entry
+ * rather than be dropped as malformed. Own properties only: a
+ * `__proto__`/`constructor` segment must read as a miss, not as the prototype
+ * chain.
+ */
+export function getProviderLocaleSegments(catalog, segments) {
+    if (segments.length === 0)
+        return undefined;
     let cursor = catalog;
-    for (const segment of key.split(".")) {
-        if (!isRecord(cursor))
+    for (const segment of segments) {
+        if (!isRecord(cursor) || !Object.hasOwn(cursor, segment))
             return undefined;
         cursor = cursor[segment];
     }

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export { type CreateCredentialContextOptions, createCredentialContext, } from ".
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
+export { OcrTelemetryCollector, bindOcrTelemetry, type OcrTelemetryBackend, type OcrTelemetryEngine, type OcrTelemetryErrorCode, type OcrTelemetryEvent, type OcrTelemetryFinishReason, type OcrTelemetryHeaderPayload, type OcrTelemetryLogPayload, type OcrTelemetryModel, type OcrTelemetrySink, } from "./runtime/ocr-telemetry.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesizer, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesisInput, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
@@ -37,6 +38,9 @@ export type { ProxyTelemetryHeaderPayload, ProxyHash, ProxyTelemetryLogPayload,
 export { RequestTelemetry, closedEnum, type ClosedEnum, type GatewayIngestible, type RequestTelemetryLogPayload, type SpanIndex, type TelemetryContributor, type TelemetryKey, type TenantNeutral, } from "./runtime/request-telemetry.js";
 export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
 export { ResolverTelemetryCollector, type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverAttemptSample, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryHeaderPayload, type ResolverTelemetryIdentitySource, type ResolverTelemetryLogPayload, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "./runtime/resolver-telemetry.js";
+export { StealthTelemetryCollector, type StealthTelemetryAttemptEvent, type StealthTelemetryAttemptKind, type StealthTelemetryAttemptSample, type StealthTelemetryDiagnostics, type StealthTelemetryErrorCode, type StealthTelemetryHeaderPayload, type StealthTelemetryLogPayload, type StealthTelemetryRequestClass, type StealthTelemetrySbsdEvent, type StealthTelemetrySbsdOutcome, type StealthTelemetrySink, } from "./runtime/stealth-telemetry.js";
+export { SttTelemetryCollector, bindSttTelemetry, type SttTelemetryBackend, type SttTelemetryEngine, type SttTelemetryModel, type SttTelemetryErrorCode, type SttTelemetryEvent, type SttTelemetryHeaderPayload, type SttTelemetryLogPayload, type SttTelemetrySink, } from "./runtime/stt-telemetry.js";
+export { BrowserTelemetryCollector, type BrowserTelemetryErrorCode, type BrowserTelemetryHeaderPayload, type BrowserTelemetryLogPayload, type BrowserTelemetryPoolAcquireOutcome, type BrowserTelemetrySink, type BrowserTelemetrySampleName, type BrowserTelemetryEngine, } from "./runtime/browser-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
@@ -51,7 +55,7 @@ export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, AP
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ProviderErrorCauseFrame, type ServeOptions, serve, } from "./server/serve.js";
 export { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, listStealthProfiles, } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthChallengeClassification, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpAttemptContext, HttpClient, HttpHeadersFactory, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderSecretIssuer, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthChallengeClassification, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";
@@ -59,3 +63,5 @@ export * from "./utils/text.js";
 export * from "./utils/transform.js";
 export { HttpTelemetryCollector, type HttpTelemetrySink, type HttpTelemetryRequestSink, type HttpAttemptTelemetryEvent, type HttpAttemptSample, type HttpTelemetryErrorCode, type HttpTelemetryRetryPayload, type HttpTelemetryLogPayload, type HttpTelemetryHeaderPayload, } from "./runtime/http-telemetry.js";
 export { NativeTelemetryCollector, type NativeAttemptSample, type NativeConnectTelemetryEvent, type NativeLifecycleTelemetryEvent, type NativeTelemetryDiagnostics, type NativeTelemetryErrorCode, type NativeTelemetryHeaderPayload, type NativeTelemetryKind, type NativeTelemetryLifecycleKind, type NativeTelemetryLogPayload, type NativeTelemetryOutcome, type NativeTelemetrySink, type NativeTelemetryVendorSkipReason, type NativeVendorSkipTelemetryEvent, } from "./runtime/native-telemetry.js";
+export { CacheTelemetryCollector, type CacheTelemetryHeaderPayload, type CacheTelemetryLogPayload, type CacheTelemetrySample, type CacheTelemetrySink, type CacheTelemetrySource, } from "./runtime/cache-telemetry.js";
+export { StateTelemetryCollector, instrumentProviderRuntimeState, type StateTelemetryBackend, type StateTelemetryHeaderPayload, type StateTelemetryLogPayload, type StateTelemetryOperation, type StateTelemetrySample, type StateTelemetrySink, type StateTelemetryViolation, } from "./runtime/state-telemetry.js";

package/dist/index.js

@@ -23,6 +23,7 @@ export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
+export { OcrTelemetryCollector, bindOcrTelemetry, } from "./runtime/ocr-telemetry.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
@@ -30,6 +31,9 @@ export { getProviderBaseUrl } from "./runtime/provider.js";
 export { RequestTelemetry, closedEnum, } from "./runtime/request-telemetry.js";
 export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
 export { ResolverTelemetryCollector, } from "./runtime/resolver-telemetry.js";
+export { StealthTelemetryCollector, } from "./runtime/stealth-telemetry.js";
+export { SttTelemetryCollector, bindSttTelemetry, } from "./runtime/stt-telemetry.js";
+export { BrowserTelemetryCollector, } from "./runtime/browser-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
@@ -48,3 +52,5 @@ export * from "./utils/text.js";
 export * from "./utils/transform.js";
 export { HttpTelemetryCollector, } from "./runtime/http-telemetry.js";
 export { NativeTelemetryCollector, } from "./runtime/native-telemetry.js";
+export { CacheTelemetryCollector, } from "./runtime/cache-telemetry.js";
+export { StateTelemetryCollector, instrumentProviderRuntimeState, } from "./runtime/state-telemetry.js";

package/dist/lint.d.ts

@@ -1,3 +1,4 @@
+import { type ProviderLocaleCatalog } from "./i18n/keys.js";
 import type { OperationApprovalPolicy, OperationRiskClass } from "./types.js";
 type AuthModeLike = "none" | "platform-managed" | "credentials" | "oauth2" | "oauth2_proxied" | "api-key";
 type ProviderAuthLike = {
@@ -60,6 +61,11 @@ export declare function lintProvider(provider: {
     };
     authFlowSource?: string;
     providerSourceFiles?: Record<string, string>;
+    /**
+     * The provider's `locales/en.json`, injected by `apifuse check`. Error
+     * message localization rules are skipped when it is absent.
+     */
+    localeCatalogEn?: ProviderLocaleCatalog;
     operations?: Record<string, {
         descriptionKey?: string;
         whenToUseKeys?: readonly string[];
@@ -74,6 +80,10 @@ export declare function lintProvider(provider: {
         source?: string;
         errorCodes?: ReadonlyArray<{
             code: string;
+            status?: number;
+            retryable?: boolean;
+            messageKey?: string;
+            fixKey?: string;
         }>;
     }>;
     meta?: {