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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.54
+
+- Release candidate for main commit 4dccd0cd9d3443cde4edebf98ffc6c11beecb9ea.
+
+## 2.2.0-beta.53
+
+- Release candidate for main commit 40a916bac16bb2b2bbda7fc4a96132d10ca103bf.
+
 ## 2.2.0-beta.52
 
 - Release candidate for main commit 6e64ae0ad2e735b3de0c115f5ea29517efcf4ff2.

package/dist/cli/migrate-operation-declaration.d.ts

@@ -1,4 +1,4 @@
-export type OperationDeclarationRefusalReason = "no_safety" | "safety_conflict" | "locale_key_conflict" | "connection_mode_conflict" | "execution_conflict" | "approval_conflict" | "non_literal" | "unsupported_member" | "factory_composed_operations" | "source_syntax" | "codemod_syntax" | "missing_english_locale" | "operation_id_unresolved" | "examples_conflict" | "locale_todo_conflict";
+export type OperationDeclarationRefusalReason = "no_safety" | "safety_conflict" | "locale_key_conflict" | "connection_mode_conflict" | "execution_conflict" | "approval_conflict" | "non_literal" | "unsupported_member" | "factory_composed_operations" | "source_syntax" | "codemod_syntax" | "missing_english_locale" | "operation_id_unresolved" | "examples_conflict" | "invalid_locale_key" | "locale_todo_conflict";
 export type OperationDeclarationRefusal = {
     readonly file: string;
     readonly operationKey: string;

package/dist/cli/migrate-operation-declaration.js

@@ -1,5 +1,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, resolve } from "node:path";
+import { assertProviderLocaleKey } from "../i18n/keys.js";
+import { operationIdToLocaleNamespace } from "../i18n/operation-locale-namespace.js";
 const ts = await loadTypeScript();
 async function loadTypeScript() {
     try {
@@ -81,6 +83,10 @@ export function migrateOperationDeclaration(sourceText, fileName, options = {})
     }
     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 {
             status: "unchanged",
@@ -221,7 +227,20 @@ function planOperationMigration(source, fileName, site, constObjects, constArray
         if (merged.insert !== undefined)
             addInsertion(insertions, "docs", merged.insert);
     }
-    const examples = planExamples(top.byName.get("inputExamples"), top.byName.get("examples"), fileName, site, source, constArrays, localeFiles);
+    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"), fileName, site, source, constArrays, localeFiles, localeNamespace.namespace);
     if ("refusal" in examples)
         return examples;
     const edits = [...examples.edits];
@@ -245,7 +264,66 @@ function planOperationMigration(source, fileName, site, constObjects, constArray
         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, flatTitleKey, nestedTitleKey, fileName, site, localeFiles) {
+    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;
+    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(top, annotations, toolRouter, fileName, operationKey) {
     const topRisk = top.get("riskClass");
@@ -381,7 +459,7 @@ function mergeFlatAndNested(field, flat, nested, fileName, operationKey, source,
     }
     return {};
 }
-function planExamples(inputExamples, existingExamples, fileName, site, source, constArrays, localeFiles) {
+function planExamples(inputExamples, existingExamples, fileName, site, source, constArrays, localeFiles, localeNamespace) {
     if (inputExamples === undefined)
         return { edits: [], localeTodos: [] };
     if (existingExamples !== undefined) {
@@ -440,7 +518,7 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, c
         if (scenarioProse === undefined) {
             return nonLiteral(fileName, site.operationKey, `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({
@@ -456,7 +534,7 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, c
             if (rationaleProse === undefined) {
                 return nonLiteral(fileName, site.operationKey, `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({
@@ -470,6 +548,34 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, c
     }
     return { edits, localeTodos: todos };
 }
+function resolveOperationLocaleNamespace(members, fileName, site) {
+    const authoredNamespaces = new Set();
+    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, newName, localeKey, source) {
     return {
         start: member.property.getStart(source),
@@ -1049,6 +1155,21 @@ function firstSyntaxError(source) {
 function refusal(file, operationKey, reason, detail) {
     return { file, operationKey, reason, detail };
 }
+function findInvalidLocaleTodo(todos, fileName) {
+    for (const todo of todos) {
+        try {
+            assertProviderLocaleKey(todo.key);
+        }
+        catch (error) {
+            return invalidLocaleKeyRefusal(fileName, todo.operationKey, todo.key, error);
+        }
+    }
+    return undefined;
+}
+function invalidLocaleKeyRefusal(fileName, operationKey, localeKey, error) {
+    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, operationKey, detail) {
     return {
         refusal: refusal(fileName, operationKey, "non_literal", detail),

package/dist/i18n/operation-locale-namespace.d.ts

@@ -0,0 +1,2 @@
+/** Canonical locale-catalog namespace for a URL-safe provider operation id. */
+export declare function operationIdToLocaleNamespace(operationId: string): string;

package/dist/i18n/operation-locale-namespace.js

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

package/dist/runtime/auth-flow.d.ts

@@ -15,4 +15,5 @@ export declare function createFlowContext(options: {
     initialContext?: Record<string, unknown>;
     ocr?: OcrContext;
     stt?: SttContext;
+    trace?: FlowContext["trace"];
 }): FlowContext;

package/dist/runtime/auth-flow.js

@@ -3,6 +3,7 @@ import { createAuthFlowHelpers } from "../auth.js";
 import { createUnsupportedOcrClient } from "./ocr.js";
 import { createUnsupportedResolverClient } from "./resolver-shared.js";
 import { createUnsupportedSttClient } from "./stt.js";
+import { createTraceContext } from "./trace.js";
 function normalizeAllowedKeys(allowedKeys) {
     return new Set(allowedKeys.filter((key) => key.trim().length > 0));
 }
@@ -39,6 +40,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/dist/runtime/trace.d.ts

@@ -10,6 +10,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.
@@ -25,6 +27,11 @@ export interface TraceRecorder {
     runSpan<T>(name: string, fn: () => Promise<T> | T, options?: SpanHookOptions<T>): Promise<T>;
 }
 export declare const TRACE_RECORDER: unique symbol;
+/** Updates request metadata before its pending root span completes and exports. */
+export declare function updateTraceContextExportMetadata(trace: BaseTraceContext, input: {
+    traceId?: string;
+    resourceAttributes?: Record<string, string>;
+}): void;
 export declare function resolveTraceContextOptions(config?: TraceConfig): CreateTraceContextOptions;
 export declare function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null;
 export declare function createTraceContext(options?: CreateTraceContextOptions): TraceContext;

package/dist/runtime/trace.js

@@ -1,6 +1,16 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { exportSpansOTLP } from "./otlp.js";
 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");
+function assertValidTraceId(traceId) {
+    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, input) {
+    trace[TRACE_EXPORT_METADATA]?.update(input);
+}
 function buildOTLPExportOptions(config) {
     if (config?.exporter !== "otlp") {
         return undefined;
@@ -67,6 +77,8 @@ export function getTraceRecorder(trace) {
     return trace[TRACE_RECORDER] ?? null;
 }
 export function createTraceContext(options = {}) {
+    if (options.traceId !== undefined)
+        assertValidTraceId(options.traceId);
     const maxSpans = options.maxSpans ?? 1000;
     const completed = [];
     const activeSpanStorage = new AsyncLocalStorage();
@@ -79,7 +91,7 @@ export function createTraceContext(options = {}) {
         : 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
     // handed to the exporter exactly once, so later roots never re-send earlier spans.
@@ -168,6 +180,17 @@ export function createTraceContext(options = {}) {
             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;
 }

package/dist/server/serve-implementation.d.ts

@@ -79,6 +79,10 @@ type ProviderServerLogEventBase = ProviderRequestCost & {
     kind: "operation" | "auth";
     route: string;
     requestId?: string;
+    connectionId?: string;
+    flowId?: string;
+    tenantId?: string;
+    requestedProviderId?: string;
     status: number;
     proxy?: ProxyTelemetryLogPayload;
 };