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

package/src/lint.ts

@@ -1,17 +1,9 @@
 import type { ZodType } from "zod";
 
-import { lintPublicSchemaFieldNames } from "./public-schema-field-lint";
-import {
-	APIFUSE_DESCRIPTION_KEY_META_KEY,
-	APIFUSE_SENSITIVE_META_KEY,
-} from "./schema";
-
-type AuthModeLike =
-	| "none"
-	| "platform-managed"
-	| "credentials"
-	| "oauth2"
-	| "api-key";
+import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
+import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
+
+type AuthModeLike = "none" | "platform-managed" | "credentials" | "oauth2" | "api-key";
 
 type ProviderAuthLike = {
 	mode?: AuthModeLike;
@@ -141,28 +133,19 @@ function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	}
 
 	return keys.some((key) =>
-		/(access_token|refresh_token|password|secret|cookie|session|token|api[_-]?key)/i.test(
-			key,
-		),
+		/(access_token|refresh_token|password|secret|cookie|session|token|api[_-]?key)/i.test(key),
 	);
 }
 
-function hasReusableReloginSecretKeys(
-	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),
-	);
+	return keys.some((key) => /(password|passcode|secret|cookie|session)/i.test(key));
 }
 
-function getAuthFlowSource(provider: {
-	auth?: ProviderAuthLike;
-	authFlowSource?: string;
-}): string {
+function getAuthFlowSource(provider: { auth?: ProviderAuthLike; authFlowSource?: string }): string {
 	if (provider.authFlowSource) {
 		return provider.authFlowSource;
 	}
@@ -176,10 +159,7 @@ function getAuthFlowSource(provider: {
 	];
 
 	return parts
-		.filter(
-			(part): part is (...args: unknown[]) => unknown =>
-				typeof part === "function",
-		)
+		.filter((part): part is (...args: unknown[]) => unknown => typeof part === "function")
 		.map((part) => part.toString())
 		.join("\n");
 }
@@ -243,8 +223,7 @@ function lintAuthModel(provider: {
 
 	if (
 		hasReusableSecretKeys(credentialKeys) &&
-		(!provider.credential?.storesReusableSecret ||
-			!provider.credential.justification)
+		(!provider.credential?.storesReusableSecret || !provider.credential.justification)
 	) {
 		diagnostics.push({
 			rule: "credential-reusable-secret",
@@ -257,8 +236,7 @@ function lintAuthModel(provider: {
 	if (
 		typeof provider.auth?.flow?.refresh === "function" &&
 		hasReusableReloginSecretKeys(credentialKeys) &&
-		(!provider.credential?.storesReusableSecret ||
-			!provider.credential.justification)
+		(!provider.credential?.storesReusableSecret || !provider.credential.justification)
 	) {
 		diagnostics.push({
 			rule: "auth-refresh-reusable-secret",
@@ -278,10 +256,7 @@ function lintAuthModel(provider: {
 	}
 
 	const authFlowSource = getAuthFlowSource(provider);
-	if (
-		authFlowSource.includes("ctx.context") &&
-		(provider.context?.keys?.length ?? 0) === 0
-	) {
+	if (authFlowSource.includes("ctx.context") && (provider.context?.keys?.length ?? 0) === 0) {
 		diagnostics.push({
 			rule: "context-keys-required",
 			level: "warn",
@@ -323,8 +298,7 @@ function isSchemaRecord(value: unknown): value is Record<string, SchemaLike> {
 }
 
 function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
-	const rawShape =
-		typeof schema.shape === "function" ? schema.shape() : schema.shape;
+	const rawShape = typeof schema.shape === "function" ? schema.shape() : schema.shape;
 	if (isSchemaRecord(rawShape)) {
 		return rawShape;
 	}
@@ -344,9 +318,7 @@ function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
 	return {};
 }
 
-function getChildSchemas(
-	schema: SchemaLike,
-): Array<{ key: string; schema: SchemaLike }> {
+function getChildSchemas(schema: SchemaLike): Array<{ key: string; schema: SchemaLike }> {
 	const seen = new Map<string, SchemaLike>();
 	const def = getSchemaDef(schema);
 
@@ -450,10 +422,7 @@ function getSchemaMetadata(schema: SchemaLike): Record<string, unknown> {
 }
 
 function getSchemaDescriptionKey(schema: SchemaLike): string | undefined {
-	const value = Reflect.get(
-		getSchemaMetadata(schema),
-		APIFUSE_DESCRIPTION_KEY_META_KEY,
-	);
+	const value = Reflect.get(getSchemaMetadata(schema), APIFUSE_DESCRIPTION_KEY_META_KEY);
 	return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
@@ -597,22 +566,14 @@ function collectSchemaDescriptionKeyDiagnostics(
 						? `${currentPath}[]`
 						: `${currentPath}.${child.key}`;
 		diagnostics.push(
-			...collectSchemaDescriptionKeyDiagnostics(
-				child.schema,
-				childPath,
-				seen,
-				!isStructuralNode,
-			),
+			...collectSchemaDescriptionKeyDiagnostics(child.schema, childPath, seen, !isStructuralNode),
 		);
 	}
 
 	return diagnostics;
 }
 
-function isComplexSchema(
-	schema: unknown,
-	seen = new Set<SchemaLike>(),
-): boolean {
+function isComplexSchema(schema: unknown, seen = new Set<SchemaLike>()): boolean {
 	if (!isSchema(schema) || seen.has(schema)) {
 		return false;
 	}
@@ -624,10 +585,7 @@ function isComplexSchema(
 		return childChildren.length > 0;
 	});
 
-	return (
-		hasNestedComposite ||
-		children.some(({ schema: child }) => isComplexSchema(child, seen))
-	);
+	return hasNestedComposite || children.some(({ schema: child }) => isComplexSchema(child, seen));
 }
 
 function hasBidirectionalFixtures(fixtures: unknown): boolean {
@@ -638,16 +596,11 @@ function hasBidirectionalFixtures(fixtures: unknown): boolean {
 	return "request" in fixtures && "response" in fixtures;
 }
 
-function getOperationSource(operation: {
-	handler?: unknown;
-	source?: string;
-}): string {
+function getOperationSource(operation: { handler?: unknown; source?: string }): string {
 	if (operation.source) {
 		return operation.source;
 	}
-	return typeof operation.handler === "function"
-		? operation.handler.toString()
-		: "";
+	return typeof operation.handler === "function" ? operation.handler.toString() : "";
 }
 
 function lintStealthTransportUsage(provider: {
@@ -660,22 +613,20 @@ function lintStealthTransportUsage(provider: {
 	}
 
 	const providerLabel = provider.id ? `Provider "${provider.id}"` : "Provider";
-	return Object.entries(provider.operations).flatMap(
-		([operationKey, operation]) => {
-			const source = getOperationSource(operation);
-			if (!/\bctx\.stealth\b/.test(source)) {
-				return [];
-			}
-			return [
-				{
-					rule: "stealth-config-required",
-					level: "error" as const,
-					field: `operations.${operationKey}`,
-					message: `${providerLabel} operation "${operationKey}" uses ctx.stealth but provider.stealth is not declared.`,
-				},
-			];
-		},
-	);
+	return Object.entries(provider.operations).flatMap(([operationKey, operation]) => {
+		const source = getOperationSource(operation);
+		if (!/\bctx\.stealth\b/.test(source)) {
+			return [];
+		}
+		return [
+			{
+				rule: "stealth-config-required",
+				level: "error" as const,
+				field: `operations.${operationKey}`,
+				message: `${providerLabel} operation "${operationKey}" uses ctx.stealth but provider.stealth is not declared.`,
+			},
+		];
+	});
 }
 
 function lintCredentialWriteUsage(provider: {
@@ -685,24 +636,22 @@ function lintCredentialWriteUsage(provider: {
 		return [];
 	}
 
-	return Object.entries(provider.operations).flatMap(
-		([operationKey, operation]) => {
-			const source = getOperationSource(operation);
-			if (!/\bctx\.credential\.(?:set|setMany)\s*\(/.test(source)) {
-				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.",
-				},
-			];
-		},
-	);
+		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: {
@@ -724,9 +673,7 @@ function lintPlaywrightDirectImports(provider: {
 		});
 	}
 
-	for (const [filePath, source] of Object.entries(
-		provider.providerSourceFiles ?? {},
-	)) {
+	for (const [filePath, source] of Object.entries(provider.providerSourceFiles ?? {})) {
 		if (!importPattern.test(source)) {
 			continue;
 		}
@@ -814,15 +761,11 @@ function lintSelfHostedBrowserPatterns(
 		sources.push({ field: "auth.flow", source: provider.authFlowSource });
 	}
 
-	for (const [filePath, source] of Object.entries(
-		provider.providerSourceFiles ?? {},
-	)) {
+	for (const [filePath, source] of Object.entries(provider.providerSourceFiles ?? {})) {
 		sources.push({ field: `sourceFiles.${filePath}`, source });
 	}
 
-	for (const [operationKey, operation] of Object.entries(
-		provider.operations ?? {},
-	)) {
+	for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
 		const source = getOperationSource(operation);
 		if (source) {
 			sources.push({
@@ -865,16 +808,14 @@ export function lintOperation(op: {
 }): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [];
 	const description = op.description ?? "";
-	const hasDescriptionKey =
-		typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
+	const hasDescriptionKey = typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
 
 	if (description.trim().length > 0 && !hasDescriptionKey) {
 		diagnostics.push({
 			rule: "operation-description-raw-prose",
 			level: "error",
 			field: "description",
-			message:
-				"Operation description must use descriptionKey instead of raw static prose.",
+			message: "Operation description must use descriptionKey instead of raw static prose.",
 		});
 	}
 
@@ -892,21 +833,16 @@ export function lintOperation(op: {
 			rule: "operation-when-to-use-raw-prose",
 			level: "error",
 			field: "whenToUse",
-			message:
-				"Operation whenToUse must use whenToUseKeys instead of raw static prose.",
+			message: "Operation whenToUse must use whenToUseKeys instead of raw static prose.",
 		});
 	}
 
-	if (
-		(op.whenNotToUse?.length ?? 0) > 0 &&
-		!(op.whenNotToUseKeys?.length ?? 0)
-	) {
+	if ((op.whenNotToUse?.length ?? 0) > 0 && !(op.whenNotToUseKeys?.length ?? 0)) {
 		diagnostics.push({
 			rule: "operation-when-not-to-use-raw-prose",
 			level: "error",
 			field: "whenNotToUse",
-			message:
-				"Operation whenNotToUse must use whenNotToUseKeys instead of raw static prose.",
+			message: "Operation whenNotToUse must use whenNotToUseKeys instead of raw static prose.",
 		});
 	}
 
@@ -942,14 +878,11 @@ export function lintOperation(op: {
 			rule: "complex-input-has-examples",
 			level: "warn",
 			field: "inputExamples",
-			message:
-				"Complex input schemas should provide at least 2 input examples.",
+			message: "Complex input schemas should provide at least 2 input examples.",
 		});
 	}
 
-	for (const field of uniqueFields(
-		collectUnmarkedSensitiveFields(op.input, "input"),
-	)) {
+	for (const field of uniqueFields(collectUnmarkedSensitiveFields(op.input, "input"))) {
 		diagnostics.push({
 			rule: "sensitive-field-unmarked",
 			level: "warn",
@@ -958,9 +891,7 @@ export function lintOperation(op: {
 		});
 	}
 
-	for (const field of uniqueFields(
-		collectUnmarkedSensitiveFields(op.output, "output"),
-	)) {
+	for (const field of uniqueFields(collectUnmarkedSensitiveFields(op.output, "output"))) {
 		diagnostics.push({
 			rule: "sensitive-field-unmarked",
 			level: "warn",
@@ -1044,36 +975,35 @@ export function lintProvider(
 	}
 
 	diagnostics.push(
-		...Object.entries(provider.operations).flatMap(
-			([operationKey, operation]) =>
-				[
-					...lintOperation({
-						description: operation.description ?? "",
-						descriptionKey: operation.descriptionKey,
-						whenToUse: operation.whenToUse,
-						whenToUseKeys: operation.whenToUseKeys,
-						whenNotToUse: operation.whenNotToUse,
-						whenNotToUseKeys: operation.whenNotToUseKeys,
-						input: operation.input,
-						output: operation.output,
-						fixtures: operation.fixtures,
-						inputExamples: operation.inputExamples,
-						derivations: operation.derivations,
-					}),
-					...lintPublicSchemaFieldNames(
-						provider.id,
-						operationKey,
-						operation.input,
-						operation.output,
-						provider.meta?.contract?.publicSchemaFieldNames === "normalized",
-					),
-				].map((diagnostic) => ({
-					...diagnostic,
-					field: diagnostic.field
-						? `operations.${operationKey}.${diagnostic.field}`
-						: `operations.${operationKey}`,
-					message: `[${operationKey}] ${diagnostic.message}`,
-				})),
+		...Object.entries(provider.operations).flatMap(([operationKey, operation]) =>
+			[
+				...lintOperation({
+					description: operation.description ?? "",
+					descriptionKey: operation.descriptionKey,
+					whenToUse: operation.whenToUse,
+					whenToUseKeys: operation.whenToUseKeys,
+					whenNotToUse: operation.whenNotToUse,
+					whenNotToUseKeys: operation.whenNotToUseKeys,
+					input: operation.input,
+					output: operation.output,
+					fixtures: operation.fixtures,
+					inputExamples: operation.inputExamples,
+					derivations: operation.derivations,
+				}),
+				...lintPublicSchemaFieldNames(
+					provider.id,
+					operationKey,
+					operation.input,
+					operation.output,
+					provider.meta?.contract?.publicSchemaFieldNames === "normalized",
+				),
+			].map((diagnostic) => ({
+				...diagnostic,
+				field: diagnostic.field
+					? `operations.${operationKey}.${diagnostic.field}`
+					: `operations.${operationKey}`,
+				message: `[${operationKey}] ${diagnostic.message}`,
+			})),
 		),
 	);
 

package/src/provider.ts

@@ -3,7 +3,7 @@ export {
 	credentialsAuthChallenge,
 	createAuthFlowHelpers,
 	defineCredentialsAuth,
-} from "./auth";
+} from "./auth.js";
 export type {
 	CredentialsAuthChallengeDefinition,
 	CredentialsAuthChallengeRequest,
@@ -16,8 +16,8 @@ export type {
 	CredentialsAuthLoginResult,
 	DefineCredentialsAuthOptions,
 	DefinedCredentialsAuth,
-} from "./auth";
-export { createFormCeremony } from "./ceremonies";
+} from "./auth.js";
+export { createFormCeremony } from "./ceremonies/index.js";
 export {
 	assertFreshProviderChoiceIssuedAt,
 	createProviderChoiceToken,
@@ -25,7 +25,7 @@ export {
 	type ProviderChoiceTokenErrorReason,
 	type ProviderChoiceTokenPayload,
 	parseProviderChoiceToken,
-} from "./choice-token";
+} from "./choice-token.js";
 export {
 	centered,
 	delayed,
@@ -34,25 +34,28 @@ export {
 	defineProvider,
 	defineSmsOtpMatcher,
 	every,
-} from "./define";
+} from "./define.js";
 export {
 	AuthError,
+	isProviderError,
+	isSessionExpiredError,
+	isTransportError,
 	ProviderError,
 	SessionExpiredError,
 	TransportError,
 	ValidationError,
-} from "./errors";
+} from "./errors.js";
 export {
 	getProviderLocalePath,
 	providerLocaleKey,
 	qualifyProviderLocaleKey,
-} from "./i18n";
+} from "./i18n/index.js";
 export {
 	type CreateProviderChoiceContextOptions,
 	createProviderChoiceContext,
 	createTestProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-} from "./runtime/choice";
+} from "./runtime/choice.js";
 export {
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
@@ -69,7 +72,7 @@ export {
 	type SensitivePath,
 	sensitive,
 	z,
-} from "./schema";
+} from "./schema.js";
 export type {
 	AuthAbortData,
 	AuthAbortRetry,
@@ -112,6 +115,7 @@ export type {
 	ProviderChoiceParseOptions,
 	ProviderContext,
 	ProviderDefinition,
+	ProviderDeploymentOverrides,
 	ProviderLocale,
 	ProviderLocaleKey,
 	ProviderLocaleKeyInput,
@@ -130,11 +134,11 @@ export type {
 	StateNamespaceOptions,
 	StateValue,
 	StateWriteOptions,
-} from "./types";
+} from "./types.js";
 export {
 	HttpRetryAfterPolicy,
 	HttpRetryDelayStrategy,
 	HttpRetryJitter,
 	HttpRetryPreset,
 	HttpRetryUnsafeMethodPolicy,
-} from "./types";
+} from "./types.js";

package/src/public-schema-field-lint.ts

@@ -1,6 +1,6 @@
 import type { ZodType } from "zod";
 
-import type { LintDiagnostic } from "./lint";
+import type { LintDiagnostic } from "./lint.js";
 
 type SchemaLike = ZodType & {
 	def?: Record<string, unknown>;
@@ -55,8 +55,7 @@ function isSchemaRecord(value: unknown): value is Record<string, SchemaLike> {
 }
 
 function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
-	const rawShape =
-		typeof schema.shape === "function" ? schema.shape() : schema.shape;
+	const rawShape = typeof schema.shape === "function" ? schema.shape() : schema.shape;
 	if (isSchemaRecord(rawShape)) {
 		return rawShape;
 	}
@@ -69,10 +68,7 @@ function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
 	return isSchemaRecord(defShape) ? defShape : {};
 }
 
-function appendSchemaChildren(
-	children: SchemaLike[],
-	value: unknown,
-): SchemaLike[] {
+function appendSchemaChildren(children: SchemaLike[], value: unknown): SchemaLike[] {
 	if (isSchema(value)) {
 		children.push(value);
 		return children;
@@ -183,26 +179,14 @@ function collectPublicSchemaFieldDiagnostics(
 			});
 		}
 		diagnostics.push(
-			...collectPublicSchemaFieldDiagnostics(
-				providerId,
-				operationId,
-				child,
-				fieldPath,
-				seen,
-			),
+			...collectPublicSchemaFieldDiagnostics(providerId, operationId, child, fieldPath, seen),
 		);
 	}
 
 	for (const child of getTransparentChildSchemas(schema)) {
 		const childPath = schema.element === child ? `${basePath}[]` : basePath;
 		diagnostics.push(
-			...collectPublicSchemaFieldDiagnostics(
-				providerId,
-				operationId,
-				child,
-				childPath,
-				seen,
-			),
+			...collectPublicSchemaFieldDiagnostics(providerId, operationId, child, childPath, seen),
 		);
 	}
 
@@ -221,17 +205,7 @@ export function lintPublicSchemaFieldNames(
 	}
 
 	return [
-		...collectPublicSchemaFieldDiagnostics(
-			providerId,
-			operationId,
-			input,
-			"input",
-		),
-		...collectPublicSchemaFieldDiagnostics(
-			providerId,
-			operationId,
-			output,
-			"output",
-		),
+		...collectPublicSchemaFieldDiagnostics(providerId, operationId, input, "input"),
+		...collectPublicSchemaFieldDiagnostics(providerId, operationId, output, "output"),
 	];
 }

package/src/recipes/gov-api.ts

@@ -1,4 +1,4 @@
-import { unwrapEnvelope } from "../utils/parse";
+import { unwrapEnvelope } from "../utils/parse.js";
 
 function getResultCode(raw: unknown): string | undefined {
 	if (!raw || typeof raw !== "object") {
@@ -33,10 +33,7 @@ export function checkResultCode(
  * Replace placeholder values with null
  * e.g., nullIfPlaceholder('해당없음', ['해당없음', '-', '']) → null
  */
-export function nullIfPlaceholder(
-	v: unknown,
-	patterns: string[],
-): unknown | null {
+export function nullIfPlaceholder(v: unknown, patterns: string[]): unknown | null {
 	if (v === null || v === undefined) {
 		return null;
 	}

package/src/runtime/auth-flow.ts

@@ -1,5 +1,5 @@
-import { ContextAccessError } from "../errors";
-import { createAuthFlowHelpers } from "../auth";
+import { ContextAccessError } from "../errors.js";
+import { createAuthFlowHelpers } from "../auth.js";
 import type {
 	ContextScratchpad,
 	EnvContext,
@@ -7,8 +7,8 @@ import type {
 	HttpClient,
 	StealthClient,
 	SttContext,
-} from "../types";
-import { createUnsupportedSttClient } from "./stt";
+} from "../types.js";
+import { createUnsupportedSttClient } from "./stt.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 	return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -16,9 +16,7 @@ function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 
 function assertAllowedKey(allowedKeys: Set<string>, key: string): void {
 	if (!allowedKeys.has(key)) {
-		throw new ContextAccessError(
-			`Context key "${key}" is not declared in context.keys.`,
-		);
+		throw new ContextAccessError(`Context key "${key}" is not declared in context.keys.`);
 	}
 }