@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/dist/contract-serialization.d.ts

@@ -1,4 +1,4 @@
-import { type JsonValue } from "./contract-json";
-import type { SchemaLike } from "./types";
+import { type JsonValue } from "./contract-json.js";
+import type { SchemaLike } from "./types.js";
 export declare function describeSchema(schema: SchemaLike): JsonValue;
 export declare function serializeSmsMatcher(value: Record<string, unknown>): Record<string, unknown>;

package/dist/contract-serialization.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import { canonicalJson, compactObject, isRecord, toJsonValue, } from "./contract-json";
+import { canonicalJson, compactObject, isRecord, toJsonValue, } from "./contract-json.js";
 export function describeSchema(schema) {
     if (isZodSchema(schema)) {
         const jsonSchema = zodJsonSchema(schema);
@@ -9,9 +9,7 @@ export function describeSchema(schema) {
             vendor: "zod",
             typeName: getSchemaTypeName(schema),
             jsonSchema,
-            jsonSchemaHash: jsonSchema === undefined
-                ? undefined
-                : digest(canonicalJson(jsonSchema)),
+            jsonSchemaHash: jsonSchema === undefined ? undefined : digest(canonicalJson(jsonSchema)),
         });
     }
     const standard = isRecord(schema) ? schema["~standard"] : undefined;
@@ -20,8 +18,7 @@ export function describeSchema(schema) {
             kind: "schema",
             standard: "standard-schema-v1",
             vendor: typeof standard.vendor === "string" ? standard.vendor : "unknown",
-            version: typeof standard.version === "number" ||
-                typeof standard.version === "string"
+            version: typeof standard.version === "number" || typeof standard.version === "string"
                 ? standard.version
                 : undefined,
         });
@@ -57,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

@@ -1,5 +1,5 @@
-import type { JsonValue } from "./contract-json";
-import type { ProviderDefinition } from "./types";
+import type { JsonValue } from "./contract-json.js";
+import type { ProviderDefinition } from "./types.js";
 export declare const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";
 export interface ProviderContractSnapshot {
     readonly schemaVersion: typeof PROVIDER_CONTRACT_SCHEMA_VERSION;
@@ -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.d.ts

@@ -1,6 +1,6 @@
-import { canonicalJson, type JsonPrimitive, type JsonValue } from "./contract-json";
-import { PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot } from "./contract-types";
-import type { ProviderDefinition } from "./types";
+import { canonicalJson, type JsonPrimitive, type JsonValue } from "./contract-json.js";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot } from "./contract-types.js";
+import type { ProviderDefinition } from "./types.js";
 export { canonicalJson, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, };
 export declare function extractProviderContract(provider: ProviderDefinition): ProviderContractSnapshot;
 export declare function digestProviderContract(snapshot: ProviderContractSnapshot): string;

package/dist/contract.js

@@ -1,12 +1,13 @@
 import { createHash } from "node:crypto";
-import { canonicalJson, compactObject, copyRecordWithout, toJsonValue, } from "./contract-json";
-import { describeSchema, serializeSmsMatcher } from "./contract-serialization";
-import { PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract-types";
+import { canonicalJson, compactObject, copyRecordWithout, toJsonValue, } from "./contract-json.js";
+import { describeSchema, serializeSmsMatcher } from "./contract-serialization.js";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract-types.js";
 export { canonicalJson, PROVIDER_CONTRACT_SCHEMA_VERSION, };
 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);
@@ -27,11 +28,10 @@ export function extractProviderContract(provider) {
         operations: Object.entries(provider.operations)
             .sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
             .map(([operationId, operation]) => extractOperation(operationId, operation)),
-        ...(provider.allowedHosts
-            ? { allowedHosts: [...provider.allowedHosts].sort() }
-            : {}),
+        ...(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,23 @@
+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 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;

package/dist/declaration-validation.js

@@ -0,0 +1,159 @@
+import { describeSchema } from "./contract-serialization.js";
+import { ProviderError } from "./errors.js";
+export const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
+export const DECLARATION_RULE_IDS = {
+    challengeShape: "credentials-challenge-shape",
+    journeyExecutable: "health-journey-executable",
+    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);
+}
+function validateHealthDeclaration(provider, violations) {
+    for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
+        if (!journey || typeof journey !== "object")
+            continue;
+        if (typeof journey.run !== "function") {
+            const journeyPath = healthJourneyPath(journey, index);
+            violations.push({
+                ruleId: DECLARATION_RULE_IDS.journeyExecutable,
+                path: `${journeyPath}.run`,
+                message: "coversOperations cannot provide health coverage without executable run logic.",
+                fix: `Add an async run(ctx) implementation to ${journeyPath}.`,
+            });
+        }
+    }
+    // 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, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types";
+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";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -8,6 +8,8 @@ interface ProviderImplementationProfile {
     operatorNotes?: string;
     visibility: "internal" | "operator";
 }
+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>>>;
@@ -41,13 +43,23 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
+    /**
+     * 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.
+     */
+    deployment?: ProviderDeploymentOverrides;
     allowedHosts?: string[];
+    native?: NativeProviderConfig;
     stealth?: {
         profile: string;
         platform: StealthPlatform;
     };
     proxy?: ProviderProxyConfig;
+    ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
+    resolver?: ProviderResolverConfig;
     browser?: {
         engine: BrowserEngine;
     };