@apifuse/provider-sdk 2.2.0-beta.52 → 2.2.0-beta.54

package/dist/types.d.ts

@@ -1748,6 +1748,7 @@ export interface FlowContext {
     externalRef?: string;
     tenantId: string;
     providerId: string;
+    trace: TraceContext;
     http: HttpClient;
     /** Durable connection-scoped runtime state. Present when the host runtime
      * supplies one; auth ceremonies must fail closed when absent rather than

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.52",
+	"version": "2.2.0-beta.54",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-kebab-operation-id.ts.txt

@@ -0,0 +1,17 @@
+const listHospitalsOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [
+		{
+			scenario: "List nearby hospitals",
+			input: { latitude: 37.5665, longitude: 126.978 },
+			rationale: "Exercises a kebab-case operation id.",
+		},
+	],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+export default buildProvider({
+	operations: { "list-hospitals": listHospitalsOperation },
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-snake-operation-id.ts.txt

@@ -0,0 +1,21 @@
+const listRecentEarthquakesOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	docs: {
+		titleKey: "operations.listRecentEarthquakes.title",
+		descriptionKey: "operations.listRecentEarthquakes.description",
+	},
+	inputExamples: [
+		{
+			scenario: "List recent earthquakes",
+			input: { limit: 10 },
+			rationale: "Exercises a snake-case operation id.",
+		},
+	],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+export default buildProvider({
+	operations: { list_recent_earthquakes: listRecentEarthquakesOperation },
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-existing-operation-namespace-en.json

@@ -0,0 +1,8 @@
+{
+	"operations": {
+		"listRecentEarthquakes": {
+			"title": "Recent earthquakes",
+			"description": "Lists recent earthquakes."
+		}
+	}
+}

package/src/cli/migrate-operation-declaration.ts

@@ -3,6 +3,9 @@ import { dirname, extname, join, relative, resolve } from "node:path";
 
 import type TS from "typescript";
 
+import { assertProviderLocaleKey } from "../i18n/keys.js";
+import { operationIdToLocaleNamespace } from "../i18n/operation-locale-namespace.js";
+
 const ts: typeof import("typescript") = await loadTypeScript();
 
 async function loadTypeScript(): Promise<typeof import("typescript")> {
@@ -67,6 +70,7 @@ export type OperationDeclarationRefusalReason =
 	| "missing_english_locale"
 	| "operation_id_unresolved"
 	| "examples_conflict"
+	| "invalid_locale_key"
 	| "locale_todo_conflict";
 
 export type OperationDeclarationRefusal = {
@@ -180,6 +184,10 @@ export function migrateOperationDeclaration(
 		todos.push(...plan.localeTodos);
 	}
 	if (refusals.length > 0) return { status: "refused", refusals };
+	const invalidLocaleKey = findInvalidLocaleTodo(todos, fileName);
+	if (invalidLocaleKey !== undefined) {
+		return { status: "refused", refusals: [invalidLocaleKey] };
+	}
 
 	if (edits.length === 0) {
 		return {
@@ -400,6 +408,30 @@ function planOperationMigration(
 		if (merged.insert !== undefined) addInsertion(insertions, "docs", merged.insert);
 	}
 
+	const title = planTitleLocale(
+		top.byName.get("title"),
+		top.byName.get("titleKey"),
+		docs.get("titleKey"),
+		fileName,
+		site,
+		localeFiles,
+	);
+	if ("refusal" in title) return title;
+	const localeNamespace =
+		top.byName.get("inputExamples") === undefined
+			? { namespace: site.operationKey }
+			: resolveOperationLocaleNamespace(
+					[
+						top.byName.get("titleKey"),
+						docs.get("titleKey"),
+						top.byName.get("descriptionKey"),
+						docs.get("descriptionKey"),
+					],
+					fileName,
+					site,
+				);
+	if ("refusal" in localeNamespace) return localeNamespace;
+
 	const examples = planExamples(
 		top.byName.get("inputExamples"),
 		top.byName.get("examples"),
@@ -408,6 +440,7 @@ function planOperationMigration(
 		source,
 		constArrays,
 		localeFiles,
+		localeNamespace.namespace,
 	);
 	if ("refusal" in examples) return examples;
 
@@ -431,7 +464,107 @@ function planOperationMigration(
 		if (!edits.some((existing) => rangesOverlap(existing, edit))) edits.push(edit);
 	}
 
-	return { edits, localeTodos: examples.localeTodos };
+	return { edits, localeTodos: [...title.localeTodos, ...examples.localeTodos] };
+}
+
+function planTitleLocale(
+	title: ResolvedMember | undefined,
+	flatTitleKey: ResolvedMember | undefined,
+	nestedTitleKey: ResolvedMember | undefined,
+	fileName: string,
+	site: OperationSite,
+	localeFiles: readonly string[],
+):
+	| { readonly localeTodos: readonly LocaleTodo[] }
+	| { readonly refusal: OperationDeclarationRefusal } {
+	if (title === undefined) return { localeTodos: [] };
+	const originalProse = literalString(title.initializer);
+	if (originalProse === undefined) {
+		return nonLiteral(
+			fileName,
+			site.operationKey,
+			"title must be a string literal so its authored prose can be preserved in the English locale catalog.",
+		);
+	}
+	if (!site.operationIdProven) {
+		return {
+			refusal: refusal(
+				fileName,
+				site.operationKey,
+				"operation_id_unresolved",
+				"title requires an exact operation id proven from a static operations map.",
+			),
+		};
+	}
+	if (!localeFiles.includes("locales/en.json")) {
+		return {
+			refusal: refusal(
+				fileName,
+				site.operationKey,
+				"missing_english_locale",
+				"title cannot be migrated because locales/en.json does not exist.",
+			),
+		};
+	}
+
+	let selectedTitleKey = flatTitleKey ?? nestedTitleKey;
+	if (flatTitleKey !== undefined && nestedTitleKey !== undefined) {
+		const same = equivalentLiteral(flatTitleKey.initializer, nestedTitleKey.initializer);
+		if (same === undefined) {
+			return nonLiteral(
+				fileName,
+				site.operationKey,
+				"titleKey must be literal when both top-level and nested declarations exist.",
+			);
+		}
+		if (!same) {
+			return {
+				refusal: refusal(
+					fileName,
+					site.operationKey,
+					"locale_key_conflict",
+					"Top-level titleKey conflicts with nested titleKey.",
+				),
+			};
+		}
+		selectedTitleKey = flatTitleKey;
+	}
+	const explicitTitleKey =
+		selectedTitleKey === undefined ? undefined : literalString(selectedTitleKey.initializer);
+	if (selectedTitleKey !== undefined && explicitTitleKey === undefined) {
+		return nonLiteral(
+			fileName,
+			site.operationKey,
+			"titleKey must be a string literal so the title locale destination is provable.",
+		);
+	}
+	let selectedTitleLocaleKey: string;
+	if (explicitTitleKey !== undefined) {
+		selectedTitleLocaleKey = explicitTitleKey;
+	} else {
+		try {
+			selectedTitleLocaleKey = `operations.${operationIdToLocaleNamespace(site.operationKey)}.title`;
+		} catch (error) {
+			return {
+				refusal: invalidLocaleKeyRefusal(
+					fileName,
+					site.operationKey,
+					`operations.${site.operationKey}.title`,
+					error,
+				),
+			};
+		}
+	}
+	return {
+		localeTodos: [
+			{
+				localeFile: "locales/en.json",
+				operationKey: site.operationKey,
+				key: selectedTitleLocaleKey,
+				originalProse,
+			},
+		],
+	};
 }
 
 function resolveRiskClass(
@@ -664,6 +797,7 @@ function planExamples(
 	source: TS.SourceFile,
 	constArrays: ReadonlyMap<string, TS.ArrayLiteralExpression>,
 	localeFiles: readonly string[],
+	localeNamespace: string,
 ):
 	| { readonly edits: readonly TextEdit[]; readonly localeTodos: readonly LocaleTodo[] }
 	| { readonly refusal: OperationDeclarationRefusal } {
@@ -760,7 +894,7 @@ function planExamples(
 				`inputExamples[${index}].scenario must be a string literal.`,
 			);
 		}
-		const scenarioKey = `operations.${site.operationKey}.examples.${index}.scenario`;
+		const scenarioKey = `operations.${localeNamespace}.examples.${index}.scenario`;
 		edits.push(replaceExampleLocaleMember(scenario, "scenarioKey", scenarioKey, source));
 		for (const localeFile of localeFiles) {
 			todos.push({
@@ -781,7 +915,7 @@ function planExamples(
 					`inputExamples[${index}].rationale must be a string literal.`,
 				);
 			}
-			const rationaleKey = `operations.${site.operationKey}.examples.${index}.rationale`;
+			const rationaleKey = `operations.${localeNamespace}.examples.${index}.rationale`;
 			edits.push(replaceExampleLocaleMember(rationale, "rationaleKey", rationaleKey, source));
 			for (const localeFile of localeFiles) {
 				todos.push({
@@ -796,6 +930,47 @@ function planExamples(
 	return { edits, localeTodos: todos };
 }
 
+function resolveOperationLocaleNamespace(
+	members: readonly (ResolvedMember | undefined)[],
+	fileName: string,
+	site: OperationSite,
+): { readonly namespace: string } | { readonly refusal: OperationDeclarationRefusal } {
+	const authoredNamespaces = new Set<string>();
+	for (const member of members) {
+		const localeKey = literalString(member?.initializer);
+		if (localeKey === undefined) continue;
+		const segments = localeKey.split(".");
+		if (segments[0] === "operations" && segments[1] !== undefined) {
+			authoredNamespaces.add(segments[1]);
+		}
+	}
+	if (authoredNamespaces.size > 1) {
+		return {
+			refusal: refusal(
+				fileName,
+				site.operationKey,
+				"locale_key_conflict",
+				`Operation titleKey and descriptionKey declarations use different locale namespaces: ${[...authoredNamespaces].join(", ")}.`,
+			),
+		};
+	}
+	const authored = authoredNamespaces.values().next().value;
+	if (authored !== undefined) return { namespace: authored };
+
+	try {
+		return { namespace: operationIdToLocaleNamespace(site.operationKey) };
+	} catch (error) {
+		return {
+			refusal: invalidLocaleKeyRefusal(
+				fileName,
+				site.operationKey,
+				`operations.${site.operationKey}.examples`,
+				error,
+			),
+		};
+	}
+}
+
 function replaceExampleLocaleMember(
 	member: ResolvedMember,
 	newName: string,
@@ -984,9 +1159,7 @@ function isProviderOperationsProperty(
 	// (a) The initializer (direct or via same-file const) mentions
 	// defineOperation / defineStreamOperation — the strongest signal.
 	const target = ts.isIdentifier(unwrapExpression(node.initializer) ?? node.initializer)
-		? constObjects.get(
-				(unwrapExpression(node.initializer) as TS.Identifier).text,
-			)
+		? constObjects.get((unwrapExpression(node.initializer) as TS.Identifier).text)
 		: undefined;
 	const initializerText = (target ?? node.initializer).getText();
 	if (/\bdefine(?:Stream)?Operation\b/.test(initializerText)) return true;
@@ -1513,6 +1686,35 @@ function refusal(
 	return { file, operationKey, reason, detail };
 }
 
+function findInvalidLocaleTodo(
+	todos: readonly LocaleTodo[],
+	fileName: string,
+): OperationDeclarationRefusal | undefined {
+	for (const todo of todos) {
+		try {
+			assertProviderLocaleKey(todo.key);
+		} catch (error) {
+			return invalidLocaleKeyRefusal(fileName, todo.operationKey, todo.key, error);
+		}
+	}
+	return undefined;
+}
+
+function invalidLocaleKeyRefusal(
+	fileName: string,
+	operationKey: string,
+	localeKey: string,
+	error: unknown,
+): OperationDeclarationRefusal {
+	const validatorDetail = error instanceof Error ? error.message : String(error);
+	return refusal(
+		fileName,
+		operationKey,
+		"invalid_locale_key",
+		`Refusing to write invalid provider locale key ${JSON.stringify(localeKey)}: ${validatorDetail}`,
+	);
+}
+
 function nonLiteral(
 	fileName: string,
 	operationKey: string,

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;
+}

package/src/runtime/auth-flow.ts

@@ -13,6 +13,7 @@ import type {
 import { createUnsupportedOcrClient } from "./ocr.js";
 import { createUnsupportedResolverClient } from "./resolver-shared.js";
 import { createUnsupportedSttClient } from "./stt.js";
+import { createTraceContext } from "./trace.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 	return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -66,6 +67,7 @@ export function createFlowContext(options: {
 	initialContext?: Record<string, unknown>;
 	ocr?: OcrContext;
 	stt?: SttContext;
+	trace?: FlowContext["trace"];
 }): FlowContext {
 	return {
 		flowId: options.flowId,
@@ -73,6 +75,7 @@ export function createFlowContext(options: {
 		externalRef: options.externalRef,
 		tenantId: options.tenantId,
 		providerId: options.providerId,
+		trace: options.trace ?? createTraceContext(),
 		http: options.http,
 		state: options.state,
 		stealth: options.stealth,

package/src/runtime/trace.ts

@@ -21,6 +21,8 @@ export interface CreateTraceContextOptions {
 	onSpan?: (span: Span) => void;
 	exportOptions?: OTLPExportOptions;
 	resourceAttributes?: Record<string, string>;
+	/** W3C-compatible 32-character lowercase hexadecimal trace id used for export. */
+	traceId?: string;
 	/**
 	 * Applied to a detached copy of each span immediately before OTLP export; never touches
 	 * getSpans() or onSpan. Returning nothing (or throwing) drops that export batch.
@@ -55,11 +57,33 @@ export interface TraceRecorder {
 }
 
 export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-recorder");
+const TRACE_EXPORT_METADATA = Symbol.for(
+	"@apifuse/provider-sdk/runtime/trace-export-metadata",
+);
+
+type TraceExportMetadata = {
+	update(input: { traceId?: string; resourceAttributes?: Record<string, string> }): void;
+};
 
 type InternalTraceContext = TraceContext & {
 	[TRACE_RECORDER]: TraceRecorder;
+	[TRACE_EXPORT_METADATA]: TraceExportMetadata;
 };
 
+function assertValidTraceId(traceId: string): void {
+	if (!/^[0-9a-f]{32}$/.test(traceId) || /^0{32}$/.test(traceId)) {
+		throw new TypeError("traceId must be 32 lowercase hexadecimal characters and non-zero");
+	}
+}
+
+/** Updates request metadata before its pending root span completes and exports. */
+export function updateTraceContextExportMetadata(
+	trace: BaseTraceContext,
+	input: { traceId?: string; resourceAttributes?: Record<string, string> },
+): void {
+	(trace as Partial<InternalTraceContext>)[TRACE_EXPORT_METADATA]?.update(input);
+}
+
 function buildOTLPExportOptions(config?: TraceConfig): OTLPExportOptions | undefined {
 	if (config?.exporter !== "otlp") {
 		return undefined;
@@ -148,6 +172,7 @@ export function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null
 }
 
 export function createTraceContext(options: CreateTraceContextOptions = {}): TraceContext {
+	if (options.traceId !== undefined) assertValidTraceId(options.traceId);
 	const maxSpans = options.maxSpans ?? 1000;
 	const completed: CompletedSpanEntry[] = [];
 	const activeSpanStorage = new AsyncLocalStorage<PendingSpan | undefined>();
@@ -160,7 +185,7 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 		: undefined;
 	// One trace id per context so every export batch of this request shares it and
 	// two processes can never mint the same id.
-	const exportTraceId = crypto.randomUUID().replace(/-/g, "");
+	let exportTraceId = options.traceId ?? crypto.randomUUID().replace(/-/g, "");
 	let exportScheduled = false;
 
 	// One pending batch per context: roots completing before the flush share it, and a span is
@@ -265,6 +290,17 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 			return completed.map((entry) => ({ ...entry.span }));
 		},
 		[TRACE_RECORDER]: recorder,
+		[TRACE_EXPORT_METADATA]: {
+			update(input) {
+				if (input.traceId !== undefined) {
+					assertValidTraceId(input.traceId);
+					exportTraceId = input.traceId;
+				}
+				if (input.resourceAttributes !== undefined && exportResourceAttributes) {
+					Object.assign(exportResourceAttributes, input.resourceAttributes);
+				}
+			},
+		},
 	};
 
 	return traceContext;