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

package/src/serve.ts

@@ -1,664 +1 @@
-import { Hono } from "hono";
-import { type ZodType, z } from "zod";
-
-import { ProviderError } from "./errors";
-import type {
-	ConnectRequest,
-	ConnectResponse,
-	ContainerErrorResponse,
-	DisconnectRequest,
-	DisconnectResponse,
-	ExecuteRequest,
-	ExecuteResponse,
-	HealthResponse,
-	RefreshRequest,
-	RefreshResponse,
-	ResumeRequest,
-	ResumeResponse,
-	SchemaResponse,
-} from "./protocol";
-import { createBrowserClient } from "./runtime/browser";
-import { executeOperation } from "./runtime/executor";
-import { createHttpClient } from "./runtime/http";
-import { getProviderBaseUrl } from "./runtime/provider";
-import { createStateContext } from "./runtime/state";
-import { createTlsClient } from "./runtime/tls";
-import { createTraceContext, type TraceContext } from "./runtime/trace";
-import type {
-	AuthContext,
-	BrowserClient,
-	ProviderContext,
-	ProviderDefinition,
-	SessionStore,
-	TlsClient,
-} from "./types";
-
-const AUTH_SESSION_KEY = "__auth__";
-const DEFAULT_PORT = 3900;
-
-type ErrorStatusCode = 400 | 404 | 500;
-
-type SessionPatch = Record<string, string | null>;
-
-type PendingAuthState = {
-	credentials: Record<string, string>;
-	resolvedFields: Record<string, string>;
-	requestedField: string;
-};
-
-class PendingFieldError extends Error {
-	constructor(readonly field: string) {
-		super(`Pending auth field: ${field}`);
-		this.name = "PendingFieldError";
-	}
-}
-
-function createSessionOverlay(snapshot: Record<string, string> = {}): {
-	store: SessionStore;
-	getPatch: () => SessionPatch;
-} {
-	const data = new Map<string, string>(Object.entries(snapshot));
-	const patch: SessionPatch = {};
-
-	return {
-		store: {
-			async get(key: string): Promise<string | null> {
-				return data.get(key) ?? null;
-			},
-			async set(key: string, value: string): Promise<void> {
-				data.set(key, value);
-				patch[key] = value;
-			},
-			async delete(key: string): Promise<void> {
-				data.delete(key);
-				patch[key] = null;
-			},
-		},
-		getPatch: () => ({ ...patch }),
-	};
-}
-
-function createBrowserStub(): BrowserClient {
-	return {
-		engine: "playwright-stealth",
-		async newPage() {
-			throw new ProviderError("Browser runtime is not available", {
-				code: "BROWSER_RUNTIME_UNSUPPORTED",
-			});
-		},
-	};
-}
-
-async function closeBrowserRuntime(browser: BrowserClient): Promise<void> {
-	if (!Reflect.has(browser as object, "close")) {
-		return;
-	}
-
-	await (browser as BrowserClient & { close(): Promise<void> }).close();
-}
-
-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 createAuthSessionMarker(
-	marker: Record<string, boolean | number>,
-): string {
-	return JSON.stringify(marker);
-}
-
-function toSessionSnapshot(
-	snapshot: Record<string, string> | undefined,
-): Record<string, string> {
-	return snapshot ?? {};
-}
-
-function toStringRecord(value: unknown): Record<string, string> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return {};
-	}
-
-	return Object.fromEntries(
-		Object.entries(value).map(([key, entryValue]) => [key, String(entryValue)]),
-	);
-}
-
-function toErrorEnvelope(
-	error: unknown,
-	overrides?: Partial<ContainerErrorResponse["error"]>,
-): ContainerErrorResponse {
-	const providerError = error instanceof ProviderError ? error : null;
-	const fallbackMessage =
-		error instanceof Error ? error.message : "Unknown error";
-
-	return {
-		error: {
-			code: overrides?.code ?? providerError?.code ?? "INTERNAL_ERROR",
-			message: overrides?.message ?? fallbackMessage,
-			...(overrides?.details !== undefined
-				? { details: overrides.details }
-				: providerError?.options?.fix
-					? { details: { fix: providerError.options.fix } }
-					: {}),
-		},
-	};
-}
-
-function getStatusCode(error: unknown): ErrorStatusCode {
-	if (error instanceof ProviderError && error.code === "NOT_FOUND") {
-		return 404;
-	}
-
-	if (error instanceof z.ZodError) {
-		return 400;
-	}
-
-	return 500;
-}
-
-function getFieldLabel(
-	provider: ProviderDefinition,
-	fieldName: string,
-): string | undefined {
-	return provider.auth?.fields?.find((field) => field.name === fieldName)
-		?.label;
-}
-
-function toConnectFailedResponse(error: unknown): ConnectResponse {
-	return {
-		status: "failed",
-		error:
-			error instanceof ProviderError
-				? (error.code ?? "AUTH_FAILED")
-				: "AUTH_FAILED",
-		message: error instanceof Error ? error.message : "Authentication failed",
-	};
-}
-
-function toRefreshFailedResponse(error: unknown): RefreshResponse {
-	return {
-		status: "failed",
-		error:
-			error instanceof ProviderError
-				? (error.code ?? "REFRESH_FAILED")
-				: "REFRESH_FAILED",
-		message: error instanceof Error ? error.message : "Refresh failed",
-	};
-}
-
-function toDisconnectFailedResponse(error: unknown): DisconnectResponse {
-	return {
-		status: "failed",
-		error:
-			error instanceof ProviderError
-				? (error.code ?? "DISCONNECT_FAILED")
-				: error instanceof Error
-					? error.message
-					: "DISCONNECT_FAILED",
-	};
-}
-
-function toSchema(schema: ZodType): Record<string, unknown> {
-	const zodModule = z as typeof z & {
-		toJSONSchema?: (schema: ZodType) => Record<string, unknown>;
-	};
-	const schemaWithMethod = schema as ZodType & {
-		toJSONSchema?: () => Record<string, unknown>;
-	};
-
-	if (typeof zodModule.toJSONSchema === "function") {
-		return zodModule.toJSONSchema(schema);
-	}
-
-	if (typeof schemaWithMethod.toJSONSchema === "function") {
-		return schemaWithMethod.toJSONSchema();
-	}
-
-	throw new ProviderError("Zod JSON Schema conversion is unavailable", {
-		code: "SCHEMA_CONVERSION_UNAVAILABLE",
-	});
-}
-
-function getTracePayload(
-	trace: TraceContext,
-): ExecuteResponse["trace"] | undefined {
-	const spans = trace.getSpans();
-	return spans.length > 0 ? { spans } : undefined;
-}
-
-function toStringSessionPatch(
-	sessionPatch: SessionPatch,
-): Record<string, string> {
-	return Object.fromEntries(
-		Object.entries(sessionPatch).filter(
-			(entry): entry is [string, string] => entry[1] !== null,
-		),
-	);
-}
-
-function assertAuthConfigured(
-	provider: ProviderDefinition,
-): asserts provider is ProviderDefinition & {
-	auth: NonNullable<ProviderDefinition["auth"]>;
-} {
-	if (!provider.auth || provider.auth.mode === "none") {
-		throw new ProviderError("Auth is not configured", {
-			code: "AUTH_NOT_CONFIGURED",
-		});
-	}
-
-	if (!provider.auth.exchange) {
-		throw new ProviderError("Auth exchange is not configured", {
-			code: "AUTH_EXCHANGE_NOT_CONFIGURED",
-		});
-	}
-}
-
-function createContainerContext(
-	provider: ProviderDefinition,
-	sessionSnapshot: Record<string, string> = {},
-	options: {
-		auth?: AuthContext;
-		baseUrl?: string;
-		stateSecret?: string;
-	} = {},
-): {
-	ctx: ProviderContext;
-	getSessionPatch: () => SessionPatch;
-	close: () => Promise<void>;
-	trace: TraceContext;
-} {
-	const overlay = createSessionOverlay(sessionSnapshot);
-	const trace = createTraceContext({ onSpan: () => {} });
-	const resolvedBaseUrl = options.baseUrl ?? getProviderBaseUrl(provider);
-	const 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();
-	const tls = resolvedBaseUrl
-		? createTlsClient(resolvedBaseUrl)
-		: createTlsStub();
-
-	const ctx: ProviderContext = {
-		http: createHttpClient(resolvedBaseUrl),
-		tls,
-		browser,
-		session: overlay.store,
-		state: createStateContext(options.stateSecret),
-		trace,
-		auth:
-			options.auth ??
-			({
-				async requestField(name: string): Promise<string> {
-					throw new ProviderError(`Deferred auth field requested: ${name}`, {
-						code: "AUTH_FIELD_REQUESTED",
-					});
-				},
-			} satisfies AuthContext),
-	};
-
-	return {
-		ctx,
-		getSessionPatch: overlay.getPatch,
-		close: async () => await closeBrowserRuntime(browser),
-		trace,
-	};
-}
-
-async function runAuthExchange(
-	provider: ProviderDefinition,
-	credentials: Record<string, string>,
-	sessionSnapshot: Record<string, string>,
-	resolvedFields: Record<string, string>,
-	options: {
-		baseUrl?: string;
-		stateSecret?: string;
-	},
-): Promise<
-	| { type: "success"; sessionPatch: Record<string, string> }
-	| {
-			type: "pending_field";
-			field: string;
-			fieldLabel?: string;
-			resumeToken: string;
-			sessionPatch?: Record<string, string>;
-	  }
-> {
-	assertAuthConfigured(provider);
-	const auth = provider.auth as NonNullable<ProviderDefinition["auth"]> & {
-		exchange: NonNullable<NonNullable<ProviderDefinition["auth"]>["exchange"]>;
-	};
-
-	let requestedField: string | null = null;
-	const { ctx, getSessionPatch, close } = createContainerContext(
-		provider,
-		sessionSnapshot,
-		{
-			baseUrl: options.baseUrl,
-			stateSecret: options.stateSecret,
-			auth: {
-				async requestField(name: string): Promise<string> {
-					const resolvedValue = resolvedFields[name];
-					if (resolvedValue !== undefined) {
-						return resolvedValue;
-					}
-
-					requestedField = name;
-					throw new PendingFieldError(name);
-				},
-			},
-		},
-	);
-
-	try {
-		await auth.exchange(ctx, credentials);
-		await ctx.session.set(
-			AUTH_SESSION_KEY,
-			createAuthSessionMarker({ authenticated: true, timestamp: Date.now() }),
-		);
-		return {
-			type: "success",
-			sessionPatch: toStringSessionPatch(getSessionPatch()),
-		};
-	} catch (error) {
-		if (error instanceof PendingFieldError && requestedField) {
-			const resumeToken = await ctx.state.seal(
-				{
-					credentials,
-					resolvedFields,
-					requestedField,
-				} satisfies PendingAuthState,
-				{ ttl: "15m" },
-			);
-
-			const sessionPatch = toStringSessionPatch(getSessionPatch());
-			return {
-				type: "pending_field",
-				field: requestedField,
-				fieldLabel: getFieldLabel(provider, requestedField),
-				resumeToken,
-				...(Object.keys(sessionPatch).length > 0 ? { sessionPatch } : {}),
-			};
-		}
-
-		throw error;
-	} finally {
-		await close();
-	}
-}
-
-async function parseJsonBody<T>(request: Request): Promise<T> {
-	try {
-		return (await request.json()) as T;
-	} catch (error) {
-		throw new ProviderError("Invalid JSON body", {
-			code: "INVALID_JSON",
-			cause: error instanceof Error ? error : undefined,
-		});
-	}
-}
-
-export function createProviderServer(
-	provider: ProviderDefinition,
-	options: {
-		port?: number;
-		baseUrl?: string;
-		stateSecret?: string;
-		sessionDbPath?: string;
-	} = {},
-): { app: Hono; start: () => void } {
-	const startedAt = Date.now();
-	const app = new Hono();
-
-	app.post("/execute/:operationId", async (c) => {
-		try {
-			const operationId = c.req.param("operationId");
-			const body = await parseJsonBody<ExecuteRequest>(c.req.raw);
-			const { ctx, getSessionPatch, trace, close } = createContainerContext(
-				provider,
-				toSessionSnapshot(body.session),
-				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
-			);
-
-			try {
-				const data = await executeOperation(
-					provider,
-					operationId,
-					ctx,
-					body.input,
-				);
-				const response: ExecuteResponse = {
-					data,
-					sessionPatch: getSessionPatch(),
-					...(getTracePayload(trace) ? { trace: getTracePayload(trace) } : {}),
-				};
-
-				return c.json(response);
-			} finally {
-				await close();
-			}
-		} catch (error) {
-			return c.json(toErrorEnvelope(error), getStatusCode(error));
-		}
-	});
-
-	app.post("/connect", async (c) => {
-		try {
-			const body = await parseJsonBody<ConnectRequest>(c.req.raw);
-			const result = await runAuthExchange(
-				provider,
-				toStringRecord(body.credentials),
-				toSessionSnapshot(body.session),
-				{},
-				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
-			);
-
-			const response: ConnectResponse =
-				result.type === "success"
-					? {
-							status: "success",
-							sessionPatch: result.sessionPatch,
-						}
-					: {
-							status: "pending_field",
-							field: result.field,
-							resumeToken: result.resumeToken,
-							...(result.fieldLabel ? { fieldLabel: result.fieldLabel } : {}),
-							...(result.sessionPatch
-								? { sessionPatch: result.sessionPatch }
-								: {}),
-						};
-
-			return c.json(response);
-		} catch (error) {
-			return c.json(toConnectFailedResponse(error));
-		}
-	});
-
-	app.post("/connect/resume", async (c) => {
-		try {
-			const body = await parseJsonBody<ResumeRequest>(c.req.raw);
-			const state = createStateContext(options.stateSecret);
-			const pendingState = await state.unseal<PendingAuthState>(
-				body.resumeToken,
-			);
-
-			if (!pendingState) {
-				const response: ResumeResponse = {
-					status: "failed",
-					error: "INVALID_RESUME_TOKEN",
-					message: "Resume token is invalid or expired",
-				};
-				return c.json(response);
-			}
-
-			const result = await runAuthExchange(
-				provider,
-				pendingState.credentials,
-				toSessionSnapshot(body.session),
-				{
-					...pendingState.resolvedFields,
-					[pendingState.requestedField]: body.fieldValue,
-				},
-				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
-			);
-
-			const response: ResumeResponse =
-				result.type === "success"
-					? {
-							status: "success",
-							sessionPatch: result.sessionPatch,
-						}
-					: {
-							status: "pending_field",
-							field: result.field,
-							resumeToken: result.resumeToken,
-							...(result.fieldLabel ? { fieldLabel: result.fieldLabel } : {}),
-							...(result.sessionPatch
-								? { sessionPatch: result.sessionPatch }
-								: {}),
-						};
-
-			return c.json(response);
-		} catch (error) {
-			return c.json(toConnectFailedResponse(error));
-		}
-	});
-
-	app.post("/refresh", async (c) => {
-		try {
-			if (!provider.auth?.refresh) {
-				throw new ProviderError("Auth refresh is not configured", {
-					code: "AUTH_REFRESH_NOT_CONFIGURED",
-				});
-			}
-
-			const body = await parseJsonBody<RefreshRequest>(c.req.raw);
-			const { ctx, getSessionPatch, close } = createContainerContext(
-				provider,
-				body.session,
-				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
-			);
-
-			try {
-				await provider.auth.refresh(ctx);
-				await ctx.session.set(
-					AUTH_SESSION_KEY,
-					createAuthSessionMarker({
-						authenticated: true,
-						refreshed: true,
-						timestamp: Date.now(),
-					}),
-				);
-				const response: RefreshResponse = {
-					status: "success",
-					sessionPatch: toStringSessionPatch(getSessionPatch()),
-				};
-
-				return c.json(response);
-			} finally {
-				await close();
-			}
-		} catch (error) {
-			return c.json(toRefreshFailedResponse(error));
-		}
-	});
-
-	app.post("/disconnect", async (c) => {
-		try {
-			const body = await parseJsonBody<DisconnectRequest>(c.req.raw);
-			const { ctx, close } = createContainerContext(provider, body.session, {
-				baseUrl: options.baseUrl,
-				stateSecret: options.stateSecret,
-			});
-
-			try {
-				if (provider.auth?.disconnect) {
-					await provider.auth.disconnect(ctx);
-				}
-
-				await ctx.session.delete(AUTH_SESSION_KEY);
-				const response: DisconnectResponse = { status: "success" };
-				return c.json(response);
-			} finally {
-				await close();
-			}
-		} catch (error) {
-			return c.json(toDisconnectFailedResponse(error));
-		}
-	});
-
-	app.get("/health", (c) => {
-		const response: HealthResponse = {
-			status: "ok",
-			provider: provider.id,
-			version: provider.version,
-			uptime: Date.now() - startedAt,
-		};
-
-		return c.json(response);
-	});
-
-	app.get("/schema/:operationId", (c) => {
-		try {
-			const operationId = c.req.param("operationId");
-			const operation = provider.operations[operationId];
-
-			if (!operation) {
-				throw new ProviderError(
-					`Unknown operation: ${provider.id}/${operationId}`,
-					{
-						code: "NOT_FOUND",
-						fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
-					},
-				);
-			}
-
-			const response: SchemaResponse = {
-				operationId,
-				...(operation.description
-					? { description: operation.description }
-					: {}),
-				input: toSchema(operation.input),
-				output: toSchema(operation.output),
-				...(operation.hints ? { hints: operation.hints } : {}),
-			};
-
-			return c.json(response);
-		} catch (error) {
-			return c.json(toErrorEnvelope(error), getStatusCode(error));
-		}
-	});
-
-	return {
-		app,
-		start() {
-			if (typeof Bun === "undefined") {
-				throw new ProviderError("Bun runtime is required to start the server", {
-					code: "RUNTIME_UNSUPPORTED",
-				});
-			}
-
-			Bun.serve({
-				port: options.port ?? DEFAULT_PORT,
-				fetch: app.fetch,
-			});
-		},
-	};
-}
+export { createServerApp, type ServeOptions, serve } from "./server/serve";

package/src/server/index.ts

@@ -0,0 +1,22 @@
+export { createServerApp, type ServeOptions, serve } from "./serve";
+export type {
+	AuthFlowRequest,
+	AuthFlowResponse,
+	AuthFlowSuccessResponse,
+	ConnectionMode,
+	OperationConnection,
+	OperationErrorResponse,
+	OperationRequest,
+	OperationResponse,
+	OperationSuccessResponse,
+} from "./types";
+export {
+	AuthFlowRequestSchema,
+	AuthFlowSuccessResponseSchema,
+	ConnectionModeSchema,
+	ErrorEnvelopeSchema,
+	OperationConnectionSchema,
+	OperationErrorResponseSchema,
+	OperationRequestSchema,
+	OperationSuccessResponseSchema,
+} from "./types";