@apifuse/provider-sdk 2.1.0-beta.5 → 2.1.0-beta.8

package/src/index.ts

@@ -9,6 +9,16 @@ export type {
 	SessionConfig,
 } from "./config/loader";
 export { defineConfig, loadApiFuseConfig } from "./config/loader";
+export {
+	canonicalJson,
+	digestProviderContract,
+	extractProviderContract,
+	type JsonPrimitive,
+	type JsonValue,
+	PROVIDER_CONTRACT_SCHEMA_VERSION,
+	type ProviderContractOperation,
+	type ProviderContractSnapshot,
+} from "./contract";
 export {
 	defineHealthJourney,
 	defineOperation,
@@ -38,6 +48,12 @@ export {
 	type ProviderCacheOptions,
 	resetProviderCacheForTests,
 } from "./runtime/cache";
+export {
+	type CreateProviderChoiceContextOptions,
+	createProviderChoiceContext,
+	createTestProviderChoiceContext,
+	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+} from "./runtime/choice";
 export {
 	type CreateCredentialContextOptions,
 	createCredentialContext,
@@ -99,7 +115,8 @@ export type {
 	AuthConfig,
 	AuthContext,
 	AuthFlowDefinition,
-	AuthFlowHandler,
+	AuthFlowInputHandler,
+	AuthFlowStartHandler,
 	AuthMode,
 	AuthTurn,
 	Bcp47Locale,
@@ -167,6 +184,10 @@ export type {
 	ProviderCacheLookupMeta,
 	ProviderCacheResponseMeta,
 	ProviderCacheResult,
+	ProviderChoiceBindingOptions,
+	ProviderChoiceContext,
+	ProviderChoiceIssueOptions,
+	ProviderChoiceParseOptions,
 	ProviderContext,
 	ProviderDefinition,
 	ProviderHealthMonitorConfig,

package/src/lint.ts

@@ -20,6 +20,7 @@ type ProviderAuthLike = {
 		continue?: unknown;
 		poll?: unknown;
 		abort?: unknown;
+		refresh?: unknown;
 	};
 };
 
@@ -52,6 +53,18 @@ export interface LintDiagnostic {
 	field?: string;
 }
 
+export type ProviderLintMode = "official" | "standalone";
+
+type ProviderLintOptions = {
+	mode?: ProviderLintMode;
+};
+
+type ProviderSourceLike = {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+};
+
 function lintAllowedHosts(
 	providerId: string | undefined,
 	allowedHosts: readonly string[] | undefined,
@@ -126,6 +139,18 @@ function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	);
 }
 
+function hasReusableReloginSecretKeys(
+	keys: readonly string[] | undefined,
+): boolean {
+	if (!keys) {
+		return false;
+	}
+
+	return keys.some((key) =>
+		/(password|passcode|secret|cookie|session)/i.test(key),
+	);
+}
+
 function getAuthFlowSource(provider: {
 	auth?: ProviderAuthLike;
 	authFlowSource?: string;
@@ -139,6 +164,7 @@ function getAuthFlowSource(provider: {
 		provider.auth?.flow?.continue,
 		provider.auth?.flow?.poll,
 		provider.auth?.flow?.abort,
+		provider.auth?.flow?.refresh,
 	];
 
 	return parts
@@ -211,6 +237,20 @@ function lintAuthModel(provider: {
 		});
 	}
 
+	if (
+		typeof provider.auth?.flow?.refresh === "function" &&
+		hasReusableReloginSecretKeys(credentialKeys) &&
+		(!provider.credential?.storesReusableSecret ||
+			!provider.credential.justification)
+	) {
+		diagnostics.push({
+			rule: "auth-refresh-reusable-secret",
+			level: "error",
+			field: "credential",
+			message: `${providerLabel} must set storesReusableSecret and justification when auth.flow.refresh may silently re-login with reusable credential secrets.`,
+		});
+	}
+
 	if (authMode === "platform-managed" && credentialKeys.length > 0) {
 		diagnostics.push({
 			rule: "platform-managed-no-credential-keys",
@@ -621,6 +661,178 @@ function lintStealthTransportUsage(provider: {
 	);
 }
 
+function lintCredentialWriteUsage(provider: {
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+}): LintDiagnostic[] {
+	if (!provider.operations) {
+		return [];
+	}
+
+	return Object.entries(provider.operations).flatMap(
+		([operationKey, operation]) => {
+			const source = getOperationSource(operation);
+			if (!/\bctx\.credential\.(?:set|setMany)\s*\(/.test(source)) {
+				return [];
+			}
+
+			return [
+				{
+					rule: "ctx-credential-write-forbidden-in-handler",
+					level: "error" as const,
+					field: `operations.${operationKey}.handler`,
+					message:
+						"Operation handlers must not mutate credentials; return refreshed credentials from auth.flow.refresh instead.",
+				},
+			];
+		},
+	);
+}
+
+function lintPlaywrightDirectImports(provider: {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+}): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [];
+	const importPattern =
+		/(?:import\s+(?:type\s+)?[\s\S]*?\s+from\s+["'](?:playwright|playwright-core)["']|require\(\s*["'](?:playwright|playwright-core)["']\s*\)|import\(\s*["'](?:playwright|playwright-core)["']\s*\))/;
+
+	if (provider.authFlowSource && importPattern.test(provider.authFlowSource)) {
+		diagnostics.push({
+			rule: "playwright-direct-import",
+			level: "warn",
+			field: "auth.flow",
+			message:
+				"Provider auth flow imports playwright directly; use ctx.browser frame-aware methods so the SDK can enforce the CDP pool runtime.",
+		});
+	}
+
+	for (const [filePath, source] of Object.entries(
+		provider.providerSourceFiles ?? {},
+	)) {
+		if (!importPattern.test(source)) {
+			continue;
+		}
+
+		diagnostics.push({
+			rule: "playwright-direct-import",
+			level: "warn",
+			field: `sourceFiles.${filePath}`,
+			message:
+				"Provider source imports playwright directly; use ctx.browser frame-aware methods so the SDK can enforce the CDP pool runtime.",
+		});
+	}
+
+	if (!provider.operations) {
+		return diagnostics;
+	}
+
+	for (const [operationKey, operation] of Object.entries(provider.operations)) {
+		const source = getOperationSource(operation);
+		if (!importPattern.test(source)) {
+			continue;
+		}
+
+		diagnostics.push({
+			rule: "playwright-direct-import",
+			level: "warn",
+			field: `operations.${operationKey}.handler`,
+			message:
+				"Operation source imports playwright directly; use ctx.browser frame-aware methods so the SDK can enforce the CDP pool runtime.",
+		});
+	}
+
+	return diagnostics;
+}
+
+type SelfHostedBrowserPattern = {
+	rule: string;
+	pattern: RegExp;
+	message: string;
+};
+
+const SELF_HOSTED_BROWSER_MESSAGE =
+	"Official browser providers must use ctx.browser backed by the managed CDP Pool; do not launch or connect to provider-local Chrome/CDP runtimes.";
+
+const SELF_HOSTED_BROWSER_PATTERNS: readonly SelfHostedBrowserPattern[] = [
+	{
+		rule: "browser-self-hosted-launch",
+		pattern: /\b(?:playwright|chromium|firefox|webkit|puppeteer)\.launch\s*\(/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Replace direct Playwright/Puppeteer launch calls with ctx.browser.newPage() or ctx.browser.withIsolatedContext().`,
+	},
+	{
+		rule: "browser-self-hosted-child-process",
+		pattern:
+			/(?:\b(?:spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\([\s\S]{0,240}\b(?:google-chrome|chrome|chromium|chromium-browser)\b|\b(?:Bun\.)?spawn(?:Sync)?\s*\([\s\S]{0,240}\b(?:google-chrome|chrome|chromium|chromium-browser)\b|\$`[\s\S]{0,240}\b(?:google-chrome|chrome|chromium|chromium-browser)\b)/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Provider pods must not start Chrome with child_process, Bun.spawn, or shell commands.`,
+	},
+	{
+		rule: "browser-self-hosted-remote-debugging-port",
+		pattern:
+			/(?:\b(?:google-chrome|chrome|chromium|chromium-browser)\b[\s\S]{0,240}--remote-debugging-port\b|--remote-debugging-port(?:=|\s+))/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Provider entrypoints, Dockerfiles, and scripts must not start Chrome with a remote debugging port; use the managed CDP Pool instead.`,
+	},
+	{
+		rule: "browser-direct-cdp-version-poll",
+		pattern: /\/json\/version\b/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Do not poll /json/version from provider code; the SDK manages CDP leases through APIFUSE__CDP_POOL__URL.`,
+	},
+	{
+		rule: "browser-provider-local-cdp-env",
+		pattern:
+			/\b(?!APIFUSE__CDP_POOL__URL\b)[A-Z][A-Z0-9_]*_CDP_URL\b|process\.env(?:\.(?!APIFUSE__CDP_POOL__URL\b)[A-Z0-9_]*_CDP_URL\b|\[\s*["'`](?!APIFUSE__CDP_POOL__URL\b)[A-Z0-9_]*_CDP_URL["'`]\s*\])/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Do not read provider-local CDP endpoint env vars including AMAZON_CDP_URL or custom *_CDP_URL names; production uses APIFUSE__CDP_POOL__URL through ctx.browser.`,
+	},
+];
+
+function lintSelfHostedBrowserPatterns(
+	provider: ProviderSourceLike,
+	options: ProviderLintOptions,
+): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [];
+	const level = options.mode === "standalone" ? "warn" : "error";
+	const sources: Array<{ field: string; source: string }> = [];
+
+	if (provider.authFlowSource) {
+		sources.push({ field: "auth.flow", source: provider.authFlowSource });
+	}
+
+	for (const [filePath, source] of Object.entries(
+		provider.providerSourceFiles ?? {},
+	)) {
+		sources.push({ field: `sourceFiles.${filePath}`, source });
+	}
+
+	for (const [operationKey, operation] of Object.entries(
+		provider.operations ?? {},
+	)) {
+		const source = getOperationSource(operation);
+		if (source) {
+			sources.push({
+				field: `operations.${operationKey}.handler`,
+				source,
+			});
+		}
+	}
+
+	for (const { field, source } of sources) {
+		for (const item of SELF_HOSTED_BROWSER_PATTERNS) {
+			item.pattern.lastIndex = 0;
+			if (!item.pattern.test(source)) {
+				continue;
+			}
+			diagnostics.push({
+				rule: item.rule,
+				level,
+				field,
+				message: item.message,
+			});
+		}
+	}
+
+	return diagnostics;
+}
+
 export function lintOperation(op: {
 	description?: string;
 	descriptionKey?: string;
@@ -743,48 +955,55 @@ export function lintOperation(op: {
 	return diagnostics;
 }
 
-export function lintProvider(provider: {
-	id?: string;
-	allowedHosts?: readonly string[];
-	stealth?: unknown;
-	auth?: ProviderAuthLike;
-	credential?: {
-		keys?: readonly string[];
-		storesReusableSecret?: boolean;
-		justification?: string;
-	};
-	context?: {
-		keys?: readonly string[];
-	};
-	authFlowSource?: string;
-	operations?: Record<
-		string,
-		{
-			description?: string;
-			descriptionKey?: string;
-			whenToUse?: readonly string[];
-			whenToUseKeys?: readonly string[];
-			whenNotToUse?: readonly string[];
-			whenNotToUseKeys?: readonly string[];
-			input: unknown;
-			output: unknown;
-			fixtures?: unknown;
-			inputExamples?: readonly unknown[];
-			derivations?: Record<string, string>;
-			handler?: unknown;
-			source?: string;
-		}
-	>;
-	meta?: {
-		contract?: ProviderContractMetaLike;
-	};
-	reviewed?: string;
-}): LintDiagnostic[] {
+export function lintProvider(
+	provider: {
+		id?: string;
+		allowedHosts?: readonly string[];
+		stealth?: unknown;
+		auth?: ProviderAuthLike;
+		credential?: {
+			keys?: readonly string[];
+			storesReusableSecret?: boolean;
+			justification?: string;
+		};
+		context?: {
+			keys?: readonly string[];
+		};
+		authFlowSource?: string;
+		providerSourceFiles?: Record<string, string>;
+		operations?: Record<
+			string,
+			{
+				description?: string;
+				descriptionKey?: string;
+				whenToUse?: readonly string[];
+				whenToUseKeys?: readonly string[];
+				whenNotToUse?: readonly string[];
+				whenNotToUseKeys?: readonly string[];
+				input: unknown;
+				output: unknown;
+				fixtures?: unknown;
+				inputExamples?: readonly unknown[];
+				derivations?: Record<string, string>;
+				handler?: unknown;
+				source?: string;
+			}
+		>;
+		meta?: {
+			contract?: ProviderContractMetaLike;
+		};
+		reviewed?: string;
+	},
+	options: ProviderLintOptions = {},
+): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [
 		...lintAllowedHosts(provider.id, provider.allowedHosts),
 		...lintReviewed(provider.id, provider.reviewed),
 		...lintAuthModel(provider),
 		...lintStealthTransportUsage(provider),
+		...lintCredentialWriteUsage(provider),
+		...lintPlaywrightDirectImports(provider),
+		...lintSelfHostedBrowserPatterns(provider, options),
 	];
 
 	if (!provider.operations) {

package/src/provider.ts

@@ -14,8 +14,24 @@ export {
 	defineSmsOtpMatcher,
 	every,
 } from "./define";
-export { AuthError, ProviderError, ValidationError } from "./errors";
-export { providerLocaleKey, qualifyProviderLocaleKey } from "./i18n";
+export {
+	AuthError,
+	ProviderError,
+	SessionExpiredError,
+	TransportError,
+	ValidationError,
+} from "./errors";
+export {
+	getProviderLocalePath,
+	providerLocaleKey,
+	qualifyProviderLocaleKey,
+} from "./i18n";
+export {
+	type CreateProviderChoiceContextOptions,
+	createProviderChoiceContext,
+	createTestProviderChoiceContext,
+	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+} from "./runtime/choice";
 export {
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
@@ -34,7 +50,12 @@ export {
 	z,
 } from "./schema";
 export type {
+	AuthMode,
 	FlowContext,
+	HealthCheckAssertionContext,
+	HealthCheckCase,
+	HealthCheckSuite,
+	HealthCheckUnsupported,
 	HealthJourneyDefinition,
 	HealthJourneyEventContext,
 	HealthJourneyManualTriggerPolicy,
@@ -43,16 +64,38 @@ export type {
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,
+	OperationApprovalPolicy,
+	OperationContractMetadata,
 	OperationDefinition,
+	OperationDocMeta,
+	OperationErrorCode,
+	OperationInputExample,
+	OperationLifecycle,
 	OperationObservabilityConfig,
 	OperationObservabilitySensitiveConfig,
+	OperationRelationships,
+	OperationRiskClass,
 	OperationSensitivePath,
+	OperationToolRouterMetadata,
+	OperationTransport,
+	ProviderAccessVisibility,
+	ProviderChoiceBindingOptions,
+	ProviderChoiceContext,
+	ProviderChoiceIssueOptions,
+	ProviderChoiceParseOptions,
 	ProviderContext,
+	ProviderDefinition,
+	ProviderLocale,
+	ProviderLocaleKey,
 	ProviderLocaleKeyInput,
+	ProviderLogoProfile,
 	ProviderProxyPolicy,
+	ProviderPublicConnectionMode,
+	ProviderPublicProfile,
 	ProviderRuntimeState,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
+	ProviderSupportLevel,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
 	StandardSchemaV1,