@apifuse/provider-sdk 2.2.0-beta.25 → 2.2.0-beta.27

package/AUTHORING.md

@@ -365,7 +365,7 @@ export default defineProvider({
 ```
 <!-- @magic-end:sample -->
 
-The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the optional journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
+The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the required journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
 
 For authenticated journeys, open a fresh connection inside `run` with `ctx.gateway.connect({ input: { ... } })`, execute covered operations with the returned `connectionId`, and disconnect in a `finally` block. Do not require or store long-lived `HEALTH_MONITOR_*_CONNECTION_ID` secrets; those stale connection IDs can hide broken login ceremonies.
 
@@ -734,11 +734,12 @@ const credentialsAuth = defineCredentialsAuth({
   request's `context`.
 - Stealth/browser providers may require local runtime setup outside Provider code:
   keep access-sensitive operations on `ctx.stealth.fetch()` with an SDK stealth
-  `profile`; the TypeScript runtime uses `impit` behind that interface, so do
+  `profile`; the TypeScript runtime uses `wreq-js` behind that interface, so do
   not add per-operation JA3, HTTP/2 SETTINGS, or pseudo-header tuning. `ctx.stealth`
-  supports Chrome/Firefox-style profiles; use `browser.engine:
-  "playwright-stealth"` for Safari-specific or real browser Providers
-  (`nodriver` is Python-runtime only); install local browser assets with
+  supports Chrome, Firefox, and Safari profiles; use `ctx.browser` when a
+  Provider needs real browser execution. TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only);
+  install local browser assets with
   `bunx playwright install chromium`, or set
   `APIFUSE__CDP_POOL__URL` for remote browser debugging.
 
@@ -786,7 +787,7 @@ its own diagnostics.
 
 Set `maxBodyBytes` on `ctx.stealth.fetch()` or `session.redirects.run()` when an
 upstream response has a known safe maximum. The limit is opt-in and counts
-decoded bytes as impit streams them. It applies to every redirect hop, uses a
+decoded bytes as `wreq-js` streams them. It applies to every redirect hop, uses a
 parseable `Content-Length` for an early rejection, and still enforces the limit
 incrementally when the header is absent or inaccurate. Exceeding the limit
 aborts the response and throws a non-retryable `TransportError` with code

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.27
+
+- Release candidate for main commit 579d9e7fd22d8414b151be2b71a43a0990456911.
+
+## 2.2.0-beta.26
+
+- Release candidate for main commit 924fe13d1101e7840d799a562a7a70174355185d.
+
 ## 2.2.0-beta.25
 
 - Release candidate for main commit e6df658b95c0728b671fd221919ec2f85f82b0b7.
@@ -205,7 +213,7 @@
 
 ## 2.1.0-beta.3
 
-- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by `impit` browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
+- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
 - Add the public `apifuse submit-check` / `apifuse bounty-check` CLI for score-based pre-submission provider quality checks.
 - Ship `SUBMISSION.md` in the npm package so bounty contributors can follow the checklist without access to the private monorepo.
 - Include submit-check in generated provider validation scripts and packed-artifact smoke coverage.

package/README.md

@@ -137,7 +137,7 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `context` object.
 - **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
   `ctx.stealth.fetch()` when you need browser-like session or cookie control.
-  `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and
+  `ctx.stealth.fetch()` uses the `wreq-js`-backed browser stealth transport and
   accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`, `profile`,
   `maxBodyBytes`, `redirect`, `throwOnHttpError`, and
   `stealth.insecureSkipVerify`. For login
@@ -145,8 +145,8 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
   `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
-  pseudo-header order in provider code. Chrome/Firefox-style profiles are
-  supported; use `ctx.browser` when Safari-specific behavior is required.
+  pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
+  are supported; use `ctx.browser` when the provider needs browser execution.
 - **Query-parameter credentials**: when an upstream requires a credential in
   its URL query, pass it through `sensitiveParams`, not `params` and never a
   hand-built URL. It is sent as a normal query parameter while the SDK redacts

package/bin/apifuse-check.ts

@@ -11,6 +11,11 @@ import {
 	PROMPT_ASSET_SYNC_REMEDIATION,
 	verifyPromptAssets,
 } from "../src/cli/prompt-assets.js";
+import {
+	DECLARATION_INVALID_CODE,
+	validateFailClosedDeclaration,
+} from "../src/declaration-validation.js";
+import { isProviderError } from "../src/errors.js";
 import type { ProviderDefinition } from "../src/index.js";
 import { lintProvider, type ProviderLintMode } from "../src/lint.js";
 import { safeParseSchemaSync } from "../src/schema.js";
@@ -119,14 +124,25 @@ export async function runChecks(
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
 
-	const providerModule = existsSync(indexPath)
-		? await import(pathToFileURL(indexPath).href)
-		: undefined;
+	let providerModule: Record<string, unknown> | undefined;
+	let providerImportError: unknown;
+	if (existsSync(indexPath)) {
+		try {
+			providerModule = (await import(pathToFileURL(indexPath).href)) as Record<string, unknown>;
+		} catch (error) {
+			if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+				providerImportError = error;
+			} else {
+				throw error;
+			}
+		}
+	}
 	const provider = assertProviderDefinition(providerModule?.default);
 	const providerSourceFiles = collectProviderSourceFiles(providerRoot);
 
 	return [
 		checkIndex(indexPath, provider),
+		checkDeclaration(provider, providerImportError),
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
@@ -138,6 +154,49 @@ export async function runChecks(
 	];
 }
 
+const DECLARATION_CHECK_MESSAGE = "Provider declaration passes fail-closed validation";
+
+function checkDeclaration(
+	provider: ProviderDefinition | undefined,
+	importError: unknown,
+): CheckResult {
+	if (importError !== undefined) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(importError),
+		};
+	}
+	if (!provider) return { message: DECLARATION_CHECK_MESSAGE, passed: false };
+	try {
+		validateFailClosedDeclaration(provider);
+		return { message: DECLARATION_CHECK_MESSAGE, passed: true };
+	} catch (error) {
+		return {
+			message: DECLARATION_CHECK_MESSAGE,
+			passed: false,
+			details: formatDeclarationError(error),
+		};
+	}
+}
+
+function formatDeclarationError(error: unknown): string[] {
+	if (isProviderError(error) && error.code === DECLARATION_INVALID_CODE) {
+		const details = error.details;
+		if (isRecord(details) && Array.isArray(details.violations)) {
+			return details.violations.map((violation) => {
+				if (!isRecord(violation)) return String(violation);
+				const ruleId = typeof violation.ruleId === "string" ? violation.ruleId : "unknown-rule";
+				const path = typeof violation.path === "string" ? violation.path : "unknown-path";
+				const message = typeof violation.message === "string" ? `: ${violation.message}` : "";
+				const fix = typeof violation.fix === "string" ? ` Fix: ${violation.fix}` : "";
+				return `${path} [${ruleId}]${message}${fix}`;
+			});
+		}
+	}
+	return [error instanceof Error ? error.message : String(error)];
+}
+
 export const PROMPT_ASSETS_CHECK_MESSAGE =
 	"Agent prompt assets match the installed SDK version";
 

package/bin/apifuse-pack-check.ts

@@ -156,9 +156,9 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
-	if (!content.includes("impit")) {
+	if (!content.includes("wreq-js")) {
 		throw new Error(
-			`${label} must include impit stealth runtime guidance for TLS/browser bounties.`,
+			`${label} must include wreq-js stealth runtime guidance for TLS/browser bounties.`,
 		);
 	}
 
@@ -168,6 +168,12 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
+	if (!content.includes("Chrome, Firefox, and Safari")) {
+		throw new Error(
+			`${label} must document the browser families supported by the TypeScript stealth runtime.`,
+		);
+	}
+
 	if (
 		!content.includes('browser.engine: "playwright-stealth"') ||
 		!content.includes("nodriver")

package/bin/apifuse-pack-smoke.ts

@@ -73,6 +73,7 @@ try {
 		],
 		consumerDir,
 	);
+	smokePackedStealthNative(consumerDir);
 
 	const cliBin = join(consumerDir, "node_modules", ".bin", "apifuse");
 	if (!existsSync(cliBin)) {
@@ -216,6 +217,43 @@ function run(command: string, args: string[], cwd: string): void {
 	}
 }
 
+function smokePackedStealthNative(consumerDir: string): void {
+	run(
+		"bun",
+		[
+			"--eval",
+			[
+				'import { createServer } from "node:http";',
+				'import { createStealthClient } from "@apifuse/provider-sdk";',
+				"const server = createServer((_request, response) => {",
+				'  response.setHeader("set-cookie", "pack_native_cookie=landed; Path=/");',
+				'  response.end("packed native stealth ok");',
+				"});",
+				"await new Promise((resolve, reject) => {",
+				'  server.once("error", reject);',
+				'  server.listen(0, "127.0.0.1", resolve);',
+				"});",
+				"const address = server.address();",
+				'if (!address || typeof address === "string") throw new Error("Local server has no TCP address");',
+				'const baseUrl = "http://127.0.0.1:" + address.port;',
+				'const session = createStealthClient(baseUrl).createSession({ profile: "safari-17" });',
+				"try {",
+				'  const response = await session.fetch("/native");',
+				'  if (response.body !== "packed native stealth ok") throw new Error("Unexpected stealth body: " + response.body);',
+				'  if (session.cookies.get("pack_native_cookie", baseUrl + "/native") !== "landed") {',
+				'    throw new Error("Packed stealth Set-Cookie did not land in the SDK jar");',
+				"  }",
+				'  console.log("packed native Safari stealth request OK");',
+				"} finally {",
+				"  session.close();",
+				"  await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));",
+				"}",
+			].join("\n"),
+		],
+		consumerDir,
+	);
+}
+
 function assertGeneratedReadme(providerDir: string): void {
 	const readme = readFileSync(join(providerDir, "README.md"), "utf8");
 	if (!readme.includes('"requestId":"req_local_ping"')) {
@@ -227,8 +265,11 @@ function assertGeneratedReadme(providerDir: string): void {
 	if (!readme.includes("bunx playwright install chromium")) {
 		throw new Error("Generated README is missing browser runtime troubleshooting guidance.");
 	}
-	if (!readme.includes("impit")) {
-		throw new Error("Generated README is missing impit stealth runtime guidance.");
+	if (!readme.includes("wreq-js")) {
+		throw new Error("Generated README is missing wreq-js stealth runtime guidance.");
+	}
+	if (!readme.includes("Chrome, Firefox, and Safari")) {
+		throw new Error("Generated README is missing supported stealth browser families.");
 	}
 	if (!readme.includes("bun run submit-check")) {
 		throw new Error("Generated README must document the submit-check pre-submission workflow.");

package/bin/apifuse-pack-types.ts

@@ -143,6 +143,51 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-aws-waf-site-key-type.ts",
+		expectedCode: "TS2322",
+		description: "aws_waf siteKey must be a string",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tsiteKey: 123,",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-aws-waf-context-type.ts",
+		expectedCode: "TS2322",
+		description: "aws_waf context must be a string",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tcontext: 123,",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-aws-waf-unknown-field.ts",
+		expectedCode: "TS2353",
+		description: "aws_waf rejects fields it does not declare",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tunknownField: 1,",
+			"};",
+			"",
+		].join("\n"),
+	},
 	{
 		filename: "negative-control-recaptcha-v3-action.ts",
 		expectedCode: "TS2322",
@@ -184,6 +229,19 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-resolver-runtime-adapter-factories.ts",
+		expectedCode: "TS2353",
+		description: "ResolverRuntimeOptions does not accept caller-supplied adapter factories",
+		source: [
+			'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverRuntimeOptions = {",
+			"\tadapterFactories: {},",
+			"};",
+			"",
+		].join("\n"),
+	},
 	{
 		filename: "negative-control-resolver-runtime-allowed-hosts.ts",
 		expectedCode: "TS2322",

package/dist/auth.js

@@ -1,4 +1,5 @@
 import { AuthError, ProviderError } from "./errors.js";
+import { declarationInvalidError, DECLARATION_RULE_IDS, } from "./declaration-validation.js";
 const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
 const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
 const DEFAULT_ABORT_TURN_ID = "auth.abort";
@@ -379,6 +380,7 @@ export function defineCredentialsAuth(options) {
     const retryTurnId = options.retryTurnId ?? "credentials.retry";
     const completeTurnId = options.completeTurnId ?? "credentials.complete";
     const challenges = (options.challenges ?? {});
+    validateCredentialsAuthChallenges(challenges);
     return {
         auth: {
             mode: "credentials",
@@ -425,3 +427,30 @@ export function defineCredentialsAuth(options) {
         },
     };
 }
+function validateCredentialsAuthChallenges(challenges) {
+    const violations = [];
+    for (const [challengeId, challenge] of Object.entries(challenges)) {
+        const fieldCount = challenge.fields && typeof challenge.fields === "object"
+            ? Object.keys(challenge.fields).length
+            : 0;
+        const fieldsDeclared = challenge.fields !== undefined && challenge.fields !== null;
+        const hasFields = fieldCount > 0;
+        const hasVerify = typeof challenge.verify === "function";
+        const hasPoll = typeof challenge.poll === "function";
+        const isInteractive = hasFields && hasVerify && !hasPoll;
+        const isPolling = !fieldsDeclared && !hasVerify && hasPoll;
+        const isHybrid = hasFields && hasVerify && hasPoll;
+        const emptyFieldsDeclared = fieldsDeclared && !hasFields;
+        if (!emptyFieldsDeclared && (isInteractive || isPolling || isHybrid))
+            continue;
+        const path = `challenges.${challengeId}`;
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.challengeShape,
+            path,
+            message: "challenge must be interactive, polling, or an explicit hybrid.",
+            fix: `Give ${path} non-empty fields plus verify, poll alone, or all three for a hybrid.`,
+        });
+    }
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}

package/dist/cli/templates/provider/README.md.tpl

@@ -114,10 +114,10 @@ Structured errors return an `error` object with `code`, `message`,
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
 - Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
-  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
-  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
-  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
-  (`nodriver` is Python-runtime only), then install local Chromium with
+  SDK stealth `profile`; the TypeScript stealth runtime uses `wreq-js` internally
+  and supports Chrome, Firefox, and Safari profiles. Use `ctx.browser` only when
+  the provider needs browser execution; TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only). Install local Chromium with
   `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
 
 ## Next steps

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/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

@@ -9,7 +9,7 @@ interface ProviderImplementationProfile {
     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"];
+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>>>;

package/dist/define.js

@@ -1,4 +1,5 @@
 import ms from "ms";
+import { validateFailClosedDeclaration } from "./declaration-validation.js";
 import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
 import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
@@ -66,6 +67,8 @@ export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray()([
     "hcaptcha",
     "cloudflare_interstitial",
     "aws_waf",
+    "akamai_sec_cpt",
+    "akamai_sensor",
 ]);
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
@@ -423,9 +426,15 @@ function validateProviderResolver(config) {
             fix: `Set resolver for provider "${config.id}" to { vendors: ["2captcha"], kinds: ["turnstile"] }.`,
         });
     }
-    rejectUnknownFields(resolver, new Set(["vendors", "kinds"]), "resolver", config.id);
+    rejectUnknownFields(resolver, new Set(["vendors", "kinds", "clientProfile"]), "resolver", config.id);
     validateResolverLiteralArray(resolver.vendors, "resolver.vendors", VALID_PROVIDER_RESOLVER_VENDORS, config.id);
     validateResolverLiteralArray(resolver.kinds, "resolver.kinds", VALID_PROVIDER_CHALLENGE_KINDS, config.id);
+    if (resolver.clientProfile !== undefined &&
+        (typeof resolver.clientProfile !== "string" || !resolver.clientProfile.trim())) {
+        throw new ValidationError(`Provider "${config.id}" has invalid resolver.clientProfile: must be a non-empty string.`, {
+            fix: `Set resolver.clientProfile for provider "${config.id}" to a transport-owned profile name.`,
+        });
+    }
 }
 function validateResolverLiteralArray(value, field, validValues, providerId) {
     if (!Array.isArray(value)) {
@@ -1616,7 +1625,7 @@ export function defineProvider(config) {
         });
     if (config.browser && config.runtime !== "browser")
         throw new ProviderError(`Provider "${config.id}" cannot define browser config unless runtime is "browser"`, { fix: 'Set runtime: "browser" or remove the browser config' });
-    return {
+    const provider = {
         id: config.id,
         version: config.version,
         runtime: config.runtime,
@@ -1645,4 +1654,6 @@ export function defineProvider(config) {
         healthProbe: config.healthProbe ?? config.healthMonitor,
         healthJourneys: config.healthJourneys,
     };
+    validateFailClosedDeclaration(provider);
+    return provider;
 }