@apifuse/provider-sdk 2.2.0-beta.35 → 2.2.0-beta.37

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.37
+
+- Release candidate for main commit aa14b268dffe1196f25c2b6b314598fe0896edec.
+
+## 2.2.0-beta.36
+
+- Release candidate for main commit c6858f8b87d78b3b755adeb28982e875434be406.
+
 ## 2.2.0-beta.35
 
 - Release candidate for main commit 027fa0087b883a6281bc6d8bdaaf6d0be382000f.

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/ceremonies/index.d.ts

@@ -1,8 +1,16 @@
+import type { AuthStartNoInputGuard } from "../define.js";
 import type { AuthFlowDefinition, AuthTurn } from "../types.js";
 type JsonObject = Record<string, unknown>;
 export declare const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
 export declare const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
 export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export declare function defineAuthFlow<const TFlow extends AuthFlowDefinition>(flow: TFlow & AuthStartNoInputGuard<TFlow>): TFlow;
 export declare function createOAuth2Ceremony(options: {
     authorizeUrl: string;
     tokenUrl: string;

package/dist/ceremonies/index.js

@@ -163,8 +163,17 @@ export function validateCeremonyOutput(turn) {
     }
     return turn;
 }
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export function defineAuthFlow(flow) {
+    return flow;
+}
 export function createOAuth2Ceremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
             getRequiredEnv(ctx, options.clientSecretEnvKey);
@@ -221,7 +230,7 @@ export function createOAuth2Ceremony(options) {
             });
         }, "OAuth token exchange failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
-    };
+    });
 }
 /**
  * Builds the start handler for a custom-scheme OAuth provider. The shared
@@ -272,7 +281,7 @@ export function createOAuth2ProxiedStart(options) {
     }, "OAuth2 proxied start failed", ctx);
 }
 export function createDeviceFlowCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const response = await ctx.http.post(options.deviceCodeUrl, {
                 client_id: getRequiredEnv(ctx, options.clientIdEnvKey),
@@ -330,10 +339,10 @@ export function createDeviceFlowCeremony(options) {
             });
         }, "Device flow polling failed", ctx),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
-    };
+    });
 }
 export function createWebAuthnCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const challenge = toBase64Url(randomBytes(32));
             ctx.context.set("__webauthn_challenge", challenge);
@@ -375,21 +384,23 @@ export function createWebAuthnCeremony(options) {
             });
         }, "WebAuthn verification failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
-    };
+    });
 }
 export function createMagicLinkCeremony(options) {
     const emailField = options.emailField ?? "email";
-    return {
-        start: (ctx, input = {}) => runCeremonyHandler(async () => {
+    const buildEmailForm = () => buildJsonSchemaForm({
+        type: "object",
+        required: [emailField],
+        properties: {
+            [emailField]: { type: "string", format: "email" },
+        },
+    }, "Provide the email address to receive a magic link.");
+    return defineAuthFlow({
+        start: (ctx) => runCeremonyHandler(async () => buildEmailForm(), "Magic link start failed", ctx),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const email = getString(input, emailField);
             if (!email) {
-                return buildJsonSchemaForm({
-                    type: "object",
-                    required: [emailField],
-                    properties: {
-                        [emailField]: { type: "string", format: "email" },
-                    },
-                }, "Provide the email address to receive a magic link.");
+                return buildEmailForm();
             }
             await ctx.http.post(options.sendUrl, { email });
             ctx.context.set(MAGIC_LINK_KEY, {
@@ -401,11 +412,7 @@ export function createMagicLinkCeremony(options) {
                 hint: "Check your email for the magic link, then poll for completion.",
                 timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
             });
-        }, "Magic link start failed", ctx, input),
-        continue: async () => validateCeremonyOutput(createTurn("poll", {
-            hint: "Continue polling for magic link completion.",
-            timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
-        })),
+        }, "Magic link continuation failed", ctx, input),
         poll: (ctx) => runCeremonyHandler(async () => {
             const state = getNestedRecord(ctx, MAGIC_LINK_KEY);
             const email = getString(state, "email");
@@ -431,10 +438,10 @@ export function createMagicLinkCeremony(options) {
             });
         }, "Magic link polling failed", ctx),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
-    };
+    });
 }
 export function createFormCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: async () => validateCeremonyOutput(buildJsonSchemaForm(options.schema, options.hint ?? "Provide the required input to continue.")),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const { prevalidate } = await import("../runtime/prevalidate.js");
@@ -452,7 +459,7 @@ export function createFormCeremony(options) {
             });
         }, "Form submission failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
-    };
+    });
 }
 export function combineCeremonies(...ceremonies) {
     function getStage(ctx) {
@@ -504,7 +511,7 @@ export function combineCeremonies(...ceremonies) {
 }
 export function createSwitchCeremony(options) {
     const choiceKeys = Object.keys(options.choices);
-    return {
+    return defineAuthFlow({
         start: async () => validateCeremonyOutput(createTurn("multi_choice", {
             data: { choices: choiceKeys },
             hint: options.prompt ?? "Choose an authentication method.",
@@ -550,5 +557,5 @@ export function createSwitchCeremony(options) {
             }
             return createTurn("abort", { hint: "Switch ceremony aborted." });
         }, "Switch ceremony abort failed", ctx),
-    };
+    });
 }

package/dist/cli/templates/provider/Dockerfile.tpl

@@ -1,6 +1,6 @@
 FROM oven/bun:1.2-alpine
 WORKDIR /provider
-COPY package.json bun.lockb* ./
+COPY package.json bun.lock ./
 RUN bun install --frozen-lockfile
 COPY . .
 EXPOSE 3000

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/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,36 +10,39 @@ 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 AuthStartNoInputGuard<TConfig> = TConfig extends {
+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;
+} : unknown;
+export type AuthStartNoInputGuard<TConfig> = TConfig extends {
     auth?: {
         flow?: {
             start: infer TStart;
         };
     };
-} ? TStart extends (...args: infer TArgs) => unknown ? TArgs extends [unknown] ? unknown : {
-    "auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
-} : unknown : unknown;
-export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
+} ? AuthStartHandlerNoInputGuard<TStart> : TConfig extends {
+    start: infer TStart;
+} ? AuthStartHandlerNoInputGuard<TStart> : unknown;
+export interface ProviderDeclaration {
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
@@ -50,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?: {
@@ -64,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;
@@ -90,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;
@@ -108,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 {};