@apifuse/provider-sdk 2.2.0-beta.36 → 2.2.0-beta.38

package/AUTHORING.md

@@ -104,7 +104,14 @@ description:
 
 ### Factored operations
 
-Use `defineOperation()` when an operation is large enough to live beside helper functions or in a separate module. It preserves the same type inference as inline `defineProvider()` operations and can be placed directly in the provider `operations` map. `defineProvider()` accepts Zod and Standard Schema v1-compatible schemas. If config validation fails, the SDK names the field to fix, for example `runtime`, `auth.mode`, `operations.<id>.handler`, or `operations.<id>.fixtures.response`.
+`defineProvider(declaration)` returns the builder that accepts `operations`, so
+inline handlers are typed only after capability declarations are fixed. Export
+`ProviderContextOf<typeof buildProvider>` once from the provider entry point.
+Separate operation files import that provider context and call
+`defineOperation<ProviderContext>()({...})`; helpers should accept the one SDK
+client they use rather than the provider context. Zod and Standard Schema v1
+schemas retain input/output inference. Invalid configs name the offending field,
+such as `auth.mode` or `operations.<id>.fixtures.response`.
 
 ### Replay-safe fixtures
 
@@ -236,8 +243,9 @@ level, then call `ctx.stt` from operation handlers or auth-flow handlers.
 ```ts
 export default defineProvider({
   id: "example-provider",
-  // ...metadata, auth, operations, allowedHosts
+  // ...metadata, auth, allowedHosts
   stt: { mode: "required" },
+})({
   operations: {
     verifyAudioOtp: {
       input: z.object({
@@ -357,11 +365,13 @@ const paymentWebviewJourney = defineHealthJourney({
 	],
 });
 
-export default defineProvider({
+const buildProvider = defineProvider({
 	id: "example-provider",
-	// ...metadata, auth, operations, allowedHosts
+	// ...metadata, auth, allowedHosts
 	healthJourneys: [paymentWebviewJourney],
 });
+
+export default buildProvider({ operations });
 ```
 <!-- @magic-end:sample -->
 
@@ -604,7 +614,7 @@ failures are sanitized before propagation.
   HTML, or upstream `Error` objects.
 
 ```ts
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "example-provider",
   version: "1.0.0",
   runtime: "standard",
@@ -638,8 +648,10 @@ export default defineProvider({
     },
   },
   credential: { keys: ["cookie"] },
-  // ...metadata and operations
+  // ...metadata
 });
+
+export default buildProvider({ operations });
 ```
 
 - Credentials auth providers should use `defineCredentialsAuth()` instead of
@@ -666,15 +678,17 @@ const credentialsAuth = defineCredentialsAuth({
   },
 });
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "example-provider",
   version: "1.0.0",
   runtime: "standard",
   auth: credentialsAuth.auth,
   credential: credentialsAuth.credential,
   context: credentialsAuth.context,
-  // ...metadata and operations
+	// ...metadata
 });
+
+export default buildProvider({ operations });
 ```
 
 For OTP, MFA, CAPTCHA handoff, or user-approved login, return a challenge from

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.38
+
+- Release candidate for main commit 448775077dbc9ab907209f1feee4e6e4e5ef4283.
+
+## 2.2.0-beta.37
+
+- Release candidate for main commit aa14b268dffe1196f25c2b6b314598fe0896edec.
+
 ## 2.2.0-beta.36
 
 - Release candidate for main commit c6858f8b87d78b3b755adeb28982e875434be406.

package/README.md

@@ -196,12 +196,28 @@ the bad request path; provider/runtime failures include `code`, `message`, and
 
 ## Authoring ergonomics
 
-`defineProvider()` infers each operation handler input from the operation `input` schema. For larger providers, factor operations with `defineOperation()` and compose them later:
+`defineProvider()` establishes the capability declaration before its returned
+builder contextually types operations. For larger providers, export the derived
+context once and use it with `defineOperation()` in separate files:
 
 ```ts
-import { defineOperation, defineProvider, z } from "@apifuse/provider-sdk/provider"
+import {
+  defineOperation,
+  defineProvider,
+  type ProviderContextOf,
+  z,
+} from "@apifuse/provider-sdk/provider"
+
+const buildProvider = defineProvider({
+  id: "factored-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  meta: { displayName: "Factored", category: "demo" },
+})
 
-const search = defineOperation({
+export type ProviderContext = ProviderContextOf<typeof buildProvider>
+
+const search = defineOperation<ProviderContext>()({
   input: z.object({ q: z.string().describe("Search query") }),
   output: z.object({ count: z.number().describe("Result count") }),
   async handler(ctx, input) {
@@ -212,11 +228,7 @@ const search = defineOperation({
   },
 })
 
-export default defineProvider({
-  id: "factored-provider",
-  version: "1.0.0",
-  runtime: "standard",
-  meta: { displayName: "Factored", category: "demo" },
+export default buildProvider({
   operations: { search },
 })
 ```

package/bin/apifuse-dev.ts

@@ -129,7 +129,7 @@ export function createProviderContext(provider: ProviderDefinition): {
 			credential,
 			state,
 		}),
-	};
+	} satisfies Omit<ProviderContext, "native"> as unknown as ProviderContext;
 
 	return { ctx };
 }

package/bin/apifuse-pack-types.ts

@@ -77,6 +77,7 @@ const NEGATIVE_CONTROLS = [
 			'\truntime: "standard",',
 			'\tresolver: { vendors: ["unknown-vendor"], kinds: ["turnstile"] },',
 			'\tmeta: { displayName: "Invalid Resolver Vendor", descriptionKey: "meta.description", category: "test" },',
+			"})({",
 			"\toperations: {",
 			"\t\tprobe: {",
 			"\t\t\tinput: z.object({}),",
@@ -381,7 +382,7 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 		[
 			'import { defineProvider, ProviderError, resolveProxy, SessionExpiredError, z } from "@apifuse/provider-sdk";',
 			'import { invalidateResolverSolution } from "@apifuse/provider-sdk/runtime/resolver";',
-			'import type { BrowserCookie, ChallengeSolution, NativeNetworkClient, NativeNetworkConnection, NativeProviderConfig, NativeProviderContext, NativeTcpEgressGrant, ProviderChallenge, ProviderContext, ProviderFileRef, ProviderFilesContext, ProviderResolvedFile, ProviderResolverConfig, ResolverContext, ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
+			'import type { BrowserCookie, ChallengeSolution, NativeContext, NativeNetworkClient, NativeNetworkConnection, NativeProviderConfig, NativeTcpEgressGrant, ProviderChallenge, ProviderContext, ProviderFileRef, ProviderFilesContext, ProviderResolvedFile, ProviderResolverConfig, ResolverContext, ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
 			'import type { ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, RequestOptions, ResolvedProxyConfig } from "@apifuse/provider-sdk";',
 			'import { defineCredentialsAuth } from "@apifuse/provider-sdk/provider";',
 			'import type { NativeNetworkClient as ProviderEntryNativeNetworkClient, ProviderFilesContext as ProviderEntryFilesContext } from "@apifuse/provider-sdk/provider";',
@@ -415,12 +416,12 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			"const connection: NativeNetworkConnection = { read: async () => null, write: async () => {}, close: async () => {} };",
 			"const network: NativeNetworkClient = { connectTcp: async () => connection, connectTls: async () => connection, grantTcpEgress: () => ({ revoke() {} }) };",
 			"const providerEntryNetwork: ProviderEntryNativeNetworkClient = network;",
-			"const nativeContext: NativeProviderContext = { network };",
+			"const nativeContext: NativeContext = { network };",
 			'const grant: NativeTcpEgressGrant = network.grantTcpEgress({ sourceHost: "booking-loco.kakao.com", sourcePort: 443, host: "loco.kakao.com", port: 5228, tls: "disabled" });',
 			'const nativeConfig: NativeProviderConfig = { network: { tcp: [{ host: "booking-loco.kakao.com", ports: [443], tls: "required" }] } };',
 			"const providerContext = undefined as unknown as ProviderContext;",
 			"const optionalFiles: ProviderFilesContext | undefined = providerContext.files;",
-			"const optionalNative: NativeProviderContext | undefined = providerContext.native;",
+			"const native: NativeContext = providerContext.native;",
 			"export const providerResolver: ResolverContext = providerContext.resolver;",
 			'export const resolverRuntimeOptions: ResolverRuntimeOptions = { allowedHosts: ["example.com"], cache: providerContext.cache };',
 			"",
@@ -435,7 +436,7 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			'export const cookieSolution: ChallengeSolution = { form: "cookies", cookies: { cf_clearance: "clearance" }, userAgent: "fixture-agent" };',
 			"export const invalidation = invalidateResolverSolution(providerContext.resolver, awsWafChallenge, cookieSolution);",
 			'export const resolverConfig: ProviderResolverConfig = { vendors: ["browser", "capsolver"], kinds: ["cloudflare_interstitial", "turnstile"] };',
-			'export const resolverProvider = defineProvider({ id: "pack-types-resolver", version: "1.0.0", runtime: "standard", resolver: resolverConfig, meta: { displayName: "Pack Types Resolver", descriptionKey: "meta.description", category: "test" }, operations: { probe: { input: z.object({}), output: z.object({ ok: z.boolean() }), handler: async () => ({ ok: true }), healthCheckUnsupported: { reason: "type fixture" } } } });',
+			'export const resolverProvider = defineProvider({ id: "pack-types-resolver", version: "1.0.0", runtime: "standard", resolver: resolverConfig, meta: { displayName: "Pack Types Resolver", descriptionKey: "meta.description", category: "test" } })({ operations: { probe: { input: z.object({}), output: z.object({ ok: z.boolean() }), handler: async () => ({ ok: true }), healthCheckUnsupported: { reason: "type fixture" } } } });',
 			"export const resolverContext: ResolverContext = { solve: async () => tokenSolution };",
 			'export const browserCookie: BrowserCookie = { name: "persistent-id", value: "persistent-token", domain: "example.com", path: "/", expires: 1786698176, httpOnly: true, secure: true };',
 			'const browserPage = undefined as unknown as Awaited<ReturnType<ProviderContext["browser"]["newPage"]>>;',
@@ -465,7 +466,7 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			"	grant,",
 			"	nativeConfig,",
 			"	optionalFiles,",
-			"	optionalNative,",
+			"	native,",
 			"	browserCookie,",
 			"	browserCookies,",
 			"	queryCredentialOptions,",

package/bin/apifuse-record.ts

@@ -581,7 +581,7 @@ export function createCaptureContext(
 			credential,
 			state,
 		}),
-	};
+	} satisfies Omit<ProviderContext, "native"> as unknown as ProviderContext;
 
 	return {
 		ctx,

package/bin/apifuse-submit-check.ts

@@ -1196,18 +1196,31 @@ function scoreFlatOperationComposition(providerRoot: string): SubmitCheck {
 		);
 	}
 
-	// Scope the scan to the argument of the EXPORTED `defineProvider(...)` call.
+	// Scope the scan to the exported provider builder's implementation argument,
+	// or to the legacy-looking declaration call used by structural test fixtures.
 	// A provider can contain helper/non-exported defineProvider calls before the
 	// real default export (e.g. test scaffolds), so resolve the default export
 	// rather than blindly taking the first regex match. Resolution order:
-	//   1. `export default defineProvider(` — inline default export
-	//   2. `export default <ident>` then `const <ident> = defineProvider(`
-	//   3. fallback: first `defineProvider(` in the file
+	//   1. `export default <builder>(` — phase-separated provider
+	//   2. `export default defineProvider(` — structural fixture
+	//   3. `export default <ident>` then `const <ident> = defineProvider(`
+	//   4. fallback: first `defineProvider(` in the file
 	let defineParenIndex = -1;
+	const builderDefault = /\bexport\s+default\s+([A-Za-z_$][\w$]*)\s*\(/.exec(source);
+	if (builderDefault?.[1] !== undefined && builderDefault[1] !== "defineProvider") {
+		defineParenIndex = builderDefault.index + builderDefault[0].length - 1;
+	}
 	const inlineDefault = /\bexport\s+default\s+defineProvider\s*\(/.exec(source);
-	if (inlineDefault) {
-		defineParenIndex = inlineDefault.index + inlineDefault[0].length - 1; // points at `(`
-	} else {
+	if (defineParenIndex === -1 && inlineDefault) {
+		const declarationParen = inlineDefault.index + inlineDefault[0].length - 1;
+		const declarationStart = declarationParen + 1;
+		const declaration = balancedValueExpression(source, declarationStart);
+		let cursor = declarationStart + declaration.length;
+		while (/\s/.test(source[cursor] ?? "")) cursor++;
+		if (source[cursor] === ")") cursor++;
+		while (/\s/.test(source[cursor] ?? "")) cursor++;
+		defineParenIndex = source[cursor] === "(" ? cursor : declarationParen;
+	} else if (defineParenIndex === -1) {
 		const namedDefault = /\bexport\s+default\s+([A-Za-z_$][\w$]*)\s*;?/.exec(source);
 		const exportedName = namedDefault?.[1];
 		if (exportedName !== undefined) {
@@ -1236,7 +1249,7 @@ function scoreFlatOperationComposition(providerRoot: string): SubmitCheck {
 	const argStart = defineParenIndex + 1;
 	const argText = balancedValueExpression(source, argStart);
 
-	// Resolve the value passed as `operations:` inside the defineProvider call,
+	// Resolve the value passed as `operations:` inside the implementation call,
 	// following one alias hop. The value is classified as a static object
 	// literal (pass) or a factory/call expression (block). The regex index is
 	// offset back into the full source so line numbers stay accurate.
@@ -1249,7 +1262,7 @@ function scoreFlatOperationComposition(providerRoot: string): SubmitCheck {
 		opsLine = offsetToLine(source, valueStart);
 	}
 
-	// Property shorthand: `defineProvider({ ..., operations })` — resolve the
+	// Property shorthand: `buildProvider({ operations })` — resolve the
 	// local `operations` const initializer.
 	let aliasName: string | undefined;
 	if (opsValue === undefined) {
@@ -1395,7 +1408,7 @@ function scoreFlatOperationComposition(providerRoot: string): SubmitCheck {
 			blockerMessage:
 				"defineProvider operations are composed by a factory call instead of a static object literal.",
 			remediation:
-				"Declare operations as a static literal: defineProvider({ operations: { 'op-id': defineOperation({...}) } }). The provider-registry AST gate requires static runtime/operations; factory composition fails the registry build. If composition is unavoidable, add `// @apifuse-allow flat-operation-composition: <reason>`.",
+				"Declare operations as a static literal in the provider builder call. The provider-registry AST gate requires static runtime/operations; factory composition fails the registry build. If composition is unavoidable, add `// @apifuse-allow flat-operation-composition: <reason>`.",
 			passMessage: "defineProvider declares operations as a static object literal.",
 		});
 	}

package/dist/cli/templates/provider/index.ts.tpl

@@ -1,9 +1,9 @@
-import { defineProvider } from "@apifuse/provider-sdk/provider";
+import { defineProvider, type ProviderContextOf } from "@apifuse/provider-sdk/provider";
 
 import { providerMeta } from "./meta";
 import { operations } from "./operations";
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "{{PROVIDER_ID}}",
   version: "1.0.0",
   runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
@@ -11,5 +11,8 @@ export default defineProvider({
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
   meta: providerMeta,
-  operations: operations,
 });
+
+export type ProviderContext = ProviderContextOf<typeof buildProvider>;
+
+export default buildProvider({ operations });

package/dist/cli/templates/provider/operations/ping.ts.tpl

@@ -1,8 +1,9 @@
 import { defineOperation } from "@apifuse/provider-sdk/provider";
+import type { ProviderContext } from "../index";
 
 import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
 
-export const pingOperation = defineOperation({
+export const pingOperation = defineOperation<ProviderContext>()({
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,

package/dist/declaration-validation.d.ts

@@ -4,6 +4,8 @@ export declare const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
 export declare const DECLARATION_RULE_IDS: {
     readonly challengeShape: "credentials-challenge-shape";
     readonly journeyExecutable: "health-journey-executable";
+    readonly journeyRunScenarioExclusive: "health-journey-run-scenario-exclusive";
+    readonly journeyScenarioValid: "health-journey-scenario-valid";
     readonly schemaSerializable: "operation-schema-serializable";
     readonly proxyExplicitPolicy: "proxy-explicit-policy";
     readonly proxyVendorExclusive: "proxy-vendor-fields-exclusive";

package/dist/declaration-validation.js

@@ -1,9 +1,12 @@
 import { describeSchema } from "./contract-serialization.js";
 import { ProviderError } from "./errors.js";
+import { HealthScenarioSchema } from "./health-scenario.js";
 export const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
 export const DECLARATION_RULE_IDS = {
     challengeShape: "credentials-challenge-shape",
     journeyExecutable: "health-journey-executable",
+    journeyRunScenarioExclusive: "health-journey-run-scenario-exclusive",
+    journeyScenarioValid: "health-journey-scenario-valid",
     schemaSerializable: "operation-schema-serializable",
     proxyExplicitPolicy: "proxy-explicit-policy",
     proxyVendorExclusive: "proxy-vendor-fields-exclusive",
@@ -35,15 +38,38 @@ function validateHealthDeclaration(provider, violations) {
     for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
         if (!journey || typeof journey !== "object")
             continue;
-        if (typeof journey.run !== "function") {
+        const hasRun = journey.run !== undefined;
+        const hasScenario = journey.scenario !== undefined;
+        if (hasRun && hasScenario) {
+            const journeyPath = healthJourneyPath(journey, index);
+            violations.push({
+                ruleId: DECLARATION_RULE_IDS.journeyRunScenarioExclusive,
+                path: journeyPath,
+                message: "A health journey must declare exactly one of run or scenario, not both.",
+                fix: `Remove either ${journeyPath}.run or ${journeyPath}.scenario.`,
+            });
+        }
+        if (!hasRun && !hasScenario) {
             const journeyPath = healthJourneyPath(journey, index);
             violations.push({
                 ruleId: DECLARATION_RULE_IDS.journeyExecutable,
                 path: `${journeyPath}.run`,
-                message: "coversOperations cannot provide health coverage without executable run logic.",
-                fix: `Add an async run(ctx) implementation to ${journeyPath}.`,
+                message: "coversOperations cannot provide health coverage without run or a declarative scenario.",
+                fix: `Add an async run(ctx) implementation or a valid scenario to ${journeyPath}.`,
             });
         }
+        if (hasScenario) {
+            const parsed = HealthScenarioSchema.safeParse(journey.scenario);
+            if (!parsed.success) {
+                const journeyPath = healthJourneyPath(journey, index);
+                violations.push({
+                    ruleId: DECLARATION_RULE_IDS.journeyScenarioValid,
+                    path: `${journeyPath}.scenario`,
+                    message: "scenario must conform to HealthScenario.",
+                    fix: "Build the scenario with defineHealthScenario().",
+                });
+            }
+        }
     }
     // NOTE: healthCheck.cases[].enabled is intentionally NOT validated here.
     // self-test.ts reports a gated case as status "skipped" with skipReason

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderOcrConfig, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderContext, ProviderContextFor, ProviderOcrConfig, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -10,25 +10,25 @@ interface ProviderImplementationProfile {
 }
 export declare const VALID_PROVIDER_RESOLVER_VENDORS: readonly ["browser", "capsolver", "capmonster", "2captcha", "custom"];
 export declare const VALID_PROVIDER_CHALLENGE_KINDS: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
-type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
-type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationDefinition<TInput, TOutput>, "handler"> & {
-    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
+type ProviderOperation = OperationDefinition<any, any, any>;
+type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike, TContext = ProviderContext> = Omit<OperationDefinition<TInput, TOutput, TContext>, "handler"> & {
+    handler(ctx: TContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
 };
-type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> = {
-    [K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput> ? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput> : never;
+type OperationMapConfig<TOperations extends Record<string, ProviderOperation>, TContext = ProviderContext> = {
+    [K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput> ? OperationConfig<TInput, TOutput, TContext> | OperationDefinition<TInput, TOutput, TContext> : never;
 };
-type StreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = SseOperationConfig<TInput, TOutput> | HttpStreamOperationConfig<TInput, TOutput> | WebSocketOperationConfig<TInput, TOutput>;
-type SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationConfig<TInput, TOutput>, "handler" | "transport"> & {
+type StreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike, TContext = ProviderContext> = SseOperationConfig<TInput, TOutput, TContext> | HttpStreamOperationConfig<TInput, TOutput, TContext> | WebSocketOperationConfig<TInput, TOutput, TContext>;
+type SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike, TContext = ProviderContext> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
     transport: OperationSseTransport;
-    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): AsyncIterable<ProviderStreamEvent> | Promise<AsyncIterable<ProviderStreamEvent>>;
+    handler(ctx: TContext, input: InferSchemaOutput<TInput>): AsyncIterable<ProviderStreamEvent> | Promise<AsyncIterable<ProviderStreamEvent>>;
 };
-type HttpStreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationConfig<TInput, TOutput>, "handler" | "transport"> & {
+type HttpStreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike, TContext = ProviderContext> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
     transport: OperationHttpStreamTransport;
-    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
+    handler(ctx: TContext, input: InferSchemaOutput<TInput>): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
-type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationConfig<TInput, TOutput>, "handler" | "transport"> & {
+type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike, TContext = ProviderContext> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
     transport: OperationWebSocketTransport;
-    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
+    handler(ctx: TContext, input: InferSchemaOutput<TInput>): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
 type AuthStartHandlerNoInputGuard<TStart> = TStart extends (...args: infer TArgs) => unknown ? TArgs["length"] extends 0 | 1 ? unknown : {
     "auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
@@ -42,7 +42,7 @@ export type AuthStartNoInputGuard<TConfig> = TConfig extends {
 } ? AuthStartHandlerNoInputGuard<TStart> : TConfig extends {
     start: infer TStart;
 } ? AuthStartHandlerNoInputGuard<TStart> : unknown;
-export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
+export interface ProviderDeclaration {
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
@@ -53,6 +53,8 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
      * resolves omitted fields against the runtime deployment profiles.
      */
     deployment?: ProviderDeploymentOverrides;
+    /** Declares that provider operations use the SDK HTTP client. */
+    http?: true;
     allowedHosts?: string[];
     native?: NativeProviderConfig;
     stealth?: {
@@ -67,11 +69,21 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
         engine: BrowserEngine;
     };
     auth?: AuthConfig;
+    /** Declares that provider operations issue and consume SDK choice tokens. */
+    choice?: true;
     reviewed?: ProviderReviewed;
     access?: ProviderAccessConfig;
     secrets?: ProviderSecretDeclaration[];
+    /** Declares that provider operations read SDK-managed environment values. */
+    env?: true;
     credential?: CredentialDeclaration;
     context?: ContextDeclaration;
+    /** Declares that provider operations use SDK-managed persistent state. */
+    state?: true;
+    /** Declares that provider operations use the SDK provider cache. */
+    cache?: true;
+    /** Declares that provider operations access runtime-resolvable files. */
+    files?: true;
     meta: {
         displayName: string;
         displayNameKey?: string;
@@ -93,16 +105,15 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
             publicSchemaFieldNames?: "normalized";
         };
     };
-    operations: OperationMapConfig<TOperations>;
     healthMonitor?: ProviderHealthMonitorConfig;
     /** New name for `healthMonitor` (transitional alias); declaring both is a ValidationError. */
     healthProbe?: ProviderHealthMonitorConfig;
     healthJourneys?: readonly HealthJourneyDefinition[];
 }
-/** Define one provider operation with schema-driven handler inference. */
-export declare function defineOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(operation: OperationConfig<TInput, TOutput>): OperationDefinition<TInput, TOutput>;
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export declare function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(operation: StreamOperationConfig<TInput, TOutput>): OperationDefinition<TInput, TOutput>;
+/** Define one factored provider operation with schema-driven handler inference. */
+export declare function defineOperation<TContext>(): <TInput extends SchemaLike, TOutput extends SchemaLike>(config: OperationConfig<TInput, TOutput, TContext>) => OperationDefinition<TInput, TOutput, TContext>;
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export declare function defineStreamOperation<TContext>(): <TInput extends SchemaLike, TOutput extends SchemaLike>(config: StreamOperationConfig<TInput, TOutput, TContext>) => OperationDefinition<TInput, TOutput, TContext>;
 export declare function every(interval: string, options?: {
     jitter?: string;
     randomize?: HealthScheduleRandomization;
@@ -111,7 +122,14 @@ export declare function centered(maxOffset: string): HealthScheduleRandomization
 export declare function delayed(maxDelay: string): HealthScheduleRandomization;
 export declare function defineSmsOtpMatcher(config: Omit<SmsOtpMatcherDefinition, "extractOtp">): SmsOtpMatcherDefinition;
 export declare function defineHealthJourney(config: HealthJourneyDefinition): HealthJourneyDefinition;
-export declare function defineProvider<TOperations extends Record<string, ProviderOperation>, TConfig extends ProviderConfig<TOperations>>(config: TConfig & AuthStartNoInputGuard<TConfig>): ProviderDefinition & {
-    operations: OperationMapConfig<TOperations>;
+/** The second authoring phase for a declaration established by defineProvider. */
+export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <TOperations extends Record<string, ProviderOperation>>(implementation: {
+    operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+}) => ProviderDefinition & {
+    operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
 };
+/** Extract the declaration-derived operation context from a provider builder. */
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TDeclaration> ? ProviderContextFor<TDeclaration> : never;
+/** 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/define.js

@@ -449,13 +449,17 @@ function authStartHasHiddenInput(start) {
         return false;
     return /\s=\s/.test(second);
 }
-/** Define one provider operation with schema-driven handler inference. */
-export function defineOperation(operation) {
-    return operation;
+/** Define one factored provider operation with schema-driven handler inference. */
+export function defineOperation() {
+    return function operation(config) {
+        return config;
+    };
 }
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation(operation) {
-    return operation;
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export function defineStreamOperation() {
+    return function streamOperation(config) {
+        return config;
+    };
 }
 function assertObjectConfig(value) {
     if (!value || typeof value !== "object") {
@@ -558,6 +562,11 @@ function validateProviderShape(config) {
     assertRequiredField(config, "operations", String(config.id));
     if (typeof config.runtime === "string")
         assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
+    if (config.native !== undefined && config.runtime === "browser") {
+        throw new ValidationError(`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`, {
+            fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
+        });
+    }
     const auth = config.auth;
     if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
         assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
@@ -780,7 +789,9 @@ function validateProviderResolver(config) {
         });
     }
     rejectUnknownFields(resolver, new Set(["vendors", "kinds", "clientProfile"]), "resolver", config.id);
-    validateResolverLiteralArray(resolver.vendors, "resolver.vendors", VALID_PROVIDER_RESOLVER_VENDORS, config.id);
+    if (resolver.vendors !== undefined) {
+        validateResolverLiteralArray(resolver.vendors, "resolver.vendors", VALID_PROVIDER_RESOLVER_VENDORS, config.id);
+    }
     validateResolverLiteralArray(resolver.kinds, "resolver.kinds", VALID_PROVIDER_CHALLENGE_KINDS, config.id);
     if (resolver.clientProfile !== undefined &&
         (typeof resolver.clientProfile !== "string" || !resolver.clientProfile.trim())) {
@@ -1402,6 +1413,7 @@ const HEALTH_JOURNEY_FIELDS = new Set([
     "manualTrigger",
     "steps",
     "run",
+    "scenario",
 ]);
 const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter", "randomize"]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
@@ -1824,6 +1836,10 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
         }
         if (journey.manualTrigger !== undefined)
             validateHealthJourneyManualTrigger(providerId, journey.id, journey.manualTrigger);
+        if (journey.scenario !== undefined && journey.smsMatchers !== undefined)
+            throw new ValidationError(`Provider "${providerId}" healthJourneys.${journey.id}.smsMatchers is not allowed on declarative scenarios.`);
+        if (journey.scenario !== undefined && journey.requiredSecrets !== undefined)
+            throw new ValidationError(`Provider "${providerId}" healthJourneys.${journey.id}.requiredSecrets is not allowed on declarative scenarios.`);
         if (journey.timeout !== undefined)
             assertIsoDuration(journey.timeout, `Provider "${providerId}" healthJourneys.${journey.id}.timeout`);
         if (journey.cooldown !== undefined)
@@ -1933,7 +1949,15 @@ function validateProviderDeployment(providerId, deployment) {
             fix: 'Pass deployment: { runtime: "shared" | "dedicated" | "browser", ... } or remove the field',
         });
 }
-export function defineProvider(config) {
+/** Establish a provider declaration before its operations are contextually typed. */
+export function defineProvider(declaration) {
+    const buildProvider = (implementation) => finalizeProvider({
+        ...declaration,
+        ...implementation,
+    });
+    return buildProvider;
+}
+function finalizeProvider(config) {
     validateProviderShape(config);
     const operations = resolveOperationFixtureRequests(config.operations);
     if (!CONNECTOR_ID_REGEX.test(config.id))
@@ -2000,7 +2024,7 @@ export function defineProvider(config) {
         credential: config.credential,
         context: config.context,
         meta: config.meta,
-        operations,
+        operations: operations,
         // Transitional healthMonitor → healthProbe alias: mirror whichever field
         // was declared onto both so old and new consumers keep working.
         healthMonitor: config.healthMonitor ?? config.healthProbe,