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

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

@@ -0,0 +1,113 @@
+const ts = await loadTypeScript();
+async function loadTypeScript() {
+    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);
+    }
+}
+const OPERATION_HELPERS = new Set(["defineOperation", "defineStreamOperation"]);
+const PROVIDER_CONTEXT_TYPE_NAME = "ProviderContext";
+const PROVIDER_SDK_PROVIDER_SUBPATH = "@apifuse/provider-sdk/provider";
+/**
+ * Migrate legacy `defineOperation(config)` calls in one source file to the
+ * curried `defineOperation<ProviderContext>()(config)` form.
+ *
+ * @param contextImportSpecifier module specifier the `ProviderContext` type
+ * import should come from when one has to be added — `"../index"` for
+ * operation modules, `"./index"` is never needed because index.ts declares
+ * the alias itself. Callers pass the correct relative path per file.
+ */
+export function migrateOperationShape(sourceText, fileName, contextImportSpecifier) {
+    const source = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const parseError = firstSyntaxError(source);
+    if (parseError !== undefined) {
+        return { status: "skipped", reason: parseError };
+    }
+    // Every legacy call site: a direct call to the bare helper identifier
+    // whose single argument is the config (i.e. NOT the curried form, whose
+    // outer call has zero arguments and optional type arguments).
+    const legacyCalls = [];
+    let sawCurried = false;
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            OPERATION_HELPERS.has(node.expression.text)) {
+            if (node.arguments.length === 0) {
+                sawCurried = true; // already-migrated outer call
+            }
+            else {
+                legacyCalls.push(node);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (legacyCalls.length === 0) {
+        return { status: "unchanged", code: sourceText };
+    }
+    // A file mixing both forms almost certainly had a partial hand-migration;
+    // refuse rather than guess which convention the author wants.
+    if (sawCurried) {
+        return {
+            status: "skipped",
+            reason: "File mixes legacy defineOperation(config) with curried defineOperation<...>()(config); migrate it by hand.",
+        };
+    }
+    const declaresContextAlias = source.statements.some((statement) => ts.isTypeAliasDeclaration(statement) &&
+        statement.name.text === PROVIDER_CONTEXT_TYPE_NAME);
+    const importsContext = sourceText.includes(PROVIDER_CONTEXT_TYPE_NAME);
+    const needsImport = !declaresContextAlias && !importsContext;
+    const edits = [];
+    for (const call of legacyCalls) {
+        // `defineOperation(` -> `defineOperation<ProviderContext>()(`
+        const callee = call.expression;
+        edits.push({
+            start: callee.getEnd(),
+            end: callee.getEnd(),
+            text: `<${PROVIDER_CONTEXT_TYPE_NAME}>()`,
+        });
+    }
+    let importAdded = false;
+    if (needsImport) {
+        const lastImport = [...source.statements]
+            .reverse()
+            .find((statement) => ts.isImportDeclaration(statement));
+        const insertAt = lastImport ? lastImport.getEnd() : 0;
+        const importText = `${lastImport ? "\n" : ""}import type { ${PROVIDER_CONTEXT_TYPE_NAME} } from "${contextImportSpecifier}";${lastImport ? "" : "\n"}`;
+        edits.push({ start: insertAt, end: insertAt, text: importText });
+        importAdded = true;
+    }
+    const ordered = edits.sort((a, b) => b.start - a.start);
+    let code = sourceText;
+    for (const edit of ordered) {
+        code = code.slice(0, edit.start) + edit.text + code.slice(edit.end);
+    }
+    const verified = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const outputError = firstSyntaxError(verified);
+    if (outputError !== undefined) {
+        return {
+            status: "skipped",
+            reason: `Transform produced source that does not parse (${outputError}); refusing to emit a partial migration.`,
+        };
+    }
+    return {
+        status: "migrated",
+        code,
+        rewrites: legacyCalls.length,
+        importAdded,
+    };
+}
+function firstSyntaxError(source) {
+    const diagnostics = source.parseDiagnostics;
+    if (diagnostics === undefined || diagnostics.length === 0)
+        return undefined;
+    const first = diagnostics[0];
+    if (first === undefined)
+        return undefined;
+    const message = ts.flattenDiagnosticMessageText(first.messageText, " ");
+    const { line } = source.getLineAndCharacterOfPosition(first.start);
+    return `${message} (line ${line + 1})`;
+}

package/dist/cli/migrate-provider-shape.js

@@ -1,4 +1,13 @@
-import ts from "typescript";
+const ts = await loadTypeScript();
+async function loadTypeScript() {
+    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);
+    }
+}
 const DECLARATION_BUILDER_NAME = "buildProvider";
 const PROVIDER_CONTEXT_TYPE_NAME = "ProviderContext";
 const PROVIDER_CONTEXT_OF_TYPE_NAME = "ProviderContextOf";
@@ -397,6 +406,12 @@ function ensureProviderContextType(source, call, shape, builderName) {
     const edits = [];
     const hasContextTypeAlias = source.statements.some((statement) => 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
         // declaration was bound, or the rewritten export statement otherwise.
@@ -409,6 +424,9 @@ function ensureProviderContextType(source, call, shape, builderName) {
                 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));
+            }
         }
     }
     if (text.includes(PROVIDER_CONTEXT_OF_TYPE_NAME)) {
@@ -454,6 +472,51 @@ function findProviderSdkImport(source) {
     }
     return undefined;
 }
+/** Named import specifier binding `localName` in any import declaration. */
+function findNamedImportSpecifier(source, localName) {
+    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, specifier) {
+    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.

package/dist/define.d.ts

@@ -130,6 +130,10 @@ export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <TOperat
 };
 /** Extract the declaration-derived operation context from a provider builder. */
 export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TDeclaration> ? 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 declare function defineProvider<const TDeclaration extends ProviderDeclaration>(declaration: TDeclaration & Record<Exclude<keyof TDeclaration, keyof ProviderDeclaration>, never> & AuthStartNoInputGuard<TDeclaration>): ProviderBuilder<TDeclaration>;
 export {};

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export * from "./choice-token.js";
 export type { ApiFuseConfig, BrowserConfig, ProxyCacheStatus, ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyUserAgentSource, ProxyVendorName, ResolvedProxyConfig, SessionConfig, SmartproxyAllocatorBodyClass, } from "./config/loader.js";
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract.js";
-export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type AuthStartNoInputGuard, type ProviderBuilder, type ProviderContextOf, type ProviderDeclaration, } from "./define.js";
+export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type AuthStartNoInputGuard, type OperationDefinitionFor, type ProviderBuilder, type ProviderContextOf, type ProviderDeclaration, type ProviderDefinitionFor, } from "./define.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export type { AssertionExpression, AssertionPredicate, AttemptReference, AssertResult, AssertStep, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialReference, CredentialRefDeclaration, EstablishedConnectionReference, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JsonTemplate, JournalPolicy, ManualTriggerPolicy, NonEmpty, OperationResult, OperationStep, Operand, Quantifier, ReferenceNode, Reference, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ExtractResult, ValueType, } from "./health-scenario.js";
 export type { DevServerOptions } from "./dev.js";

package/dist/provider.d.ts

@@ -3,7 +3,7 @@ export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeReques
 export { createFormCeremony } from "./ceremonies/index.js";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, type ProviderChoiceTokenErrorReason, type ProviderChoiceTokenPayload, parseProviderChoiceToken, } from "./choice-token.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
-export type { ProviderBuilder, ProviderContextOf, ProviderDeclaration, } from "./define.js";
+export type { OperationDefinitionFor, ProviderBuilder, ProviderContextOf, ProviderDeclaration, ProviderDefinitionFor, } from "./define.js";
 export type { JsonPrimitive, JsonValue } from "./contract-json.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export type { AssertionExpression, AssertionPredicate, AttemptReference, AssertResult, AssertStep, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialReference, CredentialRefDeclaration, EstablishedConnectionReference, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JsonTemplate, JournalPolicy, ManualTriggerPolicy, NonEmpty, OperationResult, OperationStep, Operand, Quantifier, ReferenceNode, Reference, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ExtractResult, ValueType, } from "./health-scenario.js";

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

@@ -53,17 +53,17 @@ export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
 export type ProviderServerStatefulForwardEnvelope = Readonly<z.infer<typeof ProviderServerStatefulForwardEnvelopeSchema>>;
 export type ProviderServerStatefulOwnerFence = Readonly<Pick<ProviderServerStatefulForwardEnvelope, "providerId" | "sessionKey" | "ownerPodId" | "generation" | "sourcePodId" | "forwardedAt" | "requestId" | "idempotencyKey">>;
 export type ProviderServerStatefulOwnerFenceValidator = (fence: ProviderServerStatefulOwnerFence, 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) => Promise<unknown>;
+export type ProviderServerOperationExecutor<TContext extends Partial<ProviderContext> = ProviderContext> = (input: ProviderServerOperationExecutorInput<TContext>) => Promise<unknown>;
 export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
 export declare function resolveProviderResolverIdentityScope(provider: ProviderDefinition, affinityKey: string, contextId: string): string;
 export declare function resolveAuthFlowProxyAffinityKey(provider: ProviderDefinition, request: Pick<AuthFlowRequest, "connection" | "connectionId" | "externalRef" | "tenantId" | "providerId">): string;
@@ -138,12 +138,12 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     message: string;
 } | SelfTestCancellationLogEvent;
 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;
@@ -196,14 +196,14 @@ export type ProviderErrorCauseFrame = {
  * Primary, cross-runtime app factory. Declared capability ESM is preloaded
  * asynchronously, so this path works on Bun and every supported Node release.
  */
-export declare function createServerAppAsync(provider: ProviderDefinition, options?: ProviderServerOptions): Promise<Hono>;
+export declare function createServerAppAsync<TContext extends Partial<ProviderContext> = ProviderContext>(provider: ProviderDefinition<TContext>, options?: ProviderServerOptions<TContext>): Promise<Hono>;
 /**
  * Synchronous compatibility factory. Standard providers remain synchronous on
  * every runtime because they load no capability modules. Providers declaring a
  * capability require Bun or Node >=22.12; older Node releases receive an
  * actionable error directing them to createServerAppAsync().
  */
-export declare function createServerApp(provider: ProviderDefinition, options?: ProviderServerOptions): Hono;
+export declare function createServerApp<TContext extends Partial<ProviderContext> = ProviderContext>(provider: ProviderDefinition<TContext>, options?: ProviderServerOptions<TContext>): Hono;
 export type ProviderServerCloseOptions = {
     readonly timeoutMs?: number;
 };
@@ -211,7 +211,7 @@ export type ProviderServerHandle = {
     readonly port: number;
     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;
     /**
@@ -221,5 +221,5 @@ export interface ServeOptions extends ProviderServerOptions {
      */
     selfTestPort?: number;
 }
-export declare function serve(provider: ProviderDefinition, options?: ServeOptions): Promise<ProviderServerHandle>;
+export declare function serve<TContext extends Partial<ProviderContext> = ProviderContext>(provider: ProviderDefinition<TContext>, options?: ServeOptions<TContext>): Promise<ProviderServerHandle>;
 export {};

package/dist/server/serve-implementation.js

@@ -9,7 +9,7 @@ import { validateFailClosedDeclaration } from "../declaration-validation.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
 import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
-import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import { REDACTED_FIXTURE_VALUE, sanitizeDiagnosticText, } from "../fixture-sanitization.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
@@ -979,8 +979,47 @@ function extractRequestId(raw) {
 }
 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) {
+    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) {
     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;
@@ -1646,9 +1685,11 @@ function parseStatefulForwardingEnvelope(rawBody) {
  * asynchronously, so this path works on Bun and every supported Node release.
  */
 export async function createServerAppAsync(provider, options = {}) {
-    validateFailClosedDeclaration(provider);
-    validateStatefulServerConfig(options);
-    return createServerAppWithCapabilityModules(provider, options, await loadProviderCapabilityModules(provider));
+    const runtimeProvider = provider;
+    const runtimeOptions = options;
+    validateFailClosedDeclaration(runtimeProvider);
+    validateStatefulServerConfig(runtimeOptions);
+    return createServerAppWithCapabilityModules(runtimeProvider, runtimeOptions, await loadProviderCapabilityModules(runtimeProvider));
 }
 /**
  * Synchronous compatibility factory. Standard providers remain synchronous on
@@ -1657,9 +1698,11 @@ export async function createServerAppAsync(provider, options = {}) {
  * actionable error directing them to createServerAppAsync().
  */
 export function createServerApp(provider, options = {}) {
-    validateFailClosedDeclaration(provider);
-    validateStatefulServerConfig(options);
-    return createServerAppWithCapabilityModules(provider, options, loadProviderCapabilityModulesSync(provider));
+    const runtimeProvider = provider;
+    const runtimeOptions = options;
+    validateFailClosedDeclaration(runtimeProvider);
+    validateStatefulServerConfig(runtimeOptions);
+    return createServerAppWithCapabilityModules(runtimeProvider, runtimeOptions, loadProviderCapabilityModulesSync(runtimeProvider));
 }
 function createServerAppWithCapabilityModules(provider, serverOptions, capabilityModules) {
     const options = { ...serverOptions, capabilityModules };

package/dist/types.d.ts

@@ -2024,7 +2024,7 @@ export interface ProviderDeploymentOverrides {
     };
     buildContext?: string;
 }
-export interface ProviderDefinition {
+export interface ProviderDefinition<TContext = ProviderContext> {
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
@@ -2054,7 +2054,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;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.41",
+	"version": "2.2.0-beta.43",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -128,7 +128,8 @@
 		"@microsoft/api-extractor": "^7.58.13",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"ajv": "^8.17"
+		"ajv": "^8.17",
+		"typescript": "6.0.3"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
@@ -145,7 +146,6 @@
 		"safe-regex": "^2.1",
 		"socks": "^2.8.9",
 		"tough-cookie": "^6.0.2",
-		"typescript": "6.0.3",
 		"wreq-js": "3.0.0",
 		"zod": "^4.4.3"
 	},

package/src/cli/commands.ts

@@ -59,7 +59,7 @@ export const COMMAND_MANIFEST: Record<
 	"migrate-shape": {
 		name: "migrate-shape",
 		summary:
-			"Migrate a provider index.ts from the single-phase defineProvider shape to the two-phase declaration builder.",
+			"Migrate a provider to the phase-separated SDK: two-phase defineProvider in index.ts and curried defineOperation across sources.",
 		usage: "apifuse migrate-shape [path] [--check] [--json]",
 		examples: ["apifuse migrate-shape .", "apifuse migrate-shape . --check"],
 		modulePath: "./apifuse-migrate-shape",

package/src/cli/create.ts

@@ -26,7 +26,7 @@ export const CATEGORY_OPTIONS = [
 	"other",
 ] as const;
 export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"] as const;
-export const RUNTIME_OPTIONS = ["standard", "browser"] as const;
+export const RUNTIME_OPTIONS = ["standard", "shared", "browser"] as const;
 export const PRESET_OPTIONS = ["standalone", "monorepo"] as const;
 
 export type CreateCategory = (typeof CATEGORY_OPTIONS)[number];
@@ -102,7 +102,7 @@ Options:
   --display-name <name>
   --category <category>
   --auth-mode <mode>
-  --runtime <standard|browser>
+  --runtime <standard|shared|browser>
   --yes
   --dry-run
   --json

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

@@ -0,0 +1,184 @@
+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);
+	}
+}
+
+/**
+ * Operation authoring-shape migration.
+ *
+ * `defineOperation` / `defineStreamOperation` changed alongside the provider
+ * builder in 2.2.0-beta.37: the identity helper became a curried,
+ * context-typed factory.
+ *
+ *   before: defineOperation({ ...config })
+ *   after:  defineOperation<ProviderContext>()({ ...config })
+ *
+ * The old call still type-checks against an older pin, but under the new SDK
+ * it returns the INNER FACTORY FUNCTION with the config swallowed as an
+ * ignored argument, so every operation in the map becomes a function and the
+ * provider fails `finalizeProvider` with a misleading "declares neither
+ * healthCheck nor healthCheckUnsupported" error. Measured fleet blast radius
+ * (2026-08-29): 53 of 84 repositories, 450 legacy call sites.
+ *
+ * Same contract as the provider-shape transform: rewrite only what is fully
+ * understood, report a reasoned skip otherwise, never emit a partial file.
+ */
+
+export type OperationShapeMigration =
+	| {
+			readonly status: "migrated";
+			readonly code: string;
+			/** Number of call sites rewritten in this file. */
+			readonly rewrites: number;
+			/** True when a `ProviderContext` type import was added. */
+			readonly importAdded: boolean;
+	  }
+	| { readonly status: "unchanged"; readonly code: string }
+	| { readonly status: "skipped"; readonly reason: string };
+
+const OPERATION_HELPERS = new Set(["defineOperation", "defineStreamOperation"]);
+const PROVIDER_CONTEXT_TYPE_NAME = "ProviderContext";
+const PROVIDER_SDK_PROVIDER_SUBPATH = "@apifuse/provider-sdk/provider";
+
+/**
+ * Migrate legacy `defineOperation(config)` calls in one source file to the
+ * curried `defineOperation<ProviderContext>()(config)` form.
+ *
+ * @param contextImportSpecifier module specifier the `ProviderContext` type
+ * import should come from when one has to be added — `"../index"` for
+ * operation modules, `"./index"` is never needed because index.ts declares
+ * the alias itself. Callers pass the correct relative path per file.
+ */
+export function migrateOperationShape(
+	sourceText: string,
+	fileName: string,
+	contextImportSpecifier: string,
+): OperationShapeMigration {
+	const source = ts.createSourceFile(
+		fileName,
+		sourceText,
+		ts.ScriptTarget.Latest,
+		true,
+		ts.ScriptKind.TS,
+	);
+
+	const parseError = firstSyntaxError(source);
+	if (parseError !== undefined) {
+		return { status: "skipped", reason: parseError };
+	}
+
+	// Every legacy call site: a direct call to the bare helper identifier
+	// whose single argument is the config (i.e. NOT the curried form, whose
+	// outer call has zero arguments and optional type arguments).
+	const legacyCalls: TS.CallExpression[] = [];
+	let sawCurried = false;
+	const visit = (node: TS.Node): void => {
+		if (
+			ts.isCallExpression(node) &&
+			ts.isIdentifier(node.expression) &&
+			OPERATION_HELPERS.has(node.expression.text)
+		) {
+			if (node.arguments.length === 0) {
+				sawCurried = true; // already-migrated outer call
+			} else {
+				legacyCalls.push(node);
+			}
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+
+	if (legacyCalls.length === 0) {
+		return { status: "unchanged", code: sourceText };
+	}
+
+	// A file mixing both forms almost certainly had a partial hand-migration;
+	// refuse rather than guess which convention the author wants.
+	if (sawCurried) {
+		return {
+			status: "skipped",
+			reason:
+				"File mixes legacy defineOperation(config) with curried defineOperation<...>()(config); migrate it by hand.",
+		};
+	}
+
+	const declaresContextAlias = source.statements.some(
+		(statement) =>
+			ts.isTypeAliasDeclaration(statement) &&
+			statement.name.text === PROVIDER_CONTEXT_TYPE_NAME,
+	);
+	const importsContext = sourceText.includes(PROVIDER_CONTEXT_TYPE_NAME);
+	const needsImport = !declaresContextAlias && !importsContext;
+
+	const edits: { start: number; end: number; text: string }[] = [];
+	for (const call of legacyCalls) {
+		// `defineOperation(` -> `defineOperation<ProviderContext>()(`
+		const callee = call.expression;
+		edits.push({
+			start: callee.getEnd(),
+			end: callee.getEnd(),
+			text: `<${PROVIDER_CONTEXT_TYPE_NAME}>()`,
+		});
+	}
+
+	let importAdded = false;
+	if (needsImport) {
+		const lastImport = [...source.statements]
+			.reverse()
+			.find((statement) => ts.isImportDeclaration(statement));
+		const insertAt = lastImport ? lastImport.getEnd() : 0;
+		const importText = `${lastImport ? "\n" : ""}import type { ${PROVIDER_CONTEXT_TYPE_NAME} } from "${contextImportSpecifier}";${lastImport ? "" : "\n"}`;
+		edits.push({ start: insertAt, end: insertAt, text: importText });
+		importAdded = true;
+	}
+
+	const ordered = edits.sort((a, b) => b.start - a.start);
+	let code = sourceText;
+	for (const edit of ordered) {
+		code = code.slice(0, edit.start) + edit.text + code.slice(edit.end);
+	}
+
+	const verified = ts.createSourceFile(
+		fileName,
+		code,
+		ts.ScriptTarget.Latest,
+		true,
+		ts.ScriptKind.TS,
+	);
+	const outputError = firstSyntaxError(verified);
+	if (outputError !== undefined) {
+		return {
+			status: "skipped",
+			reason: `Transform produced source that does not parse (${outputError}); refusing to emit a partial migration.`,
+		};
+	}
+
+	return {
+		status: "migrated",
+		code,
+		rewrites: legacyCalls.length,
+		importAdded,
+	};
+}
+
+function firstSyntaxError(source: TS.SourceFile): string | undefined {
+	const diagnostics = (
+		source as TS.SourceFile & { parseDiagnostics?: TS.DiagnosticWithLocation[] }
+	).parseDiagnostics;
+	if (diagnostics === undefined || diagnostics.length === 0) return undefined;
+	const first = diagnostics[0];
+	if (first === undefined) return undefined;
+	const message = ts.flattenDiagnosticMessageText(first.messageText, " ");
+	const { line } = source.getLineAndCharacterOfPosition(first.start);
+	return `${message} (line ${line + 1})`;
+}