@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

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;
@@ -26,17 +27,23 @@ export interface ProviderContractSnapshot {
 }
 export interface ProviderContractOperation {
     readonly id: string;
+    readonly connectionMode?: JsonValue;
+    readonly connectionExternalRefParam?: JsonValue;
+    readonly riskClass: JsonValue;
+    readonly approval?: JsonValue;
+    readonly timeoutMs?: JsonValue;
+    readonly titleKey?: JsonValue;
     readonly descriptionKey?: JsonValue;
-    readonly docs?: JsonValue;
+    readonly summaryKey?: JsonValue;
+    readonly markdownKey?: JsonValue;
     readonly whenToUseKeys?: JsonValue;
     readonly whenNotToUseKeys?: JsonValue;
-    readonly derivations?: JsonValue;
-    readonly inputExamples?: JsonValue;
-    readonly annotations?: JsonValue;
+    readonly normalizationNotesKeys?: JsonValue;
+    readonly errorCodes?: JsonValue;
+    readonly examples?: JsonValue;
     readonly contract?: JsonValue;
     readonly tags?: JsonValue;
     readonly relatedOperations?: JsonValue;
-    readonly toolRouter?: JsonValue;
     readonly observability?: JsonValue;
     readonly transport?: JsonValue;
     readonly inputSchema: 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 }),
@@ -46,17 +48,22 @@ export function digestProviderContract(snapshot) {
     return createHash("sha256").update(canonicalJson(snapshot)).digest("hex");
 }
 function extractOperation(operationId, operation) {
+    const connectionMode = toJsonValue(operation.connectionMode);
+    const connectionExternalRefParam = toJsonValue(operation.connectionExternalRefParam);
+    const approval = toJsonValue(operation.approval);
+    const timeoutMs = toJsonValue(operation.timeoutMs);
+    const titleKey = toJsonValue(operation.titleKey);
     const descriptionKey = toJsonValue(operation.descriptionKey);
-    const docs = toJsonValue(operation.docs);
+    const summaryKey = toJsonValue(operation.summaryKey);
+    const markdownKey = toJsonValue(operation.markdownKey);
     const whenToUseKeys = toJsonValue(operation.whenToUseKeys);
     const whenNotToUseKeys = toJsonValue(operation.whenNotToUseKeys);
-    const derivations = toJsonValue(operation.derivations);
-    const inputExamples = toJsonValue(operation.inputExamples);
-    const annotations = toJsonValue(operation.annotations);
+    const normalizationNotesKeys = toJsonValue(operation.normalizationNotesKeys);
+    const errorCodes = toJsonValue(operation.errorCodes);
+    const examples = toJsonValue(operation.examples);
     const contract = toJsonValue(operation.contract);
     const tags = toJsonValue(operation.tags);
     const relatedOperations = toJsonValue(operation.relatedOperations);
-    const toolRouter = toJsonValue(operation.toolRouter);
     const observability = toJsonValue(operation.observability);
     const transport = extractTransport(operation.transport);
     const fixtures = toJsonValue(operation.fixtures);
@@ -68,17 +75,23 @@ function extractOperation(operationId, operation) {
         id: operationId,
         inputSchema: describeSchema(operation.input),
         outputSchema: describeSchema(operation.output),
+        ...(connectionMode === undefined ? {} : { connectionMode }),
+        ...(connectionExternalRefParam === undefined ? {} : { connectionExternalRefParam }),
+        riskClass: operation.riskClass,
+        ...(approval === undefined ? {} : { approval }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(titleKey === undefined ? {} : { titleKey }),
         ...(descriptionKey === undefined ? {} : { descriptionKey }),
-        ...(docs === undefined ? {} : { docs }),
+        ...(summaryKey === undefined ? {} : { summaryKey }),
+        ...(markdownKey === undefined ? {} : { markdownKey }),
         ...(whenToUseKeys === undefined ? {} : { whenToUseKeys }),
         ...(whenNotToUseKeys === undefined ? {} : { whenNotToUseKeys }),
-        ...(derivations === undefined ? {} : { derivations }),
-        ...(inputExamples === undefined ? {} : { inputExamples }),
-        ...(annotations === undefined ? {} : { annotations }),
+        ...(normalizationNotesKeys === undefined ? {} : { normalizationNotesKeys }),
+        ...(errorCodes === undefined ? {} : { errorCodes }),
+        ...(examples === undefined ? {} : { examples }),
         ...(contract === undefined ? {} : { contract }),
         ...(tags === undefined ? {} : { tags }),
         ...(relatedOperations === undefined ? {} : { relatedOperations }),
-        ...(toolRouter === undefined ? {} : { toolRouter }),
         ...(observability === undefined ? {} : { observability }),
         ...(transport === undefined ? {} : { transport }),
         ...(fixtures === undefined ? {} : { fixtures }),
@@ -128,6 +141,7 @@ function extractHealthCheck(value) {
             name: item.name,
             description: item.description,
             input: toJsonValue(item.input),
+            scenario: toJsonValue(item.scenario),
             degradedThresholdMs: item.degradedThresholdMs,
             timeoutMs: item.timeoutMs,
             expectedStatus: item.expectedStatus,

package/dist/declaration-validation.d.ts

@@ -0,0 +1,34 @@
+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";
+    readonly pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid";
+    readonly resolverClientProfileFamily: "resolver-client-profile-family";
+};
+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" | "meta" | "proxy" | "resolver" | "stealth">;
+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,305 @@
+import { describeSchema } from "./contract-serialization.js";
+import { ProviderError } from "./errors.js";
+import { HealthScenarioSchema } from "./health-scenario.js";
+import { kindRequiresClientProfile } from "./runtime/resolver-config.js";
+import { resolverClientProfileFamily, resolveStealthProfileSelection } from "./stealth/profiles.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",
+    pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid",
+    resolverClientProfileFamily: "resolver-client-profile-family",
+};
+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);
+    validatePinnedWireFieldPaths(provider, violations);
+    validateSchemaDeclaration(provider, violations);
+    validateProxyDeclaration(provider, violations);
+    validateResolverClientProfileDeclaration(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);
+    validatePinnedWireFieldPaths(provider, violations);
+    validateProxyDeclaration(provider, violations);
+    validateResolverClientProfileDeclaration(provider, violations);
+}
+function validatePinnedWireFieldPaths(provider, violations) {
+    const pins = provider.meta?.contract?.pinnedWireFieldPaths;
+    if (pins === undefined)
+        return;
+    if (!Array.isArray(pins)) {
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+            path: "meta.contract.pinnedWireFieldPaths",
+            message: "pinned wire field paths must be an array.",
+            fix: "Declare a readonly array of { path, reason } entries.",
+        });
+        return;
+    }
+    const seenPaths = new Set();
+    for (const [index, pin] of pins.entries()) {
+        const entryPath = `meta.contract.pinnedWireFieldPaths[${index}]`;
+        if (!pin || typeof pin !== "object" || Array.isArray(pin)) {
+            violations.push({
+                ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+                path: entryPath,
+                message: "each pinned wire field path must be an object.",
+                fix: `Replace ${entryPath} with { path: "operations.<operation-id>.<field-path>", reason: "<non-empty reason>" }.`,
+            });
+            continue;
+        }
+        const path = "path" in pin ? pin.path : undefined;
+        const reason = "reason" in pin ? pin.reason : undefined;
+        if (typeof path !== "string" || path.trim().length === 0) {
+            violations.push({
+                ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+                path: `${entryPath}.path`,
+                message: "path must be a non-empty string.",
+                fix: `Set ${entryPath}.path to the exact public-schema-upstream-field diagnostic path.`,
+            });
+        }
+        else if (seenPaths.has(path)) {
+            violations.push({
+                ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+                path: `${entryPath}.path`,
+                message: `duplicate pinned wire field path ${JSON.stringify(path)}.`,
+                fix: `Keep exactly one declaration for ${JSON.stringify(path)}.`,
+            });
+        }
+        else {
+            seenPaths.add(path);
+        }
+        if (typeof reason !== "string" || reason.trim().length === 0) {
+            violations.push({
+                ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+                path: `${entryPath}.reason`,
+                message: "reason must be a non-empty string.",
+                fix: `Document why renaming the exact wire field would break the upstream contract.`,
+            });
+        }
+    }
+}
+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.`,
+            });
+        }
+    }
+}
+/**
+ * An akamai_sbsd solve runs on the provider's own stealth session, so the declared
+ * resolver.clientProfile must name the browser family that session emulates. The
+ * stealth runtime re-checks per request (a fetch may override the browser); this
+ * rule fails the declaration instead of the first challenged request.
+ */
+function validateResolverClientProfileDeclaration(provider, violations) {
+    const resolver = provider.resolver;
+    if (!resolver ||
+        !Array.isArray(resolver.kinds) ||
+        !resolver.kinds.some(kindRequiresClientProfile) ||
+        typeof resolver.clientProfile !== "string") {
+        return;
+    }
+    let sessionBrowser;
+    try {
+        sessionBrowser = resolveStealthProfileSelection(provider.stealth).browser;
+    }
+    catch {
+        // An unsupported stealth selection is reported by the stealth runtime itself.
+        return;
+    }
+    const family = resolverClientProfileFamily(resolver.clientProfile);
+    if (family === sessionBrowser)
+        return;
+    violations.push({
+        ruleId: DECLARATION_RULE_IDS.resolverClientProfileFamily,
+        path: "resolver.clientProfile",
+        message: family
+            ? `"${resolver.clientProfile}" names ${family}, but the stealth session browser is ${sessionBrowser}.`
+            : `"${resolver.clientProfile}" does not name a supported browser family (chrome, firefox, safari).`,
+        fix: `Declare stealth.browser as the family resolver.clientProfile names, or set resolver.clientProfile to the ${sessionBrowser} profile the SBSD session runs on.`,
+    });
+}
+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,5 @@
-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 { HandleKind } from "./handle.js";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderRuntimeTarget, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, ProviderStealthConfig, SchemaLike, SmsOtpMatcherDefinition } 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,62 +9,89 @@ 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", "hypersolutions", "custom"];
+export declare const VALID_PROVIDER_CHALLENGE_KINDS: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor", "akamai_sbsd"];
+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";
+    /** Provider business-logic target. Omit only while migrating a legacy provider. */
+    runtimeTarget?: ProviderRuntimeTarget;
     /**
      * Optional deployment overrides, passed through verbatim onto the returned
      * provider definition. The SDK types this field but does not deep-validate
      * it — the APIFuse registry builder owns deployment validation and
      * resolves omitted fields against the runtime deployment profiles.
+     *
+     * This is the only authored deployment surface (no standalone
+     * `deploy.ts`); declare only the fields that differ from the profile.
      */
     deployment?: ProviderDeploymentOverrides;
+    /** Declares the HTTP capability binding. A bare object states use without configuration. */
+    http?: Record<string, never> | true;
+    /** Declares upstream host policy; this does not add a `ctx.allowedHosts` member. */
     allowedHosts?: string[];
-    stealth?: {
-        profile: string;
-        platform: StealthPlatform;
-    };
+    native?: NativeProviderConfig;
+    stealth?: ProviderStealthConfig;
+    /** Declares proxy policy; this is provider intent and does not add a `ctx.proxy` member. */
     proxy?: ProviderProxyConfig;
+    ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
+    resolver?: ProviderResolverConfig;
     browser?: {
         engine: BrowserEngine;
     };
     auth?: AuthConfig;
+    /** Declares the handle kinds this provider issues and accepts (ADR-0012). */
+    handle?: readonly HandleKind[];
     reviewed?: ProviderReviewed;
     access?: ProviderAccessConfig;
+    /** Declares secret requirements; this does not add a `ctx.secrets` member. */
     secrets?: ProviderSecretDeclaration[];
+    /** Declares the environment capability binding. A bare object states use without configuration. */
+    env?: Record<string, never> | true;
+    /** Declares credential keys; platform-managed auth declares this capability without key filtering. */
     credential?: CredentialDeclaration;
+    /** Declares provider context metadata; this does not add a `ctx.context` member. */
     context?: ContextDeclaration;
+    /** Declares the state capability binding. A bare object states use without configuration. */
+    state?: Record<string, never> | true;
+    /** Declares the cache capability binding. A bare object states use without configuration. */
+    cache?: Record<string, never> | true;
+    /** Declares the files capability binding. A bare object states use without configuration. */
+    files?: Record<string, never> | true;
     meta: {
         displayName: string;
         displayNameKey?: string;
@@ -83,18 +111,21 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
         implementationProfile?: ProviderImplementationProfile;
         contract?: {
             publicSchemaFieldNames?: "normalized";
+            readonly pinnedWireFieldPaths?: readonly {
+                readonly path: string;
+                readonly reason: string;
+            }[];
         };
     };
-    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 +134,18 @@ 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<TConfig extends ProviderDeclaration> = <TOperations extends Record<string, ProviderOperation>>(implementation: {
+    operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
+}) => Omit<ProviderDefinition, "operations"> & {
+    operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
 };
+/** Extract the declaration-derived operation context from a provider builder. */
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TConfig> ? ProviderContext<TConfig> : never;
+/** Annotate an operation while preserving the declaration-derived context. */
+export type OperationDefinitionFor<TBuilder, TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> = OperationDefinition<TInput, TOutput, ProviderContextOf<TBuilder>>;
+/** Annotate a built provider while preserving the declaration-derived context. */
+export type ProviderDefinitionFor<TBuilder> = ProviderDefinition<ProviderContextOf<TBuilder>>;
+/** Establish a provider declaration before its operations are contextually typed. */
+export declare function defineProvider<const TConfig extends ProviderDeclaration>(declaration: TConfig & Record<Exclude<keyof TConfig, keyof ProviderDeclaration>, never> & AuthStartNoInputGuard<TConfig>): ProviderBuilder<TConfig>;
 export {};