@apifuse/provider-sdk 2.2.0-beta.41 → 2.2.0-beta.43

package/src/cli/migrate-provider-shape.ts

@@ -1,4 +1,17 @@
-import ts from "typescript";
+import type TS from "typescript";
+
+const ts: typeof import("typescript") = await loadTypeScript();
+
+async function loadTypeScript(): Promise<typeof import("typescript")> {
+	try {
+		return await import("typescript");
+	} catch {
+		console.error(
+			"apifuse migrate-shape requires typescript; install it in the workspace running the CLI (bun add -d typescript)",
+		);
+		process.exit(1);
+	}
+}
 
 /**
  * Provider authoring shape migration.
@@ -207,16 +220,16 @@ type ShapeClassification =
 			readonly kind: Exclude<ProviderShapeKind, "two-phase">;
 			/** Variable the declaration is currently bound to, when it is bound. */
 			readonly variableName?: string;
-			readonly variableStatement?: ts.VariableStatement;
+			readonly variableStatement?: TS.VariableStatement;
 			/** Extra properties on a `{ ...provider, deployment }` default export. */
 			readonly spreadExportExtras?: string;
 	  }
 	| { readonly status: "skipped"; readonly reason: string };
 
 function classifyShape(
-	source: ts.SourceFile,
-	call: ts.CallExpression,
-	exportAssignment: ts.ExportAssignment,
+	source: TS.SourceFile,
+	call: TS.CallExpression,
+	exportAssignment: TS.ExportAssignment,
 ): ShapeClassification {
 	const variableStatement = enclosingVariableStatement(call);
 
@@ -307,9 +320,9 @@ function classifyShape(
 	};
 }
 
-function collectDefineProviderCalls(source: ts.SourceFile): ts.CallExpression[] {
-	const calls: ts.CallExpression[] = [];
-	const visit = (node: ts.Node): void => {
+function collectDefineProviderCalls(source: TS.SourceFile): TS.CallExpression[] {
+	const calls: TS.CallExpression[] = [];
+	const visit = (node: TS.Node): void => {
 		if (
 			ts.isCallExpression(node) &&
 			ts.isIdentifier(node.expression) &&
@@ -323,7 +336,7 @@ function collectDefineProviderCalls(source: ts.SourceFile): ts.CallExpression[]
 	return calls;
 }
 
-function findDefaultExport(source: ts.SourceFile): ts.ExportAssignment | undefined {
+function findDefaultExport(source: TS.SourceFile): TS.ExportAssignment | undefined {
 	for (const statement of source.statements) {
 		if (ts.isExportAssignment(statement) && statement.isExportEquals !== true) {
 			return statement;
@@ -333,8 +346,8 @@ function findDefaultExport(source: ts.SourceFile): ts.ExportAssignment | undefin
 }
 
 function defaultExportCallsBuilder(
-	exportAssignment: ts.ExportAssignment,
-	declarationCall: ts.CallExpression,
+	exportAssignment: TS.ExportAssignment,
+	declarationCall: TS.CallExpression,
 ): boolean {
 	const expression = exportAssignment.expression;
 	if (!ts.isCallExpression(expression)) return false;
@@ -353,9 +366,9 @@ function defaultExportCallsBuilder(
  * breaks idempotency for repeated fan-out runs.
  */
 function isAlreadyTwoPhase(
-	source: ts.SourceFile,
-	exportAssignment: ts.ExportAssignment,
-	declarationCall: ts.CallExpression,
+	source: TS.SourceFile,
+	exportAssignment: TS.ExportAssignment,
+	declarationCall: TS.CallExpression,
 ): boolean {
 	if (defaultExportCallsBuilder(exportAssignment, declarationCall)) return true;
 
@@ -375,7 +388,7 @@ function isAlreadyTwoPhase(
 	// Does any spread/exported identifier bind a call to an identifier other
 	// than defineProvider — i.e. a builder call?
 	let found = false;
-	const visit = (node: ts.Node): void => {
+	const visit = (node: TS.Node): void => {
 		if (found) return;
 		if (
 			ts.isVariableDeclaration(node) &&
@@ -397,8 +410,8 @@ function isAlreadyTwoPhase(
 }
 
 function findOperationsProperty(
-	declaration: ts.ObjectLiteralExpression,
-): ts.ObjectLiteralElementLike | undefined {
+	declaration: TS.ObjectLiteralExpression,
+): TS.ObjectLiteralElementLike | undefined {
 	for (const property of declaration.properties) {
 		if (ts.isSpreadAssignment(property)) continue;
 		const name = property.name;
@@ -419,8 +432,8 @@ function findOperationsProperty(
  * its initializer verbatim, including a multi-line inline map.
  */
 function operationsPropertyValueText(
-	property: ts.ObjectLiteralElementLike,
-	source: ts.SourceFile,
+	property: TS.ObjectLiteralElementLike,
+	source: TS.SourceFile,
 ): string | undefined {
 	if (ts.isShorthandPropertyAssignment(property)) {
 		return property.name.text;
@@ -432,9 +445,9 @@ function operationsPropertyValueText(
 }
 
 function removeOperationsProperty(
-	property: ts.ObjectLiteralElementLike,
-	declaration: ts.ObjectLiteralExpression,
-	source: ts.SourceFile,
+	property: TS.ObjectLiteralElementLike,
+	declaration: TS.ObjectLiteralExpression,
+	source: TS.SourceFile,
 ): TextEdit[] {
 	const properties = declaration.properties;
 	const index = properties.indexOf(property);
@@ -464,8 +477,8 @@ function removeOperationsProperty(
 }
 
 function introduceBuilder(
-	source: ts.SourceFile,
-	call: ts.CallExpression,
+	source: TS.SourceFile,
+	call: TS.CallExpression,
 	shape: Extract<ShapeClassification, { status: "ok" }>,
 	builderName: string,
 ): TextEdit[] {
@@ -501,8 +514,8 @@ function introduceBuilder(
 }
 
 function rewriteDefaultExport(
-	source: ts.SourceFile,
-	exportAssignment: ts.ExportAssignment,
+	source: TS.SourceFile,
+	exportAssignment: TS.ExportAssignment,
 	shape: Extract<ShapeClassification, { status: "ok" }>,
 	builderName: string,
 	operationsText: string,
@@ -564,8 +577,8 @@ function rewriteDefaultExport(
  * type the two-phase shape exists to provide.
  */
 function ensureProviderContextType(
-	source: ts.SourceFile,
-	call: ts.CallExpression,
+	source: TS.SourceFile,
+	call: TS.CallExpression,
 	shape: Extract<ShapeClassification, { status: "ok" }>,
 	builderName: string,
 ): TextEdit[] {
@@ -577,6 +590,15 @@ function ensureProviderContextType(
 			ts.isTypeAliasDeclaration(statement) &&
 			statement.name.text === PROVIDER_CONTEXT_TYPE_NAME,
 	);
+	// A named import of `ProviderContext` (the deprecated SDK-root context
+	// type, imported by legacy sources) occupies the same name: adding the
+	// alias alongside it is TS2440. The import must yield to the derived
+	// alias — the whole point of the two-phase shape — so drop it and let the
+	// alias own the name.
+	const conflictingImportSpecifier = findNamedImportSpecifier(
+		source,
+		PROVIDER_CONTEXT_TYPE_NAME,
+	);
 
 	if (!hasContextTypeAlias) {
 		// After the builder statement — which is the variable statement when the
@@ -591,6 +613,9 @@ function ensureProviderContextType(
 				end: insertAt,
 				text: `\n\nexport type ${PROVIDER_CONTEXT_TYPE_NAME} = ${PROVIDER_CONTEXT_OF_TYPE_NAME}<typeof ${builderName}>;`,
 			});
+			if (conflictingImportSpecifier !== undefined) {
+				edits.push(removeImportSpecifier(source, conflictingImportSpecifier));
+			}
 		}
 	}
 
@@ -622,8 +647,8 @@ function ensureProviderContextType(
 }
 
 function findProviderSdkImport(
-	source: ts.SourceFile,
-): ts.ImportDeclaration | undefined {
+	source: TS.SourceFile,
+): TS.ImportDeclaration | undefined {
 	for (const statement of source.statements) {
 		if (!ts.isImportDeclaration(statement)) continue;
 		const moduleSpecifier = statement.moduleSpecifier;
@@ -640,13 +665,59 @@ function findProviderSdkImport(
 	return undefined;
 }
 
+/** Named import specifier binding `localName` in any import declaration. */
+function findNamedImportSpecifier(
+	source: TS.SourceFile,
+	localName: string,
+): TS.ImportSpecifier | undefined {
+	for (const statement of source.statements) {
+		if (!ts.isImportDeclaration(statement)) continue;
+		const named = statement.importClause?.namedBindings;
+		if (named === undefined || !ts.isNamedImports(named)) continue;
+		for (const element of named.elements) {
+			if (element.name.text === localName) return element;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Edit removing one specifier from its named-import list, absorbing one
+ * neighboring comma so the list stays well-formed. Callers guarantee the
+ * list has at least one other specifier (legacy sources always import
+ * defineProvider alongside the context type).
+ */
+function removeImportSpecifier(
+	source: TS.SourceFile,
+	specifier: TS.ImportSpecifier,
+): TextEdit {
+	const list = specifier.parent;
+	const index = list.elements.indexOf(specifier);
+	const text = source.getFullText();
+	let start = specifier.getFullStart();
+	let end = specifier.getEnd();
+	let cursor = end;
+	while (cursor < text.length && /\s/.test(text.charAt(cursor))) cursor += 1;
+	if (text.charAt(cursor) === ",") {
+		end = cursor + 1;
+	} else if (index > 0) {
+		const previous = list.elements[index - 1];
+		if (previous !== undefined) {
+			let back = previous.getEnd();
+			while (back < text.length && /\s/.test(text.charAt(back))) back += 1;
+			if (text.charAt(back) === ",") start = back;
+		}
+	}
+	return { start, end, text: "" };
+}
+
 /**
  * `buildProvider` unless the module already binds that name, in which case a
  * numbered suffix keeps the transform from shadowing an existing binding.
  */
-function pickBuilderName(source: ts.SourceFile): string {
+function pickBuilderName(source: TS.SourceFile): string {
 	const taken = new Set<string>();
-	const visit = (node: ts.Node): void => {
+	const visit = (node: TS.Node): void => {
 		if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
 			taken.add(node.name.text);
 		}
@@ -668,8 +739,8 @@ function pickBuilderName(source: ts.SourceFile): string {
 	return `${DECLARATION_BUILDER_NAME}Migrated`;
 }
 
-function enclosingVariableStatement(node: ts.Node): ts.VariableStatement | undefined {
-	let current: ts.Node | undefined = node.parent;
+function enclosingVariableStatement(node: TS.Node): TS.VariableStatement | undefined {
+	let current: TS.Node | undefined = node.parent;
 	while (current !== undefined) {
 		if (ts.isVariableStatement(current)) return current;
 		if (ts.isSourceFile(current)) return undefined;
@@ -678,9 +749,9 @@ function enclosingVariableStatement(node: ts.Node): ts.VariableStatement | undef
 	return undefined;
 }
 
-function firstSyntaxError(source: ts.SourceFile): string | undefined {
+function firstSyntaxError(source: TS.SourceFile): string | undefined {
 	const diagnostics = (
-		source as ts.SourceFile & { parseDiagnostics?: ts.DiagnosticWithLocation[] }
+		source as TS.SourceFile & { parseDiagnostics?: TS.DiagnosticWithLocation[] }
 	).parseDiagnostics;
 	if (diagnostics === undefined || diagnostics.length === 0) return undefined;
 	const first = diagnostics[0];

package/src/define.ts

@@ -2892,6 +2892,16 @@ export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer
 	? ProviderContextFor<TDeclaration>
 	: never;
 
+/** Annotate an operation while preserving the declaration-derived context. */
+export type OperationDefinitionFor<
+	TBuilder,
+	TInput extends SchemaLike = SchemaLike,
+	TOutput extends SchemaLike = SchemaLike,
+> = OperationDefinition<TInput, TOutput, ProviderContextOf<TBuilder>>;
+
+/** Annotate a built provider while preserving the declaration-derived context. */
+export type ProviderDefinitionFor<TBuilder> = ProviderDefinition<ProviderContextOf<TBuilder>>;
+
 /** Establish a provider declaration before its operations are contextually typed. */
 export function defineProvider<const TDeclaration extends ProviderDeclaration>(
 	declaration: TDeclaration &

package/src/index.ts

@@ -37,9 +37,11 @@ export {
 	defineStreamOperation,
 	every,
 	type AuthStartNoInputGuard,
+	type OperationDefinitionFor,
 	type ProviderBuilder,
 	type ProviderContextOf,
 	type ProviderDeclaration,
+	type ProviderDefinitionFor,
 } from "./define.js";
 export {
 	AssertionExpressionSchema,

package/src/provider.ts

@@ -36,9 +36,11 @@ export {
 	every,
 } from "./define.js";
 export type {
+	OperationDefinitionFor,
 	ProviderBuilder,
 	ProviderContextOf,
 	ProviderDeclaration,
+	ProviderDefinitionFor,
 } from "./define.js";
 export type { JsonPrimitive, JsonValue } from "./contract-json.js";
 export {

package/src/server/serve-implementation.ts

@@ -23,7 +23,10 @@ import {
 	type ProviderErrorObservability,
 	type ProviderErrorOptions,
 } from "../errors.js";
-import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import {
+	REDACTED_FIXTURE_VALUE,
+	sanitizeDiagnosticText,
+} from "../fixture-sanitization.js";
 import {
 	loadProviderLocaleCatalogs,
 	localizeAuthTurn,
@@ -231,17 +234,21 @@ export type ProviderServerStatefulOwnerFenceValidator = (
 	signal: AbortSignal,
 ) => boolean | Promise<boolean>;
 
-export type ProviderServerOperationExecutorInput = {
-	readonly provider: ProviderDefinition;
+export type ProviderServerOperationExecutorInput<
+	TContext extends Partial<ProviderContext> = ProviderContext,
+> = {
+	readonly provider: ProviderDefinition<TContext>;
 	readonly operationId: string;
-	readonly ctx: ProviderContext;
+	readonly ctx: TContext;
 	readonly request: OperationRequest & { readonly deadlineAt?: string };
 	readonly signal?: AbortSignal;
 	readonly internalStatefulForward?: ProviderServerStatefulForwardEnvelope;
 };
 
-export type ProviderServerOperationExecutor = (
-	input: ProviderServerOperationExecutorInput,
+export type ProviderServerOperationExecutor<
+	TContext extends Partial<ProviderContext> = ProviderContext,
+> = (
+	input: ProviderServerOperationExecutorInput<TContext>,
 ) => Promise<unknown>;
 
 type RequestCleanup = () => void | Promise<void>;
@@ -1069,12 +1076,12 @@ export type ProviderServerLogEvent =
 
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 
-export type ProviderServerOptions = {
+export type ProviderServerOptions<TContext extends Partial<ProviderContext> = ProviderContext> = {
 	logger?: ProviderServerLogger;
 	/** Optional provider-specific operation executor. Stateful providers use this to preserve provider-local runtime semantics. */
-	operationExecutor?: ProviderServerOperationExecutor;
+	operationExecutor?: ProviderServerOperationExecutor<TContext>;
 	/** Optional signed internal executor for stateful owner forwarding. */
-	internalOperationExecutor?: ProviderServerOperationExecutor;
+	internalOperationExecutor?: ProviderServerOperationExecutor<TContext>;
 	statefulForwarding?: {
 		readonly secret: string;
 		readonly maxSkewMs?: number;
@@ -1519,9 +1526,48 @@ export type ProviderErrorCauseFrame = {
 
 const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
 const MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH = 300;
+const UNSTRUCTURED_PROVIDER_ERROR_CAUSE_MESSAGE = "[UNSTRUCTURED_UPSTREAM_TEXT]";
+const PROVIDER_ERROR_CAUSE_RETAINED_URL_RUN = /https?:\/\/[^\s"'<>]+/giu;
+const PROVIDER_ERROR_CAUSE_TOKEN_RUN = /\S+/gu;
+const PROVIDER_ERROR_CAUSE_TOKEN_EDGE_PUNCTUATION =
+	/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu;
+const STRUCTURALLY_SAFE_PROVIDER_ERROR_CAUSE_WORDS = new Set([
+	"completion",
+	"diagnostic",
+	"provider",
+	"rejected",
+	"returned",
+	"upstream",
+]);
+
+/**
+ * Cause frames fail closed when sanitization leaves a plausible credential-shaped free-text run.
+ * Redaction sentinels and retained URLs are ignored. Every other whitespace token (or each side
+ * of a structured key=value token) with at least eight Unicode characters must reduce to this
+ * small vocabulary drawn from SDK diagnostics; counting punctuation keeps bare passwords opaque.
+ */
+function isStructurallySafeProviderErrorCauseMessage(message: string): boolean {
+	const classifiableMessage = message
+		.replaceAll(REDACTED_FIXTURE_VALUE, " ")
+		.replace(PROVIDER_ERROR_CAUSE_RETAINED_URL_RUN, " ");
+	for (const match of classifiableMessage.matchAll(PROVIDER_ERROR_CAUSE_TOKEN_RUN)) {
+		const token = match[0];
+		for (const run of token.split("=")) {
+			const diagnosticWord = run
+				.replace(PROVIDER_ERROR_CAUSE_TOKEN_EDGE_PUNCTUATION, "")
+				.toLowerCase();
+			if (STRUCTURALLY_SAFE_PROVIDER_ERROR_CAUSE_WORDS.has(diagnosticWord)) continue;
+			if ([...run].length >= 8) return false;
+		}
+	}
+	return true;
+}
 
 function providerErrorCauseMessage(message: string): string {
 	const sanitized = sanitizeDiagnosticText(message);
+	if (!isStructurallySafeProviderErrorCauseMessage(sanitized)) {
+		return UNSTRUCTURED_PROVIDER_ERROR_CAUSE_MESSAGE;
+	}
 	return sanitized.length > MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH
 		? `${sanitized.slice(0, MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH)}… [truncated]`
 		: sanitized;
@@ -2371,16 +2417,18 @@ function parseStatefulForwardingEnvelope(rawBody: unknown): ProviderServerStatef
  * Primary, cross-runtime app factory. Declared capability ESM is preloaded
  * asynchronously, so this path works on Bun and every supported Node release.
  */
-export async function createServerAppAsync(
-	provider: ProviderDefinition,
-	options: ProviderServerOptions = {},
+export async function createServerAppAsync<TContext extends Partial<ProviderContext> = ProviderContext>(
+	provider: ProviderDefinition<TContext>,
+	options: ProviderServerOptions<TContext> = {},
 ): Promise<Hono> {
-	validateFailClosedDeclaration(provider);
-	validateStatefulServerConfig(options);
+	const runtimeProvider = provider as unknown as ProviderDefinition;
+	const runtimeOptions = options as unknown as ProviderServerOptions;
+	validateFailClosedDeclaration(runtimeProvider);
+	validateStatefulServerConfig(runtimeOptions);
 	return createServerAppWithCapabilityModules(
-		provider,
-		options,
-		await loadProviderCapabilityModules(provider),
+		runtimeProvider,
+		runtimeOptions,
+		await loadProviderCapabilityModules(runtimeProvider),
 	);
 }
 
@@ -2390,16 +2438,18 @@ export async function createServerAppAsync(
  * capability require Bun or Node >=22.12; older Node releases receive an
  * actionable error directing them to createServerAppAsync().
  */
-export function createServerApp(
-	provider: ProviderDefinition,
-	options: ProviderServerOptions = {},
+export function createServerApp<TContext extends Partial<ProviderContext> = ProviderContext>(
+	provider: ProviderDefinition<TContext>,
+	options: ProviderServerOptions<TContext> = {},
 ): Hono {
-	validateFailClosedDeclaration(provider);
-	validateStatefulServerConfig(options);
+	const runtimeProvider = provider as unknown as ProviderDefinition;
+	const runtimeOptions = options as unknown as ProviderServerOptions;
+	validateFailClosedDeclaration(runtimeProvider);
+	validateStatefulServerConfig(runtimeOptions);
 	return createServerAppWithCapabilityModules(
-		provider,
-		options,
-		loadProviderCapabilityModulesSync(provider),
+		runtimeProvider,
+		runtimeOptions,
+		loadProviderCapabilityModulesSync(runtimeProvider),
 	);
 }
 
@@ -3089,7 +3139,8 @@ export type ProviderServerHandle = {
 	close(options?: ProviderServerCloseOptions): Promise<void>;
 };
 
-export interface ServeOptions extends ProviderServerOptions {
+export interface ServeOptions<TContext extends Partial<ProviderContext> = ProviderContext>
+	extends ProviderServerOptions<TContext> {
 	host?: string;
 	port?: number;
 	/**
@@ -3116,9 +3167,9 @@ type ProcessSignalCoordinator = {
 
 const processSignalCoordinators = new Map<NodeJS.Signals, ProcessSignalCoordinator>();
 
-export async function serve(
-	provider: ProviderDefinition,
-	options: ServeOptions = {},
+export async function serve<TContext extends Partial<ProviderContext> = ProviderContext>(
+	provider: ProviderDefinition<TContext>,
+	options: ServeOptions<TContext> = {},
 ): Promise<ProviderServerHandle> {
 	const bunRuntime = getBunServeRuntime();
 
@@ -3133,7 +3184,7 @@ export async function serve(
 	);
 	const configuredSignals = resolveShutdownSignals(options.shutdown?.signals ?? true);
 	const selfTestSecrets = resolveSelfTestMasterSecrets();
-	const serverAppOptions: ProviderServerOptions = {
+	const serverAppOptions: ProviderServerOptions<TContext> = {
 		logger: options.logger,
 		ocr: options.ocr,
 		stt: options.stt,
@@ -3163,12 +3214,15 @@ export async function serve(
 		// socket the tenant-facing gateway never dials. Off by default — it only
 		// starts when the shared self-test master secret env is present.
 		if (selfTestSecrets && selfTestModule) {
-			const selfTestApp = selfTestModule.createSelfTestApp(provider, {
-				secrets: selfTestSecrets,
-				invoke: selfTestModule.createSelfTestInvoke(app),
-				authFlow: selfTestModule.createSelfTestAuthFlowInvoke(app),
-				logger,
-			});
+			const selfTestApp = selfTestModule.createSelfTestApp(
+				provider as unknown as ProviderDefinition,
+				{
+					secrets: selfTestSecrets,
+					invoke: selfTestModule.createSelfTestInvoke(app),
+					authFlow: selfTestModule.createSelfTestAuthFlowInvoke(app),
+					logger,
+				},
+			);
 			servers.push(
 				bunRuntime.serve({
 					port: options.selfTestPort ?? selfTestModule.resolveSelfTestPort(),

package/src/types.ts

@@ -2479,7 +2479,7 @@ export interface ProviderDeploymentOverrides {
 	buildContext?: string;
 }
 
-export interface ProviderDefinition {
+export interface ProviderDefinition<TContext = ProviderContext> {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
@@ -2509,7 +2509,7 @@ export interface ProviderDefinition {
 	credential?: CredentialDeclaration;
 	context?: ContextDeclaration;
 	meta: ProviderMeta;
-	operations: Record<string, OperationDefinition<SchemaLike, SchemaLike>>;
+	operations: Record<string, OperationDefinition<SchemaLike, SchemaLike, TContext>>;
 	healthMonitor?: ProviderHealthMonitorConfig;
 	/** Transitional alias for `healthMonitor`; `defineProvider` mirrors both. */
 	healthProbe?: ProviderHealthProbeConfig;