@apifuse/connector-sdk 2.0.0-beta.1

package/src/types.ts

@@ -0,0 +1,243 @@
+import type { infer as ZodInfer, ZodType } from "zod";
+
+export type StealthPlatform = "macos" | "windows" | "linux" | "android" | "ios";
+
+export type BrowserEngine = "playwright-stealth" | "nodriver" | "selenium-uc";
+
+export interface BrowserOptions {
+	headless?: boolean;
+	stealth?: boolean;
+	proxy?: string;
+	engine?: BrowserEngine;
+}
+
+export interface StealthProfile {
+	name: string;
+	platform: StealthPlatform;
+	version: string;
+	userAgent: string;
+	tlsClientIdentifier?: string;
+	ja3?: string;
+	ja4?: string;
+	h2Settings?: Record<string, unknown>;
+	headerOrder?: string[];
+}
+
+export type AuthMode = "none" | "credentials" | "oauth2" | "api-key";
+
+export interface AuthField {
+	name: string;
+	label: string;
+	type: "text" | "password" | "otp";
+	required?: boolean;
+	deferred?: boolean;
+}
+
+export interface ConnectorMeta {
+	displayName: string;
+	description?: string;
+	category: string;
+	tags?: string[];
+	icon?: string;
+}
+
+export interface RequestOptions {
+	headers?: Record<string, string>;
+	params?: Record<string, string>;
+	proxy?: string;
+	timeout?: number;
+}
+
+export interface TlsFetchOptions extends RequestOptions {
+	method?: string;
+	body?: string | Buffer;
+	profile?: string;
+	tls?: {
+		ja3?: string;
+		h2?: Record<string, unknown>;
+	};
+	headerOrder?: string[];
+}
+
+export interface CookieJar {
+	get(name: string): string | undefined;
+	getAll(): Record<string, string>;
+	toString(): string;
+	find?(predicate: (cookie: string) => boolean): string | undefined;
+}
+
+export interface DeclarativeTlsResponse {
+	status: number;
+	ok: boolean;
+	headers: Record<string, string>;
+	rawHeaders: [string, string][];
+	body: string;
+	httpVersion?: string;
+	tlsInfo?: { protocol?: string; cipher?: string; [key: string]: unknown };
+	cookies: CookieJar;
+	json<T>(): Promise<T>;
+}
+
+export type TlsResponse = DeclarativeTlsResponse;
+
+export type RequestWithMethodOptions = RequestOptions & {
+	method?: string;
+};
+
+export interface TlsSession {
+	fetch(url: string, options?: TlsFetchOptions): Promise<TlsResponse>;
+	close(): void;
+}
+
+export interface ApiFuseResponse<T> {
+	data: T;
+	meta: {
+		requestId: string;
+		duration: number;
+		cached?: boolean;
+	};
+}
+
+export interface HttpResponse<T = unknown> {
+	status: number;
+	ok: boolean;
+	headers: Record<string, string>;
+	data: T;
+	json<U = T>(): Promise<U>;
+	text(): Promise<string>;
+}
+
+export interface HttpClient {
+	request(url: string, opts?: RequestWithMethodOptions): Promise<HttpResponse>;
+	get(url: string, options?: RequestOptions): Promise<HttpResponse>;
+	post(
+		url: string,
+		body: unknown,
+		options?: RequestOptions,
+	): Promise<HttpResponse>;
+	put(
+		url: string,
+		body: unknown,
+		options?: RequestOptions,
+	): Promise<HttpResponse>;
+	delete(url: string, options?: RequestOptions): Promise<HttpResponse>;
+}
+
+export interface TlsClient {
+	fetch(url: string, options?: TlsFetchOptions): Promise<TlsResponse>;
+	createSession(opts?: { profile?: string }): TlsSession;
+}
+
+export interface BrowserClient {
+	readonly engine: BrowserEngine;
+	newPage(): Promise<unknown>;
+}
+
+export interface SessionStore {
+	get(key: string): Promise<string | null>;
+	set(key: string, value: string, ttl?: string): Promise<void>;
+	delete(key: string): Promise<void>;
+}
+
+export interface StateContext {
+	seal(data: unknown, options?: { ttl?: string }): Promise<string>;
+	unseal<T = unknown>(token: string): Promise<T | null>;
+}
+
+export type TraceAttributeValue = string | number | boolean;
+
+export interface TraceSpan {
+	id: string;
+	name: string;
+	startedAt: number;
+	endedAt: number;
+	duration_ms: number;
+	status: "ok" | "error";
+	error?: string;
+	attributes: Record<string, TraceAttributeValue>;
+	parentId?: string;
+}
+
+export interface TraceConfig {
+	enabled?: boolean;
+	maxSpans?: number;
+	onSpan?: (span: TraceSpan) => void;
+	exporter?: "console" | "json" | "otlp" | "none";
+	endpoint?: string;
+	otlp?: {
+		endpoint: string;
+		headers?: Record<string, string>;
+		timeout?: number;
+	};
+}
+
+export interface TraceContext {
+	span<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+
+export interface AuthContext {
+	requestField(
+		name: string,
+		options?: { type?: "otp" | "text" },
+	): Promise<string>;
+}
+
+export interface ConnectorContext {
+	http: HttpClient;
+	tls: TlsClient;
+	browser: BrowserClient;
+	session: SessionStore;
+	state: StateContext;
+	trace: TraceContext;
+	auth: AuthContext;
+}
+
+export interface AuthConfig {
+	mode: AuthMode;
+	fields?: AuthField[];
+	exchange?: (
+		ctx: ConnectorContext,
+		credentials: Record<string, string>,
+	) => Promise<void>;
+	refresh?: (ctx: ConnectorContext) => Promise<void>;
+	refreshPolicy?: {
+		strategy: "reactive" | "proactive" | "both";
+		interval?: string;
+	};
+	disconnect?: (ctx: ConnectorContext) => Promise<void>;
+}
+
+export interface OperationDefinition<
+	TInput extends ZodType = ZodType,
+	TOutput extends ZodType = ZodType,
+> {
+	description?: string;
+	input: TInput;
+	output: TOutput;
+	handler: (
+		ctx: ConnectorContext,
+		input: ZodInfer<TInput>,
+	) => Promise<ZodInfer<TOutput>>;
+	fixtures?: {
+		request: ZodInfer<TInput>;
+		response: ZodInfer<TOutput>;
+	};
+	hints?: Record<string, string>;
+}
+
+export interface ConnectorDefinition {
+	id: string;
+	version: string;
+	runtime: "standard" | "browser";
+	stealth?: {
+		profile: string;
+		platform: StealthPlatform;
+	};
+	proxy?: boolean;
+	browser?: {
+		engine: BrowserEngine;
+	};
+	auth?: AuthConfig;
+	meta: ConnectorMeta;
+	operations: Record<string, OperationDefinition<ZodType, ZodType>>;
+}

package/src/utils/date.ts

@@ -0,0 +1,163 @@
+function getDateParts(date: Date, timezone: string) {
+	const formatter = new Intl.DateTimeFormat("en-CA", {
+		timeZone: timezone,
+		hour12: false,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+	});
+
+	const parts = Object.fromEntries(
+		formatter.formatToParts(date).map((part) => [part.type, part.value]),
+	) as Record<string, string>;
+
+	return {
+		year: parts.year,
+		month: parts.month,
+		day: parts.day,
+		hour: parts.hour,
+		minute: parts.minute,
+		second: parts.second,
+	};
+}
+
+function getTimezoneOffsetMinutes(date: Date, timezone: string): number {
+	const parts = getDateParts(date, timezone);
+	const asUTC = Date.UTC(
+		Number(parts.year),
+		Number(parts.month) - 1,
+		Number(parts.day),
+		Number(parts.hour),
+		Number(parts.minute),
+		Number(parts.second),
+	);
+
+	return (asUTC - date.getTime()) / 60000;
+}
+
+function buildUtcInstantFromLocalParts(
+	year: number,
+	month: number,
+	day: number,
+	hour: number,
+	minute: number,
+	second: number,
+	timezone: string,
+): Date {
+	const guess = Date.UTC(year, month - 1, day, hour, minute, second);
+	let utc = guess;
+
+	for (let i = 0; i < 2; i += 1) {
+		const offset = getTimezoneOffsetMinutes(new Date(utc), timezone);
+		const nextUtc = guess - offset * 60_000;
+		if (nextUtc === utc) {
+			break;
+		}
+		utc = nextUtc;
+	}
+
+	return new Date(utc);
+}
+
+function formatOffset(offsetMinutes: number): string {
+	const sign = offsetMinutes >= 0 ? "+" : "-";
+	const abs = Math.abs(offsetMinutes);
+	const hours = String(Math.floor(abs / 60)).padStart(2, "0");
+	const minutes = String(abs % 60).padStart(2, "0");
+	return `${sign}${hours}:${minutes}`;
+}
+
+function formatIso(date: Date, timezone: string): string {
+	const parts = getDateParts(date, timezone);
+	const offset = getTimezoneOffsetMinutes(date, timezone);
+	return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}:${parts.second}${formatOffset(offset)}`;
+}
+
+function parseDateValue(v: unknown, timezone: string): Date | null {
+	if (v instanceof Date) {
+		return Number.isNaN(v.getTime()) ? null : v;
+	}
+
+	if (typeof v === "number") {
+		const date = new Date(v);
+		return Number.isNaN(date.getTime()) ? null : date;
+	}
+
+	if (typeof v !== "string") {
+		return null;
+	}
+
+	const value = v.trim();
+	if (value === "") {
+		return null;
+	}
+
+	const compactDate = /^(\d{4})(\d{2})(\d{2})$/;
+	const compactDateTime = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})?$/;
+	const dashedDate = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+	let match = value.match(compactDateTime);
+	if (match) {
+		const [, year, month, day, hour, minute, second = "00"] = match;
+		return buildUtcInstantFromLocalParts(
+			Number(year),
+			Number(month),
+			Number(day),
+			Number(hour),
+			Number(minute),
+			Number(second),
+			timezone,
+		);
+	}
+
+	match = value.match(compactDate);
+	if (match) {
+		const [, year, month, day] = match;
+		return buildUtcInstantFromLocalParts(
+			Number(year),
+			Number(month),
+			Number(day),
+			0,
+			0,
+			0,
+			timezone,
+		);
+	}
+
+	match = value.match(dashedDate);
+	if (match) {
+		const [, year, month, day] = match;
+		return buildUtcInstantFromLocalParts(
+			Number(year),
+			Number(month),
+			Number(day),
+			0,
+			0,
+			0,
+			timezone,
+		);
+	}
+
+	const parsed = new Date(value);
+	return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+/** Convert various date formats to ISO 8601 string */
+export function toISODate(v: unknown, timezone: string): string {
+	const date = parseDateValue(v, timezone);
+	return date ? formatIso(date, timezone) : "";
+}
+
+/** Get today's date as ISO 8601 string in given timezone */
+export function today(timezone: string): string {
+	const parts = getDateParts(new Date(), timezone);
+	return `${parts.year}-${parts.month}-${parts.day}`;
+}
+
+/** Get current hour as string in given timezone */
+export function currentHour(timezone: string): string {
+	return getDateParts(new Date(), timezone).hour;
+}

package/src/utils/parse.ts

@@ -0,0 +1,66 @@
+/**
+ * Unwrap nested envelope by dot-path
+ * e.g., unwrapEnvelope({response: {body: {items: [...]}}}, 'response.body.items')
+ */
+export function unwrapEnvelope(data: unknown, path?: string): unknown {
+	if (!path || path.trim() === "") {
+		return data;
+	}
+
+	const segments = path.split(".").filter(Boolean);
+	let current: unknown = data;
+
+	for (const segment of segments) {
+		if (!current || typeof current !== "object") {
+			return undefined;
+		}
+
+		current = (current as Record<string, unknown>)[segment];
+	}
+
+	return current;
+}
+
+/**
+ * Pivot array by field — generalized version of pivotByCategory
+ * e.g., pivotByField([{type:'A', val:1},{type:'B', val:2}], 'type', 'val')
+ * → { A: 1, B: 2 }
+ */
+export function pivotByField(
+	items: unknown[],
+	keyField: string,
+	valueField: string,
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+
+	for (const item of items) {
+		if (!item || typeof item !== "object") {
+			continue;
+		}
+
+		const record = item as Record<string, unknown>;
+		const key = record[keyField];
+		const value = record[valueField];
+
+		if (key === undefined || key === null || value === undefined) {
+			continue;
+		}
+
+		result[String(key)] = value;
+	}
+
+	return result;
+}
+
+/**
+ * Parse XML items from string — returns array
+ * Uses simple regex (no DOM), suitable for structured XML
+ */
+export function parseXmlItems(xml: string, tag: string): string[] {
+	const matches = [
+		...xml.matchAll(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, "gi")),
+	];
+	return matches
+		.map((match) => match[1].replace(/<[^>]+>/g, "").trim())
+		.filter((item) => item.length > 0);
+}

package/src/utils/text.ts

@@ -0,0 +1,20 @@
+/** Remove HTML tags from string */
+export function stripHtml(html: string): string {
+	return html
+		.replace(/<[^>]*>/g, "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/** Truncate string to maxLength with optional suffix */
+export function truncate(
+	str: string,
+	maxLength: number,
+	suffix = "...",
+): string {
+	if (str.length <= maxLength) {
+		return str;
+	}
+
+	return `${str.slice(0, maxLength)}${suffix}`;
+}

package/src/utils/transform.ts

@@ -0,0 +1,62 @@
+/** Parse any value to number (returns 0 if not parseable) */
+export function toNumber(v: unknown): number {
+	if (typeof v === "number") {
+		return Number.isFinite(v) ? v : 0;
+	}
+
+	if (typeof v === "boolean") {
+		return v ? 1 : 0;
+	}
+
+	if (typeof v === "string") {
+		const cleaned = v.replaceAll(",", "").trim();
+
+		if (cleaned === "") {
+			return 0;
+		}
+
+		const parsed = Number(cleaned);
+		return Number.isFinite(parsed) ? parsed : 0;
+	}
+
+	return 0;
+}
+
+/** Parse any value to float */
+export function toFloat(v: unknown, decimals?: number): number {
+	const parsed = toNumber(v);
+
+	if (!Number.isFinite(parsed)) {
+		return 0;
+	}
+
+	if (decimals === undefined) {
+		return parsed;
+	}
+
+	const factor = 10 ** decimals;
+	return Math.round(parsed * factor) / factor;
+}
+
+/** Parse any value to integer */
+export function toInt(v: unknown): number {
+	return Math.round(toNumber(v));
+}
+
+/** Parse any value to boolean (handles "true", "1", "yes", true, 1) */
+export function toBoolean(v: unknown): boolean {
+	if (typeof v === "boolean") {
+		return v;
+	}
+
+	if (typeof v === "number") {
+		return v === 1;
+	}
+
+	if (typeof v === "string") {
+		const normalized = v.trim().toLowerCase();
+		return ["true", "1", "yes", "y"].includes(normalized);
+	}
+
+	return false;
+}