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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.43
+
+- Release candidate for main commit 5b8b6048514fb500ead400495bd5e1ed8695ed6d.
+
 ## 2.2.0-beta.42
 
 - Release candidate for main commit efbdbb409c9400e6211b061705b634e659f298bd.

package/bin/apifuse-check.ts

@@ -551,7 +551,7 @@ function isProviderDefinition(value: unknown): value is ProviderDefinition {
 	return (
 		typeof value.id === "string" &&
 		typeof value.version === "string" &&
-		(value.runtime === "standard" || value.runtime === "browser") &&
+		(value.runtime === "standard" || value.runtime === "shared" || value.runtime === "browser") &&
 		typeof value.meta.displayName === "string" &&
 		typeof value.meta.category === "string"
 	);

package/bin/apifuse-dev.ts

@@ -249,7 +249,7 @@ function isProviderDefinition(value: unknown): value is ProviderDefinition {
 	return (
 		typeof value.id === "string" &&
 		typeof value.version === "string" &&
-		(value.runtime === "standard" || value.runtime === "browser") &&
+		(value.runtime === "standard" || value.runtime === "shared" || value.runtime === "browser") &&
 		typeof value.meta.displayName === "string" &&
 		typeof value.meta.category === "string"
 	);

package/dist/cli/create.d.ts

@@ -1,7 +1,7 @@
 export declare const PROVIDER_NAME_REGEX: RegExp;
 export declare const CATEGORY_OPTIONS: readonly ["developer-tools", "finance", "commerce", "productivity", "marketing", "data", "communication", "other"];
 export declare const AUTH_MODE_OPTIONS: readonly ["none", "platform-managed", "credentials", "oauth2"];
-export declare const RUNTIME_OPTIONS: readonly ["standard", "browser"];
+export declare const RUNTIME_OPTIONS: readonly ["standard", "shared", "browser"];
 export declare const PRESET_OPTIONS: readonly ["standalone", "monorepo"];
 export type CreateCategory = (typeof CATEGORY_OPTIONS)[number];
 export type CreateAuthMode = (typeof AUTH_MODE_OPTIONS)[number];

package/dist/cli/create.js

@@ -19,7 +19,7 @@ export const CATEGORY_OPTIONS = [
     "other",
 ];
 export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"];
-export const RUNTIME_OPTIONS = ["standard", "browser"];
+export const RUNTIME_OPTIONS = ["standard", "shared", "browser"];
 export const PRESET_OPTIONS = ["standalone", "monorepo"];
 const CREATE_CONFIG_SCHEMA = z.object({
     authMode: z.enum(AUTH_MODE_OPTIONS).optional(),
@@ -46,7 +46,7 @@ Options:
   --display-name <name>
   --category <category>
   --auth-mode <mode>
-  --runtime <standard|browser>
+  --runtime <standard|shared|browser>
   --yes
   --dry-run
   --json

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

@@ -1685,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
@@ -1696,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.42",
+	"version": "2.2.0-beta.43",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

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/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

@@ -234,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>;
@@ -1072,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;
@@ -2413,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),
 	);
 }
 
@@ -2432,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),
 	);
 }
 
@@ -3131,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;
 	/**
@@ -3158,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();
 
@@ -3175,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,
@@ -3205,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;