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

package/src/server/serve.ts

@@ -0,0 +1,624 @@
+import { Hono } from "hono";
+import { z } from "zod";
+
+import { ProviderError, TransportError } from "../errors";
+import { createScratchpad } from "../runtime/auth-flow";
+import { createBrowserClient } from "../runtime/browser";
+import { createCredentialContext } from "../runtime/credential";
+import { createEnvContext } from "../runtime/env";
+import { executeOperation } from "../runtime/executor";
+import { createHttpClient } from "../runtime/http";
+import { getProviderBaseUrl } from "../runtime/provider";
+import { createTlsClient } from "../runtime/tls";
+import { createTraceContext } from "../runtime/trace";
+import type {
+	AuthContext,
+	BrowserClient,
+	FlowContext,
+	FlowContextStore,
+	ProviderContext,
+	ProviderDefinition,
+	TlsClient,
+} from "../types";
+import {
+	type AuthFlowRequest,
+	AuthFlowRequestSchema,
+	type AuthFlowResponse,
+	type AuthFlowSuccessResponse,
+	type OperationErrorResponse,
+	type OperationRequest,
+	OperationRequestSchema,
+	type OperationResponse,
+	type OperationSuccessResponse,
+} from "./types";
+
+const DEFAULT_HOST = "0.0.0.0";
+const DEFAULT_PORT = 3000;
+
+function createAuthStub(): AuthContext {
+	return {
+		async requestField(name) {
+			throw new ProviderError(`Auth prompt is unavailable for ${name}`, {
+				code: "AUTH_PROMPT_UNAVAILABLE",
+			});
+		},
+	};
+}
+
+function createBrowserStub(): BrowserClient {
+	return {
+		engine: "playwright-stealth",
+		async newPage() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+	};
+}
+
+function createTlsStub(): TlsClient {
+	return {
+		async fetch() {
+			throw new ProviderError("TLS runtime is not available", {
+				code: "TLS_RUNTIME_UNSUPPORTED",
+			});
+		},
+		createSession() {
+			throw new ProviderError("TLS runtime is not available", {
+				code: "TLS_RUNTIME_UNSUPPORTED",
+			});
+		},
+	};
+}
+
+function createProviderContext(
+	provider: ProviderDefinition,
+	request: OperationRequest,
+): ProviderContext {
+	const baseUrl = getProviderBaseUrl(provider);
+
+	return {
+		env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
+		credential: createCredentialContext({
+			allowedKeys: provider.credential?.keys,
+			mode: request.connection?.mode,
+			scopes: request.connection?.scopes,
+			values: request.connection?.secrets,
+		}),
+		request: {
+			connectionId: request.connection?.id,
+			headers: request.headers ?? {},
+		},
+		http: createHttpClient(baseUrl),
+		tls: baseUrl ? createTlsClient(baseUrl) : createTlsStub(),
+		browser:
+			provider.runtime === "browser"
+				? createBrowserClient({
+						cdpUrl:
+							process.env.CDP_POOL_URL ?? process.env.APIFUSE_CDP_POOL_URL,
+						headless: true,
+						stealth: true,
+						engine: provider.browser?.engine,
+					})
+				: createBrowserStub(),
+		trace: createTraceContext(),
+		auth: createAuthStub(),
+	};
+}
+
+function createFlowContextStore(
+	allowedKeys: string[],
+	initialContext: Record<string, unknown> = {},
+): {
+	context: FlowContextStore;
+	getPatch: () => Record<string, unknown | null> | undefined;
+} {
+	const context = createScratchpad(allowedKeys, initialContext);
+
+	return {
+		context,
+		getPatch() {
+			const next = context.toJSON();
+			const patch = new Map<string, unknown | null>();
+
+			for (const [key, value] of Object.entries(next)) {
+				if (initialContext[key] !== value) {
+					patch.set(key, value);
+				}
+			}
+
+			for (const key of Object.keys(initialContext)) {
+				if (!(key in next)) {
+					patch.set(key, null);
+				}
+			}
+
+			if (patch.size === 0) {
+				return undefined;
+			}
+
+			return Object.fromEntries(patch.entries());
+		},
+	};
+}
+
+function createAuthFlowContext(
+	provider: ProviderDefinition,
+	request: AuthFlowRequest,
+): {
+	context: FlowContext;
+	getPatch: () => Record<string, unknown | null> | undefined;
+} {
+	const baseUrl = getProviderBaseUrl(provider);
+	const contextData = request.context ?? {};
+	const flowContextStore = createFlowContextStore(
+		provider.context?.keys ?? Object.keys(contextData),
+		contextData,
+	);
+
+	return {
+		context: {
+			connectionId: request.connectionId,
+			externalRef: request.externalRef,
+			tenantId: request.tenantId ?? "",
+			providerId: request.providerId ?? provider.id,
+			http: createHttpClient(baseUrl),
+			env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
+			context: flowContextStore.context,
+		},
+		getPatch: flowContextStore.getPatch,
+	};
+}
+
+export type ProviderServerLogEvent = {
+	level: "warn" | "error";
+	event: "provider_request_failed";
+	providerId: string;
+	kind: "operation" | "auth";
+	route: string;
+	requestId?: string;
+	status: number;
+	code: string;
+	errorClass: string;
+	message: string;
+	upstreamStatus?: number;
+	issues?: Array<{ path: string; code: string; message: string }>;
+};
+
+export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
+
+export type ProviderServerOptions = {
+	logger?: ProviderServerLogger;
+};
+
+const defaultProviderServerLogger: ProviderServerLogger = (event) => {
+	console.error(JSON.stringify(event));
+};
+
+function zodDetails(error: z.ZodError): Array<{
+	path: string;
+	code: string;
+	message: string;
+}> {
+	return error.issues.map((issue) => ({
+		path: issue.path.join("."),
+		code: issue.code,
+		message: issue.message,
+	}));
+}
+
+function toErrorResponse(
+	error: unknown,
+	requestId?: string,
+): OperationErrorResponse {
+	if (error instanceof ProviderError) {
+		return {
+			error: {
+				code: error.code ?? "provider_error",
+				message: publicProviderErrorMessage(error),
+				...(requestId ? { requestId } : {}),
+				...(error instanceof TransportError && error.status
+					? { details: { upstreamStatus: error.status } }
+					: {}),
+			},
+		};
+	}
+
+	if (error instanceof z.ZodError) {
+		return {
+			error: {
+				code: "invalid_request",
+				message: "Invalid request body",
+				...(requestId ? { requestId } : {}),
+				details: zodDetails(error),
+			},
+		};
+	}
+
+	return {
+		error: {
+			code: "internal_error",
+			message: "Internal error",
+			...(requestId ? { requestId } : {}),
+		},
+	};
+}
+
+function publicProviderErrorMessage(error: ProviderError): string {
+	if (error instanceof TransportError) {
+		if (error.code === "transport_timeout") return "Request timed out";
+		if (error.code === "transport_network_error") return "Network error";
+		if (error.code === "upstream_http_error" && error.status) {
+			return `Upstream request failed with status ${error.status}`;
+		}
+		if (error.status) {
+			return `Upstream request failed with status ${error.status}`;
+		}
+		return "Upstream request failed";
+	}
+	return error.message;
+}
+
+function toStatusCode(error: unknown): 400 | 404 | 500 | 502 | 504 {
+	if (error instanceof z.ZodError) {
+		return 400;
+	}
+
+	if (error instanceof TransportError) {
+		return error.code === "transport_timeout" ? 504 : 502;
+	}
+
+	if (error instanceof ProviderError) {
+		if (error.code === "NOT_FOUND" || error.code === "NO_DATA") {
+			return 404;
+		}
+
+		return 400;
+	}
+
+	return 500;
+}
+
+function extractRequestId(raw: unknown): string | undefined {
+	if (!raw || typeof raw !== "object") {
+		return undefined;
+	}
+
+	const value = Object.getOwnPropertyDescriptor(raw, "requestId")?.value;
+	return typeof value === "string" ? value : undefined;
+}
+
+function logProviderError(
+	logger: ProviderServerLogger | unknown,
+	provider: ProviderDefinition,
+	kind: "operation" | "auth",
+	route: string,
+	requestId: string | undefined,
+	error: unknown,
+	status: number,
+): void {
+	const code =
+		error instanceof ProviderError
+			? (error.code ?? "provider_error")
+			: error instanceof z.ZodError
+				? "invalid_request"
+				: "internal_error";
+	const errorClass = error instanceof Error ? error.name : typeof error;
+	const message = error instanceof Error ? error.message : String(error);
+	const emit =
+		typeof logger === "function" ? logger : defaultProviderServerLogger;
+	emit({
+		level: status >= 500 ? "error" : "warn",
+		event: "provider_request_failed",
+		providerId: provider.id,
+		kind,
+		route,
+		...(requestId ? { requestId } : {}),
+		status,
+		code,
+		errorClass,
+		message,
+		...(error instanceof TransportError && error.status
+			? { upstreamStatus: error.status }
+			: {}),
+		...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
+	});
+}
+
+function toJsonSuccessResponse(
+	result: unknown,
+): Response | OperationSuccessResponse {
+	if (result instanceof Response) {
+		return result;
+	}
+
+	if (result instanceof ReadableStream) {
+		return new Response(result);
+	}
+
+	return { data: result };
+}
+
+function toAuthFlowResponse(
+	result: unknown,
+	contextPatch: Record<string, unknown | null> | undefined,
+): Response | AuthFlowSuccessResponse {
+	if (result instanceof Response) {
+		return result;
+	}
+
+	if (result instanceof ReadableStream) {
+		return new Response(result);
+	}
+
+	return {
+		data: result,
+		...(contextPatch ? { contextPatch } : {}),
+	};
+}
+
+async function handleOperation(
+	provider: ProviderDefinition,
+	request: OperationRequest,
+	operationId: string,
+): Promise<Response | OperationResponse> {
+	const ctx = createProviderContext(provider, request);
+	const result = await executeOperation(
+		provider,
+		operationId,
+		ctx,
+		request.input,
+	);
+	return toJsonSuccessResponse(result);
+}
+
+type AuthRoute = "start" | "continue" | "poll" | "abort";
+
+async function handleAuthFlow(
+	provider: ProviderDefinition,
+	request: AuthFlowRequest,
+	route: AuthRoute,
+): Promise<Response | AuthFlowResponse> {
+	const flow = provider.auth?.flow;
+	if (!flow) {
+		throw new ProviderError("Auth flow is not configured", {
+			code: "AUTH_FLOW_NOT_CONFIGURED",
+		});
+	}
+
+	const { context, getPatch } = createAuthFlowContext(provider, request);
+
+	const result =
+		route === "start"
+			? await flow.start(context)
+			: route === "continue"
+				? await flow.continue(context, request.input ?? {})
+				: route === "poll"
+					? flow.poll
+						? await flow.poll(context)
+						: null
+					: flow.abort
+						? await flow.abort(context)
+						: null;
+
+	return toAuthFlowResponse(result, getPatch());
+}
+
+export function createServerApp(
+	provider: ProviderDefinition,
+	options: ProviderServerOptions = {},
+): Hono {
+	const app = new Hono();
+	const logger = options.logger ?? defaultProviderServerLogger;
+
+	app.notFound((c) =>
+		c.json(
+			{
+				error: {
+					code: "not_found",
+					message: "Not found",
+				},
+			},
+			404,
+		),
+	);
+
+	app.get("/health", (c) =>
+		c.json({
+			status: "ok",
+			provider: provider.id,
+			version: provider.version,
+		}),
+	);
+
+	app.post("/v1/:operation", async (c) => {
+		let rawBody: unknown;
+		const operation = c.req.param("operation");
+		try {
+			rawBody = await c.req.raw
+				.clone()
+				.json()
+				.catch(() => undefined);
+			const body = OperationRequestSchema.parse(rawBody);
+			const requestHeaders = Object.fromEntries(c.req.raw.headers.entries());
+			body.headers = { ...requestHeaders, ...body.headers };
+			const response = await handleOperation(provider, body, operation);
+			return response instanceof Response ? response : c.json(response);
+		} catch (error) {
+			const status = toStatusCode(error);
+			const requestId = extractRequestId(rawBody);
+			logProviderError(
+				logger,
+				provider,
+				"operation",
+				operation,
+				requestId,
+				error,
+				status,
+			);
+			return c.json(toErrorResponse(error, requestId), status);
+		}
+	});
+
+	app.post("/auth/start", async (c) => {
+		let rawBody: unknown;
+		try {
+			rawBody = await c.req.raw
+				.clone()
+				.json()
+				.catch(() => undefined);
+			const body = AuthFlowRequestSchema.parse(rawBody);
+			const response = await handleAuthFlow(provider, body, "start");
+			return response instanceof Response ? response : c.json(response);
+		} catch (error) {
+			const status = toStatusCode(error);
+			const requestId = extractRequestId(rawBody);
+			logProviderError(
+				logger,
+				provider,
+				"auth",
+				"start",
+				requestId,
+				error,
+				status,
+			);
+			return c.json(toErrorResponse(error, requestId), status);
+		}
+	});
+
+	app.post("/auth/continue", async (c) => {
+		let rawBody: unknown;
+		try {
+			rawBody = await c.req.raw
+				.clone()
+				.json()
+				.catch(() => undefined);
+			const body = AuthFlowRequestSchema.parse(rawBody);
+			const response = await handleAuthFlow(provider, body, "continue");
+			return response instanceof Response ? response : c.json(response);
+		} catch (error) {
+			const status = toStatusCode(error);
+			const requestId = extractRequestId(rawBody);
+			logProviderError(
+				logger,
+				provider,
+				"auth",
+				"continue",
+				requestId,
+				error,
+				status,
+			);
+			return c.json(toErrorResponse(error, requestId), status);
+		}
+	});
+
+	app.post("/auth/poll", async (c) => {
+		let rawBody: unknown;
+		try {
+			rawBody = await c.req.raw
+				.clone()
+				.json()
+				.catch(() => undefined);
+			const body = AuthFlowRequestSchema.parse(rawBody);
+			const response = await handleAuthFlow(provider, body, "poll");
+			return response instanceof Response ? response : c.json(response);
+		} catch (error) {
+			const status = toStatusCode(error);
+			const requestId = extractRequestId(rawBody);
+			logProviderError(
+				logger,
+				provider,
+				"auth",
+				"poll",
+				requestId,
+				error,
+				status,
+			);
+			return c.json(toErrorResponse(error, requestId), status);
+		}
+	});
+
+	app.post("/auth/disconnect", async (c) => {
+		let rawBody: unknown;
+		try {
+			rawBody = await c.req.raw
+				.clone()
+				.json()
+				.catch(() => undefined);
+			const body = AuthFlowRequestSchema.parse(rawBody);
+			const response = await handleAuthFlow(provider, body, "abort");
+			return response instanceof Response ? response : c.json(response);
+		} catch (error) {
+			const status = toStatusCode(error);
+			const requestId = extractRequestId(rawBody);
+			logProviderError(
+				logger,
+				provider,
+				"auth",
+				"disconnect",
+				requestId,
+				error,
+				status,
+			);
+			return c.json(toErrorResponse(error, requestId), status);
+		}
+	});
+
+	return app;
+}
+
+type BunServeRuntime = {
+	serve: (options: {
+		port: number;
+		hostname: string;
+		fetch: (request: Request) => Response | Promise<Response>;
+	}) => unknown;
+};
+
+function getBunServeRuntime(): BunServeRuntime | undefined {
+	const bunValue = Object.getOwnPropertyDescriptor(globalThis, "Bun")?.value;
+	if (!bunValue || typeof bunValue !== "object") {
+		return undefined;
+	}
+
+	const serve = Object.getOwnPropertyDescriptor(bunValue, "serve")?.value;
+	if (typeof serve !== "function") {
+		return undefined;
+	}
+
+	return {
+		serve(options) {
+			return serve(options);
+		},
+	};
+}
+
+export interface ServeOptions extends ProviderServerOptions {
+	host?: string;
+	port?: number;
+}
+
+export async function serve(
+	provider: ProviderDefinition,
+	options: ServeOptions = {},
+): Promise<void> {
+	const bunRuntime = getBunServeRuntime();
+
+	if (bunRuntime === undefined) {
+		throw new ProviderError(
+			"Bun runtime is required to start the provider server",
+			{
+				code: "RUNTIME_UNSUPPORTED",
+			},
+		);
+	}
+
+	const app = createServerApp(provider, { logger: options.logger });
+
+	bunRuntime.serve({
+		port: options.port ?? DEFAULT_PORT,
+		hostname: options.host ?? DEFAULT_HOST,
+		fetch: app.fetch,
+	});
+	await Promise.resolve();
+}

package/src/server/types.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+export const ConnectionModeSchema = z.enum([
+	"oauth2",
+	"credentials",
+	"platform-managed",
+	"none",
+]);
+
+export const OperationConnectionSchema = z.object({
+	id: z.string(),
+	mode: ConnectionModeSchema,
+	secrets: z.record(z.string(), z.string()),
+	scopes: z.array(z.string()).optional(),
+	metadata: z.record(z.string(), z.unknown()),
+	externalRef: z.string(),
+});
+
+export const OperationRequestSchema = z.object({
+	requestId: z.string(),
+	input: z.record(z.string(), z.unknown()),
+	connection: OperationConnectionSchema.optional(),
+	headers: z.record(z.string(), z.string()).optional(),
+	trace: z.record(z.string(), z.string()).optional(),
+});
+
+export const ErrorEnvelopeSchema = z.object({
+	code: z.string(),
+	message: z.string(),
+	requestId: z.string().optional(),
+	fix: z.string().optional(),
+	details: z.unknown().optional(),
+});
+
+export const OperationSuccessResponseSchema = z.object({
+	data: z.unknown(),
+});
+
+export const OperationErrorResponseSchema = z.object({
+	error: ErrorEnvelopeSchema,
+});
+
+export const AuthFlowRequestSchema = z.object({
+	requestId: z.string(),
+	flowId: z.string(),
+	connectionId: z.string().optional(),
+	externalRef: z.string().optional(),
+	tenantId: z.string().optional(),
+	providerId: z.string().optional(),
+	input: z.record(z.string(), z.unknown()).optional(),
+	context: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const AuthFlowSuccessResponseSchema = z.object({
+	data: z.unknown(),
+	contextPatch: z.record(z.string(), z.unknown().nullable()).optional(),
+});
+
+export const AuthFlowErrorResponseSchema = OperationErrorResponseSchema;
+
+export type ConnectionMode = z.infer<typeof ConnectionModeSchema>;
+export type OperationConnection = z.infer<typeof OperationConnectionSchema>;
+export type OperationRequest = z.infer<typeof OperationRequestSchema>;
+export type OperationSuccessResponse = z.infer<
+	typeof OperationSuccessResponseSchema
+>;
+export type OperationErrorResponse = z.infer<
+	typeof OperationErrorResponseSchema
+>;
+export type OperationResponse =
+	| OperationSuccessResponse
+	| OperationErrorResponse;
+export type AuthFlowRequest = z.infer<typeof AuthFlowRequestSchema>;
+export type AuthFlowSuccessResponse = z.infer<
+	typeof AuthFlowSuccessResponseSchema
+>;
+export type AuthFlowErrorResponse = z.infer<typeof AuthFlowErrorResponseSchema>;
+export type AuthFlowResponse = AuthFlowSuccessResponse | AuthFlowErrorResponse;