@apifuse/connector-sdk 2.0.0-beta.1

package/src/runtime/connector.ts

@@ -0,0 +1,20 @@
+import type { ConnectorDefinition } from "../types";
+
+export function getConnectorBaseUrl(
+	connector: ConnectorDefinition,
+): string | undefined {
+	const operations = Object.values(
+		connector.operations as Record<string, unknown>,
+	);
+
+	for (const operation of operations) {
+		const baseUrl = (operation as { upstream?: { baseUrl?: unknown } }).upstream
+			?.baseUrl;
+
+		if (typeof baseUrl === "string" && baseUrl.length > 0) {
+			return baseUrl;
+		}
+	}
+
+	return undefined;
+}

package/src/runtime/executor.ts

@@ -0,0 +1,51 @@
+import { ConnectorError } from "../errors";
+import type { ConnectorContext, ConnectorDefinition } from "../types";
+
+import { createAuthManager } from "./auth";
+
+/**
+ * Execute a connector operation by calling its handler.
+ *
+ * SDK auto-wraps every handler call with:
+ * 1. Input Zod validation
+ * 2. Auth auto-refresh (if auth configured)
+ * 3. Trace span
+ * 4. Output Zod validation
+ *
+ * @see openspec/connector-sdk/03-sdk-core.md §3.6
+ */
+export async function executeOperation(
+	connector: ConnectorDefinition,
+	operationId: string,
+	ctx: ConnectorContext,
+	input: unknown,
+): Promise<unknown> {
+	const operation = connector.operations[operationId];
+
+	if (!operation) {
+		throw new ConnectorError(
+			`Unknown operation: ${connector.id}/${operationId}`,
+			{
+				code: "NOT_FOUND",
+				fix: `Valid operations: ${Object.keys(connector.operations).join(", ")}`,
+			},
+		);
+	}
+
+	const validatedInput = operation.input.parse(input);
+
+	const execute = () =>
+		ctx.trace.span(`handler:${operationId}`, () =>
+			operation.handler(ctx, validatedInput),
+		);
+
+	const result =
+		connector.auth && connector.auth.mode !== "none"
+			? await createAuthManager(
+					connector.auth,
+					ctx.session,
+				).wrapWithAutoRefresh(ctx, execute)
+			: await execute();
+
+	return operation.output.parse(result);
+}

package/src/runtime/http.ts

@@ -0,0 +1,248 @@
+import { createRequire } from "node:module";
+
+import type { ProxyResolutionOptions } from "../config/loader";
+import { resolveProxyConfig } from "../config/loader";
+import { TransportError } from "../errors";
+import { generateLayer2Headers } from "../stealth/profiles";
+import type {
+	HttpClient,
+	HttpResponse,
+	RequestOptions,
+	RequestWithMethodOptions,
+	StealthProfile,
+} from "../types";
+
+const require = createRequire(import.meta.url);
+
+const MISSING_PROXY_WARNING =
+	"[connector-sdk] Connector requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
+
+type FetchProxyInit = RequestInit & {
+	dispatcher?: unknown;
+	proxy?: string;
+};
+
+type UndiciModule = {
+	ProxyAgent?: new (proxyUrl: string) => unknown;
+};
+
+export type HttpClientOptions = ProxyResolutionOptions & {
+	warn?: (message: string) => void;
+	stealthProfile?: StealthProfile;
+	userAgent?: string;
+};
+
+function buildUrl(url: string, params?: Record<string, string>): string {
+	if (!params || Object.keys(params).length === 0) {
+		return url;
+	}
+
+	const searchParams = new URLSearchParams(params);
+	return `${url}?${searchParams.toString()}`;
+}
+
+function resolveUrl(baseUrl: string | undefined, url: string): string {
+	if (!baseUrl) {
+		return url;
+	}
+
+	return new URL(url, baseUrl).toString();
+}
+
+async function doRequest(
+	baseUrl: string | undefined,
+	url: string,
+	method: string,
+	proxy: string | undefined,
+	options: RequestOptions & { body?: unknown } = {},
+): Promise<HttpResponse> {
+	const { headers, params, timeout, body } = options;
+
+	const controller = new AbortController();
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+	if (timeout) {
+		timeoutId = setTimeout(() => controller.abort(), timeout);
+	}
+
+	try {
+		const requestUrl = buildUrl(resolveUrl(baseUrl, url), params);
+		const proxyInit = createProxyInit(proxy);
+		const response = await fetch(requestUrl, {
+			...proxyInit,
+			method,
+			headers: {
+				"Content-Type": "application/json",
+				...headers,
+			},
+			body: body !== undefined ? JSON.stringify(body) : undefined,
+			signal: controller.signal,
+		});
+
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			throw new TransportError(
+				`HTTP ${response.status} ${response.statusText}: ${requestUrl}`,
+				{
+					status: response.status,
+					fix: `Check the endpoint URL and request parameters. Response: ${text.slice(0, 200)}`,
+				},
+			);
+		}
+
+		const contentType = response.headers.get("content-type") ?? "";
+		const rawText = await response.text();
+		let data: unknown;
+
+		if (contentType.includes("application/json")) {
+			data = rawText ? (JSON.parse(rawText) as unknown) : null;
+		} else {
+			data = rawText;
+		}
+
+		return {
+			data,
+			headers: Object.fromEntries(response.headers.entries()),
+			json: async <T = unknown>() =>
+				contentType.includes("application/json")
+					? (data as T)
+					: (JSON.parse(rawText) as T),
+			ok: response.ok,
+			status: response.status,
+			text: async () => rawText,
+		};
+	} catch (error) {
+		if (error instanceof TransportError) {
+			throw error;
+		}
+
+		if (error instanceof Error && error.name === "AbortError") {
+			throw new TransportError(
+				`Request timed out: ${resolveUrl(baseUrl, url)}`,
+				{
+					fix: `Increase timeout option (current: ${timeout}ms)`,
+				},
+			);
+		}
+
+		throw new TransportError(`Network error: ${String(error)}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	} finally {
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+		}
+	}
+}
+
+function createProxyInit(
+	proxy?: string,
+): Pick<FetchProxyInit, "dispatcher" | "proxy"> {
+	if (!proxy) {
+		return {};
+	}
+
+	if (typeof Bun !== "undefined") {
+		return { proxy };
+	}
+
+	try {
+		const undici = require("undici") as UndiciModule;
+		if (typeof undici.ProxyAgent === "function") {
+			return {
+				dispatcher: new undici.ProxyAgent(
+					proxy,
+				) as FetchProxyInit["dispatcher"],
+			};
+		}
+	} catch {
+		// Fall through to a generic fetch init extension when undici is unavailable.
+	}
+
+	return { proxy };
+}
+
+export function createHttpClient(
+	baseUrl?: string,
+	clientOptions: HttpClientOptions = {},
+): HttpClient {
+	let hasWarnedMissingProxy = false;
+	const warn = clientOptions.warn ?? console.warn;
+	const stealthProfile = clientOptions.stealthProfile;
+	const userAgent = clientOptions.userAgent ?? stealthProfile?.userAgent;
+
+	function withClientHeaders(
+		options?: RequestOptions,
+	): RequestOptions | undefined {
+		const layer2Headers = stealthProfile
+			? generateLayer2Headers(stealthProfile)
+			: undefined;
+
+		if (!userAgent && !layer2Headers) {
+			return options;
+		}
+
+		return {
+			...options,
+			headers: {
+				...(userAgent ? { "User-Agent": userAgent } : {}),
+				...layer2Headers,
+				...options?.headers,
+			},
+		};
+	}
+
+	function resolveRequestProxy(
+		requestOptions?: RequestOptions,
+	): string | undefined {
+		const resolvedProxy = resolveProxyConfig({
+			proxy: requestOptions?.proxy ?? clientOptions.proxy,
+			upstream: clientOptions.upstream,
+			apifuseConfig: clientOptions.apifuseConfig,
+		});
+
+		if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
+			hasWarnedMissingProxy = true;
+			warn(MISSING_PROXY_WARNING);
+		}
+
+		return resolvedProxy.url;
+	}
+
+	return {
+		request: (url, options: RequestWithMethodOptions = {}) =>
+			doRequest(
+				baseUrl,
+				url,
+				options.method ?? "GET",
+				resolveRequestProxy(options),
+				withClientHeaders(options),
+			),
+		get: (url, options) =>
+			doRequest(
+				baseUrl,
+				url,
+				"GET",
+				resolveRequestProxy(options),
+				withClientHeaders(options),
+			),
+		post: (url, body, options) =>
+			doRequest(baseUrl, url, "POST", resolveRequestProxy(options), {
+				...withClientHeaders(options),
+				body,
+			}),
+		put: (url, body, options) =>
+			doRequest(baseUrl, url, "PUT", resolveRequestProxy(options), {
+				...withClientHeaders(options),
+				body,
+			}),
+		delete: (url, options) =>
+			doRequest(
+				baseUrl,
+				url,
+				"DELETE",
+				resolveRequestProxy(options),
+				withClientHeaders(options),
+			),
+	};
+}