@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/dist/contract-serialization.js

@@ -54,15 +54,11 @@ function isZodSchema(schema) {
     return schema instanceof z.ZodType;
 }
 function zodJsonSchema(schema) {
-    try {
-        const jsonSchema = z.toJSONSchema(schema);
-        return toJsonValue(jsonSchema);
-    }
-    catch (error) {
-        if (error instanceof Error)
-            return undefined;
-        throw error;
+    const jsonSchema = toJsonValue(z.toJSONSchema(schema));
+    if (jsonSchema === undefined) {
+        throw new TypeError("z.toJSONSchema() returned a non-JSON value");
     }
+    return jsonSchema;
 }
 function getSchemaTypeName(schema) {
     if (!isRecord(schema))

package/dist/contract-types.d.ts

@@ -11,6 +11,7 @@ export interface ProviderContractSnapshot {
     readonly allowedHosts?: readonly string[];
     readonly stealth?: JsonValue;
     readonly proxy?: JsonValue;
+    readonly ocr?: JsonValue;
     readonly stt?: JsonValue;
     readonly browser?: JsonValue;
     readonly auth?: JsonValue;

package/dist/contract.js

@@ -7,6 +7,7 @@ export function extractProviderContract(provider) {
     const auth = extractAuth(provider.auth);
     const stealth = toJsonValue(provider.stealth);
     const proxy = toJsonValue(provider.proxy);
+    const ocr = toJsonValue(provider.ocr);
     const stt = toJsonValue(provider.stt);
     const browser = toJsonValue(provider.browser);
     const reviewed = toJsonValue(provider.reviewed);
@@ -30,6 +31,7 @@ export function extractProviderContract(provider) {
         ...(provider.allowedHosts ? { allowedHosts: [...provider.allowedHosts].sort() } : {}),
         ...(stealth === undefined ? {} : { stealth }),
         ...(proxy === undefined ? {} : { proxy }),
+        ...(ocr === undefined ? {} : { ocr }),
         ...(stt === undefined ? {} : { stt }),
         ...(browser === undefined ? {} : { browser }),
         ...(auth === undefined ? {} : { auth }),

package/dist/declaration-validation.d.ts

@@ -0,0 +1,32 @@
+import { ProviderError } from "./errors.js";
+import type { ProviderDefinition } from "./types.js";
+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";
+    readonly proxyNoMixedVendors: "proxy-no-mixed-vendors";
+    readonly proxySmartproxyGeo: "proxy-smartproxy-country-only";
+    readonly operationUpstreamProxy: "operation-upstream-proxy-unsupported";
+};
+export type DeclarationRuleId = (typeof DECLARATION_RULE_IDS)[keyof typeof DECLARATION_RULE_IDS];
+export type DeclarationViolation = {
+    ruleId: DeclarationRuleId;
+    path: string;
+    message: string;
+    fix: string;
+};
+export declare function declarationInvalidError(violations: readonly DeclarationViolation[]): ProviderError;
+/** Enforces declaration rules whose runtime behavior would otherwise fail open. */
+export declare function validateFailClosedDeclaration(provider: ProviderDefinition): void;
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "proxy">;
+type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export declare function validateFailClosedProviderDeclaration(provider: ProviderDeclarationRulesInput): void;
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export declare function validateFailClosedOperationDeclaration(provider: OperationDeclarationRulesInput): void;
+export {};

package/dist/declaration-validation.js

@@ -0,0 +1,207 @@
+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",
+    proxyNoMixedVendors: "proxy-no-mixed-vendors",
+    proxySmartproxyGeo: "proxy-smartproxy-country-only",
+    operationUpstreamProxy: "operation-upstream-proxy-unsupported",
+};
+export function declarationInvalidError(violations) {
+    const summary = violations
+        .map((violation) => `${violation.path} [${violation.ruleId}]: ${violation.message}`)
+        .join("\n");
+    return new ProviderError(`Provider declaration is invalid (${violations.length} violation${violations.length === 1 ? "" : "s"}).${summary ? `\n${summary}` : ""}`, {
+        code: DECLARATION_INVALID_CODE,
+        details: { violations: [...violations] },
+        fix: "Apply every violation's fix hint, then validate the declaration again.",
+    });
+}
+/** Enforces declaration rules whose runtime behavior would otherwise fail open. */
+export function validateFailClosedDeclaration(provider) {
+    const violations = [];
+    validateHealthDeclaration(provider, violations);
+    validateSchemaDeclaration(provider, violations);
+    validateProxyDeclaration(provider, violations);
+    validateOperationDeclaration(provider, violations);
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export function validateFailClosedProviderDeclaration(provider) {
+    const violations = [];
+    collectProviderDeclarationViolations(provider, violations);
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export function validateFailClosedOperationDeclaration(provider) {
+    const violations = [];
+    collectOperationDeclarationViolations(provider, violations);
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}
+function collectProviderDeclarationViolations(provider, violations) {
+    validateHealthDeclaration(provider, violations);
+    validateProxyDeclaration(provider, violations);
+}
+function collectOperationDeclarationViolations(provider, violations) {
+    validateSchemaDeclaration(provider, violations);
+    validateOperationDeclaration(provider, violations);
+}
+function validateHealthDeclaration(provider, violations) {
+    for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
+        if (!journey || typeof journey !== "object")
+            continue;
+        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 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
+    // "disabled", so the skip is visible in results rather than silent — it is a
+    // supported conditional-execution feature, not a class-1 silent no-op.
+}
+function healthJourneyPath(journey, index) {
+    return typeof journey.id === "string" && journey.id.length > 0
+        ? `healthJourneys.${journey.id}`
+        : `healthJourneys[${index}]`;
+}
+function validateSchemaDeclaration(provider, violations) {
+    for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {
+        const schemaEntries = [
+            [`operations.${operationId}.input`, operation.input],
+            [`operations.${operationId}.output`, operation.output],
+        ];
+        // SSE event schemas reach contract extraction the same way input/output do,
+        // so a transform-bearing event schema would abort extraction at runtime while
+        // passing declaration checks. Validate them under the same rule.
+        const transport = operation.transport;
+        if (transport?.kind === "sse") {
+            for (const [eventName, eventSchema] of Object.entries(transport.events ?? {})) {
+                schemaEntries.push([
+                    `operations.${operationId}.transport.events.${eventName}`,
+                    eventSchema,
+                ]);
+            }
+        }
+        for (const [path, schema] of schemaEntries) {
+            try {
+                describeSchema(schema);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                violations.push({
+                    ruleId: DECLARATION_RULE_IDS.schemaSerializable,
+                    path,
+                    message: `schema conversion to JSON Schema failed: ${reason}`,
+                    fix: `Replace unsupported constructs in ${path} so z.toJSONSchema() succeeds.`,
+                });
+            }
+        }
+    }
+}
+const MANAGED_PROXY_VENDORS = new Set(["smartproxy", "nodemaven"]);
+const STATIC_PROXY_VENDORS = new Set(["custom", "decodo"]);
+function validateProxyDeclaration(provider, violations) {
+    if (provider.proxy === true) {
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.proxyExplicitPolicy,
+            path: "proxy",
+            message: "proxy: true does not require resolvable proxy egress.",
+            fix: 'Replace proxy: true with an explicit policy such as proxy: { mode: "required", providers: ["smartproxy"] }.',
+        });
+        return;
+    }
+    if (!provider.proxy || typeof provider.proxy !== "object")
+        return;
+    const policy = provider.proxy;
+    const hasProvider = policy.provider !== undefined;
+    const hasProviders = policy.providers !== undefined;
+    if (hasProvider && hasProviders) {
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.proxyVendorExclusive,
+            path: "proxy",
+            message: "provider and providers are ambiguous when declared together.",
+            fix: "Keep either proxy.provider or proxy.providers, and remove the other field.",
+        });
+    }
+    const vendors = declaredProxyVendors(policy);
+    if (vendors.some((vendor) => MANAGED_PROXY_VENDORS.has(vendor)) &&
+        vendors.some((vendor) => STATIC_PROXY_VENDORS.has(vendor))) {
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.proxyNoMixedVendors,
+            path: hasProviders ? "proxy.providers" : "proxy.provider",
+            message: "managed and deprecated static proxy vendors cannot share a chain.",
+            fix: "Use only smartproxy/nodemaven vendors, or only deprecated static markers, in one policy.",
+        });
+    }
+    if (vendors.includes("smartproxy")) {
+        for (const field of ["subdivision", "city"]) {
+            if (policy.geo?.[field] === undefined)
+                continue;
+            const path = `proxy.geo.${field}`;
+            violations.push({
+                ruleId: DECLARATION_RULE_IDS.proxySmartproxyGeo,
+                path,
+                message: `smartproxy cannot honor ${field}-level geo targeting.`,
+                fix: `Remove ${path} or use a vendor chain that can honor it.`,
+            });
+        }
+    }
+}
+function declaredProxyVendors(policy) {
+    const vendors = [...(policy.providers ?? [])];
+    if (policy.provider !== undefined)
+        vendors.push(policy.provider);
+    return vendors;
+}
+function validateOperationDeclaration(provider, violations) {
+    for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {
+        if (!operation.upstream?.proxy)
+            continue;
+        const path = `operations.${operationId}.upstream.proxy`;
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.operationUpstreamProxy,
+            path,
+            message: "operation-level proxy policy is not wired into operation execution.",
+            fix: `Remove ${path} and declare the effective policy at provider.proxy.`,
+        });
+    }
+}

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, 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, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, 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 {
@@ -8,36 +8,41 @@ interface ProviderImplementationProfile {
     operatorNotes?: string;
     visibility: "internal" | "operator";
 }
-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>>>;
+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<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";
@@ -48,22 +53,37 @@ 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?: {
         profile: string;
         platform: StealthPlatform;
     };
     proxy?: ProviderProxyConfig;
+    ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
+    resolver?: ProviderResolverConfig;
     browser?: {
         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;
@@ -85,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;
@@ -103,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>>;
+}) => Omit<ProviderDefinition, "operations"> & {
+    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 {};