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

package/src/i18n/catalog.ts

@@ -191,6 +191,28 @@ export function localizeAuthTurn(
 	};
 }
 
+/**
+ * Markers that indicate a locale value was scaffolded but never translated.
+ *
+ * ASCII tokens are matched case-sensitively as whole `\w` tokens so ordinary
+ * prose such as "todo list" or identifiers like "TBDx" are not flagged. Locale
+ * tags such as `[ko]` are matched literally (the brackets are the boundary), and
+ * the Korean/Japanese phrases are matched as-is since CJK text has no `\b`.
+ */
+const PROVIDER_LOCALE_PLACEHOLDER_PATTERNS: readonly RegExp[] = [
+	/\b(?:TODO|FIXME|TBD|TRANSLATE)\b/,
+	/\[(?:en|ko|ja)\]/i,
+	/번역\s*필요/,
+	/翻訳が必要/,
+];
+
+function isProviderLocalePlaceholderText(text: string): boolean {
+	if (text.trim().length === 0) {
+		return true;
+	}
+	return PROVIDER_LOCALE_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text));
+}
+
 export function validateProviderLocaleCatalogs(options: {
 	catalogs: ProviderLocaleCatalogMap;
 	requiredLocales: readonly ProviderLocale[];
@@ -239,7 +261,7 @@ export function validateProviderLocaleCatalogs(options: {
 				continue;
 			}
 			for (const text of Array.isArray(value) ? value : [value]) {
-				if (text.trim().length === 0 || /\bTODO\b/i.test(text)) {
+				if (isProviderLocalePlaceholderText(text)) {
 					issues.push({
 						locale,
 						key,

package/src/i18n/error-messages.ts

@@ -0,0 +1,255 @@
+import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import type { ProviderLocaleCatalogMap } from "./catalog.js";
+import {
+	getProviderLocaleSegments,
+	isProviderLocaleKey,
+	type ProviderLocale,
+	type ProviderLocaleValue,
+} 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 const PROVIDER_ERROR_LOCALES = ["en", "ko", "ja"] as const;
+
+/** 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: string | undefined): value is ProviderLocale {
+	return PROVIDER_ERROR_LOCALES.some((locale) => locale === value);
+}
+
+type RankedLanguageRange = {
+	readonly primary: string;
+	readonly quality: number;
+	readonly position: number;
+};
+
+/**
+ * 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: string | null | undefined,
+): ProviderLocale | undefined {
+	if (typeof header !== "string" || header.length === 0) return undefined;
+	const ranges: RankedLanguageRange[] = [];
+	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: readonly string[]): number {
+	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: Readonly<Record<string, unknown>> | undefined,
+): string | undefined {
+	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: readonly (string | null | undefined)[]
+): ProviderLocale {
+	for (const value of headerValues) {
+		const locale = providerLocaleFromAcceptLanguage(value);
+		if (locale) return locale;
+	}
+	return DEFAULT_PROVIDER_ERROR_LOCALE;
+}
+
+function truncateText(value: string, limit: number): string {
+	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: unknown): string | undefined {
+	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: string,
+	params?: ProviderErrorMessageParams,
+): string {
+	const rendered = template.replace(PLACEHOLDER_PATTERN, (match, name?: string) => {
+		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: ProviderLocaleValue | undefined): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function readCatalogSegments(
+	catalogs: ProviderLocaleCatalogMap,
+	segments: readonly string[],
+	locale: ProviderLocale,
+	fallbackLocale: ProviderLocale,
+): string | undefined {
+	return (
+		asCatalogText(getProviderLocaleSegments(catalogs[locale] ?? {}, segments)) ??
+		asCatalogText(getProviderLocaleSegments(catalogs[fallbackLocale] ?? {}, segments))
+	);
+}
+
+/** 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 function localizeProviderErrorText(
+	options: LocalizeProviderErrorTextOptions,
+): string | undefined {
+	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: ProviderErrorTextCandidate): readonly string[] | undefined {
+	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: string, field: "message" | "fix"): string {
+	return `${PROVIDER_ERROR_CATALOG_NAMESPACE}.${code}.${field}`;
+}

package/src/i18n/index.ts

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

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/i18n/operation-locale-namespace.ts

@@ -0,0 +1,10 @@
+import { assertProviderLocaleKey } from "./keys.js";
+
+/** Canonical locale-catalog namespace for a URL-safe provider operation id. */
+export function operationIdToLocaleNamespace(operationId: string): string {
+	const namespace = operationId.replace(/[-_]([a-z0-9])/g, (_separator, character: string) =>
+		character.toUpperCase(),
+	);
+	assertProviderLocaleKey(`operations.${namespace}.description`);
+	return namespace;
+}