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

package/src/i18n/keys.ts

@@ -2,8 +2,55 @@ import type { ProviderLocaleKey } from "../types.js";
 
 export type { ProviderLocale, ProviderLocaleKey } from "../types.js";
 
-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: string, parent: string | undefined): boolean {
+	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: string): ProviderLocaleKey {
 	assertProviderLocaleKey(key);
@@ -11,13 +58,21 @@ export function providerLocaleKey(key: string): ProviderLocaleKey {
 }
 
 export function isProviderLocaleKey(value: unknown): value is ProviderLocaleKey {
-	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: unknown): asserts value is ProviderLocaleKey {
 	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)}`,
+			`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)}`,
 		);
 	}
 }
@@ -35,9 +90,28 @@ export function getProviderLocalePath(
 	key: ProviderLocaleKey | string,
 ): ProviderLocaleValue | undefined {
 	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: ProviderLocaleCatalog,
+	segments: readonly string[],
+): ProviderLocaleValue | undefined {
+	if (segments.length === 0) return undefined;
 	let cursor: unknown = catalog;
-	for (const segment of key.split(".")) {
-		if (!isRecord(cursor)) return undefined;
+	for (const segment of segments) {
+		if (!isRecord(cursor) || !Object.hasOwn(cursor, segment)) return undefined;
 		cursor = cursor[segment];
 	}
 	return isProviderLocaleValue(cursor) ? cursor : undefined;

package/src/index.ts

@@ -161,6 +161,19 @@ export {
 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,
@@ -228,6 +241,43 @@ export {
 	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,
@@ -368,7 +418,9 @@ export type {
 	HealthScheduleRandomization,
 	HealthJourneySmsContext,
 	HealthJourneyStep,
+	HttpAttemptContext,
 	HttpClient,
+	HttpHeadersFactory,
 	HttpMethod,
 	HttpRedirectFailureReason,
 	HttpRedirectPolicy,
@@ -466,6 +518,7 @@ export type {
 	ProviderRuntimeTarget,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
+	ProviderSecretIssuer,
 	ProviderStealthConfig,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
@@ -572,3 +625,22 @@ export {
 	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";