@apifuse/provider-sdk 2.0.0-beta.1 → 2.1.0-beta.0

package/src/lint.ts

@@ -0,0 +1,574 @@
+import type { ZodType } from "zod";
+
+type AuthModeLike =
+	| "none"
+	| "platform-managed"
+	| "credentials"
+	| "oauth2"
+	| "api-key";
+
+type ProviderAuthLike = {
+	mode?: AuthModeLike;
+	flow?: {
+		start?: unknown;
+		continue?: unknown;
+		poll?: unknown;
+		abort?: unknown;
+	};
+};
+
+type SchemaLike = ZodType & {
+	description?: string;
+	def?: Record<string, unknown>;
+	_def?: Record<string, unknown>;
+	shape?: Record<string, SchemaLike> | (() => Record<string, SchemaLike>);
+	element?: SchemaLike;
+	items?: SchemaLike[];
+	options?: SchemaLike[] | Set<SchemaLike> | Map<string, SchemaLike>;
+	innerType?: SchemaLike;
+	sourceType?: () => SchemaLike;
+	unwrap?: () => SchemaLike;
+	in?: SchemaLike;
+	out?: SchemaLike;
+	left?: SchemaLike;
+	right?: SchemaLike;
+};
+
+export interface LintDiagnostic {
+	rule: string;
+	level: "error" | "warn";
+	message: string;
+	field?: string;
+}
+
+function lintAllowedHosts(
+	providerId: string | undefined,
+	allowedHosts: string[] | undefined,
+): LintDiagnostic[] {
+	const prefix = providerId ? `Provider "${providerId}"` : "Provider";
+
+	if (!allowedHosts) {
+		return [
+			{
+				rule: "allowed-hosts-required",
+				level: "error",
+				field: "allowedHosts",
+				message: `${prefix} must declare allowedHosts.`,
+			},
+		];
+	}
+
+	if (allowedHosts.length === 0) {
+		return [
+			{
+				rule: "allowed-hosts-non-empty",
+				level: "error",
+				field: "allowedHosts",
+				message: `${prefix} must declare at least one allowed host.`,
+			},
+		];
+	}
+
+	const wildcardHost = allowedHosts.find((host) => host.trim().includes("*"));
+	if (wildcardHost) {
+		return [
+			{
+				rule: "allowed-hosts-no-wildcards",
+				level: "error",
+				field: "allowedHosts",
+				message: `${prefix} must not declare wildcard allowedHosts entries like "${wildcardHost}".`,
+			},
+		];
+	}
+
+	return [];
+}
+
+function lintReviewed(
+	providerId: string | undefined,
+	reviewed: string | undefined,
+): LintDiagnostic[] {
+	if (reviewed === "first-party" || reviewed === "community") {
+		return [];
+	}
+
+	const prefix = providerId ? `Provider "${providerId}"` : "Provider";
+	return [
+		{
+			rule: "reviewed-required",
+			level: "error",
+			field: "reviewed",
+			message: `${prefix} must declare reviewed as "first-party" or "community".`,
+		},
+	];
+}
+
+function hasReusableSecretKeys(keys: string[] | undefined): boolean {
+	if (!keys) {
+		return false;
+	}
+
+	return keys.some((key) =>
+		/(access_token|refresh_token|password|secret|cookie|session|token|api[_-]?key)/i.test(
+			key,
+		),
+	);
+}
+
+function getAuthFlowSource(provider: {
+	auth?: ProviderAuthLike;
+	authFlowSource?: string;
+}): string {
+	if (provider.authFlowSource) {
+		return provider.authFlowSource;
+	}
+
+	const parts = [
+		provider.auth?.flow?.start,
+		provider.auth?.flow?.continue,
+		provider.auth?.flow?.poll,
+		provider.auth?.flow?.abort,
+	];
+
+	return parts
+		.filter(
+			(part): part is (...args: unknown[]) => unknown =>
+				typeof part === "function",
+		)
+		.map((part) => part.toString())
+		.join("\n");
+}
+
+function lintAuthModel(provider: {
+	id?: string;
+	auth?: ProviderAuthLike;
+	credential?: {
+		keys?: string[];
+		storesReusableSecret?: boolean;
+		justification?: string;
+	};
+	context?: {
+		keys?: string[];
+	};
+	authFlowSource?: string;
+}): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [];
+	const providerLabel = provider.id ? `Provider "${provider.id}"` : "Provider";
+	const authMode = provider.auth?.mode;
+	const credentialKeys = provider.credential?.keys ?? [];
+
+	if (authMode === "api-key") {
+		diagnostics.push({
+			rule: "auth-mode-api-key-removed",
+			level: "error",
+			field: "auth.mode",
+			message: `${providerLabel} must not use auth.mode "api-key".`,
+		});
+	}
+
+	if (
+		(authMode === "credentials" || authMode === "oauth2") &&
+		typeof provider.auth?.flow?.continue !== "function"
+	) {
+		diagnostics.push({
+			rule: "auth-flow-continue-required",
+			level: "error",
+			field: "auth.flow.continue",
+			message: `${providerLabel} must define auth.flow.continue for ${authMode} auth mode.`,
+		});
+	}
+
+	if (authMode === "credentials" && credentialKeys.length === 0) {
+		diagnostics.push({
+			rule: "credential-keys-required-when-credentials-mode",
+			level: "error",
+			field: "credential.keys",
+			message: `${providerLabel} must declare credential.keys for credentials auth mode.`,
+		});
+	}
+
+	if (
+		hasReusableSecretKeys(credentialKeys) &&
+		(!provider.credential?.storesReusableSecret ||
+			!provider.credential.justification)
+	) {
+		diagnostics.push({
+			rule: "credential-reusable-secret",
+			level: "error",
+			field: "credential",
+			message: `${providerLabel} must set storesReusableSecret and justification when credential.keys includes reusable secrets.`,
+		});
+	}
+
+	if (authMode === "platform-managed" && credentialKeys.length > 0) {
+		diagnostics.push({
+			rule: "platform-managed-no-credential-keys",
+			level: "error",
+			field: "credential.keys",
+			message: `${providerLabel} must not declare credential.keys for platform-managed auth mode.`,
+		});
+	}
+
+	const authFlowSource = getAuthFlowSource(provider);
+	if (
+		authFlowSource.includes("ctx.context") &&
+		(provider.context?.keys?.length ?? 0) === 0
+	) {
+		diagnostics.push({
+			rule: "context-keys-required",
+			level: "warn",
+			field: "context.keys",
+			message: `${providerLabel} should declare context.keys when auth flow code accesses ctx.context.*.`,
+		});
+	}
+
+	return diagnostics;
+}
+
+function isSchema(value: unknown): value is SchemaLike {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		"safeParse" in value &&
+		typeof value.safeParse === "function"
+	);
+}
+
+function getSchemaDef(schema: SchemaLike): Record<string, unknown> {
+	const def = schema.def ?? schema._def;
+	if (def && typeof def === "object") {
+		return def;
+	}
+	return {};
+}
+
+function isSchemaRecord(value: unknown): value is Record<string, SchemaLike> {
+	if (!value || typeof value !== "object") {
+		return false;
+	}
+	for (const entry of Object.values(value)) {
+		if (!isSchema(entry)) {
+			return false;
+		}
+	}
+	return true;
+}
+
+function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
+	const rawShape =
+		typeof schema.shape === "function" ? schema.shape() : schema.shape;
+	if (isSchemaRecord(rawShape)) {
+		return rawShape;
+	}
+
+	const defShape = getSchemaDef(schema).shape;
+	if (typeof defShape === "function") {
+		const resolved = defShape();
+		if (isSchemaRecord(resolved)) {
+			return resolved;
+		}
+		return {};
+	}
+
+	if (isSchemaRecord(defShape)) {
+		return defShape;
+	}
+	return {};
+}
+
+function getChildSchemas(
+	schema: SchemaLike,
+): Array<{ key: string; schema: SchemaLike }> {
+	const seen = new Map<string, SchemaLike>();
+	const def = getSchemaDef(schema);
+
+	const add = (key: string, value: unknown) => {
+		if (!isSchema(value)) {
+			return;
+		}
+		seen.set(`${key}:${seen.size}`, value);
+	};
+
+	for (const [key, value] of Object.entries(getObjectShape(schema))) {
+		add(key, value);
+	}
+
+	add("element", schema.element);
+	add("innerType", schema.innerType);
+	add("unwrap", schema.unwrap?.());
+	add("sourceType", schema.sourceType?.());
+	add("in", schema.in);
+	add("out", schema.out);
+	add("left", schema.left);
+	add("right", schema.right);
+
+	if (Array.isArray(schema.items)) {
+		for (const [index, item] of schema.items.entries()) {
+			add(String(index), item);
+		}
+	}
+
+	if (Array.isArray(def.items)) {
+		for (const [index, item] of def.items.entries()) {
+			add(String(index), item);
+		}
+	}
+
+	const options = schema.options ?? def.options;
+	if (Array.isArray(options)) {
+		for (const [index, option] of options.entries()) {
+			add(String(index), option);
+		}
+	} else if (options instanceof Set) {
+		for (const [index, option] of Array.from(options).entries()) {
+			add(String(index), option);
+		}
+	} else if (options instanceof Map) {
+		for (const [key, option] of options.entries()) {
+			add(String(key), option);
+		}
+	}
+
+	for (const key of [
+		"schema",
+		"innerType",
+		"type",
+		"valueType",
+		"keyType",
+		"item",
+		"rest",
+		"catchall",
+		"option",
+		"pipe",
+		"payload",
+		"shape",
+	]) {
+		const value = def[key];
+		if (Array.isArray(value)) {
+			for (const [index, item] of value.entries()) {
+				add(`${key}.${index}`, item);
+			}
+		} else {
+			add(key, value);
+		}
+	}
+
+	return Array.from(seen.entries()).map(([entryKey, child]) => ({
+		key: entryKey.split(":")[0] ?? entryKey,
+		schema: child,
+	}));
+}
+
+function collectMissingDescriptions(
+	schema: unknown,
+	basePath: string,
+	seen = new Set<SchemaLike>(),
+): string[] {
+	if (!isSchema(schema) || seen.has(schema)) {
+		return [];
+	}
+
+	seen.add(schema);
+	const missing: string[] = [];
+	const currentPath = basePath || "schema";
+
+	if (!schema.description) {
+		missing.push(currentPath);
+	}
+
+	for (const child of getChildSchemas(schema)) {
+		const isWrapperNode = [
+			"unwrap",
+			"innerType",
+			"sourceType",
+			"schema",
+			"type",
+			"option",
+			"pipe",
+			"payload",
+			"item",
+			"rest",
+			"catchall",
+		].includes(child.key);
+		const childPath = isWrapperNode
+			? currentPath
+			: currentPath === "schema"
+				? child.key
+				: /^\d+$/.test(child.key)
+					? `${currentPath}[${child.key}]`
+					: child.key.startsWith("element")
+						? `${currentPath}[]`
+						: `${currentPath}.${child.key}`;
+		missing.push(...collectMissingDescriptions(child.schema, childPath, seen));
+	}
+
+	return missing;
+}
+
+function uniqueFields(fields: string[]): string[] {
+	return Array.from(new Set(fields));
+}
+
+function isComplexSchema(
+	schema: unknown,
+	seen = new Set<SchemaLike>(),
+): boolean {
+	if (!isSchema(schema) || seen.has(schema)) {
+		return false;
+	}
+
+	seen.add(schema);
+	const children = getChildSchemas(schema);
+	const hasNestedComposite = children.some(({ schema: child }) => {
+		const childChildren = getChildSchemas(child);
+		return childChildren.length > 0;
+	});
+
+	return (
+		hasNestedComposite ||
+		children.some(({ schema: child }) => isComplexSchema(child, seen))
+	);
+}
+
+function hasBidirectionalFixtures(fixtures: unknown): boolean {
+	if (!fixtures || typeof fixtures !== "object") {
+		return true;
+	}
+
+	return "request" in fixtures && "response" in fixtures;
+}
+
+export function lintOperation(op: {
+	description: string;
+	input: unknown;
+	output: unknown;
+	fixtures?: unknown;
+	inputExamples?: unknown[];
+	derivations?: Record<string, string>;
+}): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [];
+	const description = op.description ?? "";
+
+	if (description.length < 150) {
+		diagnostics.push({
+			rule: "description-min-length",
+			level: "error",
+			field: "description",
+			message: "Operation description must be at least 150 characters.",
+		});
+	}
+
+	const lowerDescription = description.toLowerCase();
+	if (
+		!(lowerDescription.includes("use") && lowerDescription.includes("when"))
+	) {
+		diagnostics.push({
+			rule: "description-has-when-clause",
+			level: "warn",
+			field: "description",
+			message: 'Operation description should include both "use" and "when".',
+		});
+	}
+
+	for (const field of uniqueFields(
+		collectMissingDescriptions(op.input, "input"),
+	)) {
+		diagnostics.push({
+			rule: "all-fields-described",
+			level: "error",
+			field,
+			message: `Schema field "${field}" is missing a description.`,
+		});
+	}
+
+	for (const field of uniqueFields(
+		collectMissingDescriptions(op.output, "output"),
+	)) {
+		diagnostics.push({
+			rule: "all-fields-described",
+			level: "error",
+			field,
+			message: `Schema field "${field}" is missing a description.`,
+		});
+	}
+
+	if (!hasBidirectionalFixtures(op.fixtures)) {
+		diagnostics.push({
+			rule: "fixtures-both-directions",
+			level: "error",
+			field: "fixtures",
+			message: "Fixtures must include both request and response.",
+		});
+	}
+
+	if (isComplexSchema(op.input) && (op.inputExamples?.length ?? 0) < 2) {
+		diagnostics.push({
+			rule: "complex-input-has-examples",
+			level: "warn",
+			field: "inputExamples",
+			message:
+				"Complex input schemas should provide at least 2 input examples.",
+		});
+	}
+
+	return diagnostics;
+}
+
+export function lintProvider(provider: {
+	id?: string;
+	allowedHosts?: string[];
+	auth?: ProviderAuthLike;
+	credential?: {
+		keys?: string[];
+		storesReusableSecret?: boolean;
+		justification?: string;
+	};
+	context?: {
+		keys?: string[];
+	};
+	authFlowSource?: string;
+	operations?: Record<
+		string,
+		{
+			description?: string;
+			input: unknown;
+			output: unknown;
+			fixtures?: unknown;
+			inputExamples?: unknown[];
+			derivations?: Record<string, string>;
+		}
+	>;
+	reviewed?: string;
+}): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [
+		...lintAllowedHosts(provider.id, provider.allowedHosts),
+		...lintReviewed(provider.id, provider.reviewed),
+		...lintAuthModel(provider),
+	];
+
+	if (!provider.operations) {
+		return diagnostics;
+	}
+
+	diagnostics.push(
+		...Object.entries(provider.operations).flatMap(
+			([operationKey, operation]) =>
+				lintOperation({
+					description: operation.description ?? "",
+					input: operation.input,
+					output: operation.output,
+					fixtures: operation.fixtures,
+					inputExamples: operation.inputExamples,
+					derivations: operation.derivations,
+				}).map((diagnostic) => ({
+					...diagnostic,
+					field: diagnostic.field
+						? `operations.${operationKey}.${diagnostic.field}`
+						: `operations.${operationKey}`,
+					message: `[${operationKey}] ${diagnostic.message}`,
+				})),
+		),
+	);
+
+	return diagnostics;
+}

package/src/provider.ts

@@ -0,0 +1,14 @@
+export { z } from "zod";
+
+export { createFormCeremony } from "./ceremonies";
+export { defineCompositeOperation } from "./composite";
+export { defineOperation, defineProvider } from "./define";
+export { AuthError, ProviderError, ValidationError } from "./errors";
+export type {
+	FlowContext,
+	InferSchemaOutput,
+	OperationDefinition,
+	ProviderContext,
+	SchemaLike,
+	StandardSchemaV1,
+} from "./types";

package/src/runtime/auth-flow.ts

@@ -0,0 +1,67 @@
+import { ContextAccessError } from "../errors";
+import type {
+	ContextScratchpad,
+	EnvContext,
+	FlowContext,
+	HttpClient,
+} from "../types";
+
+function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
+	return new Set(allowedKeys.filter((key) => key.trim().length > 0));
+}
+
+function assertAllowedKey(allowedKeys: Set<string>, key: string): void {
+	if (!allowedKeys.has(key)) {
+		throw new ContextAccessError(
+			`Context key "${key}" is not declared in context.keys.`,
+		);
+	}
+}
+
+export function createScratchpad(
+	allowedKeys: string[],
+	initial: Record<string, unknown> = {},
+): ContextScratchpad {
+	const normalizedAllowedKeys = normalizeAllowedKeys(allowedKeys);
+	const values = new Map<string, unknown>();
+
+	for (const [key, value] of Object.entries(initial)) {
+		assertAllowedKey(normalizedAllowedKeys, key);
+		values.set(key, value);
+	}
+
+	return {
+		get(key: string): unknown {
+			assertAllowedKey(normalizedAllowedKeys, key);
+			return values.get(key);
+		},
+		set(key: string, value: unknown): void {
+			assertAllowedKey(normalizedAllowedKeys, key);
+			values.set(key, value);
+		},
+		toJSON(): Record<string, unknown> {
+			return Object.fromEntries(values.entries());
+		},
+	};
+}
+
+export function createFlowContext(options: {
+	http: HttpClient;
+	env: EnvContext;
+	tenantId: string;
+	providerId: string;
+	connectionId?: string;
+	externalRef?: string;
+	allowedKeys: string[];
+	initialContext?: Record<string, unknown>;
+}): FlowContext {
+	return {
+		connectionId: options.connectionId,
+		externalRef: options.externalRef,
+		tenantId: options.tenantId,
+		providerId: options.providerId,
+		http: options.http,
+		env: options.env,
+		context: createScratchpad(options.allowedKeys, options.initialContext),
+	};
+}