@apifuse/provider-sdk 2.0.0-beta.1

package/src/protocol.ts

@@ -0,0 +1,183 @@
+/**
+ * Container Protocol — Communication contract between Route Server and Provider Containers.
+ *
+ * All provider containers expose HTTP endpoints. Route Server sends requests
+ * and receives responses in these formats.
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// Execute Operation
+// POST /execute/:operationId
+// ═══════════════════════════════════════════════════════════════
+
+export interface ExecuteRequest {
+	/** Validated input (already passed Zod validation by Route Server) */
+	input: unknown;
+	/** Decrypted session key-value pairs (loaded by Route Server from DB) */
+	session?: Record<string, string>;
+	/** Trace context for distributed tracing */
+	trace?: { traceId: string; spanId: string };
+}
+
+export interface ExecuteResponse {
+	/** Operation result (will be Zod-validated by Route Server) */
+	data: unknown;
+	/** Session mutations to persist back to DB (key→value for set, key→null for delete) */
+	sessionPatch?: Record<string, string | null>;
+	/** Trace spans collected during execution */
+	trace?: { spans: unknown[] };
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Connect (Auth Exchange)
+// POST /connect
+// ═══════════════════════════════════════════════════════════════
+
+export interface ConnectRequest {
+	/** User-provided credentials */
+	credentials: Record<string, string>;
+	/** Existing session (for re-auth scenarios) */
+	session?: Record<string, string>;
+}
+
+/** Successful connection */
+export interface ConnectSuccessResponse {
+	status: "success";
+	/** Display name for the connected upstream account */
+	accountRef?: string;
+	/** Session data to persist (full session state after exchange) */
+	sessionPatch: Record<string, string>;
+}
+
+/** Connection requires additional field (e.g., OTP) */
+export interface ConnectPendingFieldResponse {
+	status: "pending_field";
+	/** Name of the field to request from user */
+	field: string;
+	/** Label to display to user */
+	fieldLabel?: string;
+	/** Opaque token to resume the connection flow */
+	resumeToken: string;
+	/** Partial session state to persist (intermediate state) */
+	sessionPatch?: Record<string, string>;
+}
+
+/** Connection failed */
+export interface ConnectFailedResponse {
+	status: "failed";
+	/** Error code for programmatic handling */
+	error: string;
+	/** Human-readable error message */
+	message?: string;
+}
+
+export type ConnectResponse =
+	| ConnectSuccessResponse
+	| ConnectPendingFieldResponse
+	| ConnectFailedResponse;
+
+// ═══════════════════════════════════════════════════════════════
+// Resume (Continue deferred auth)
+// POST /connect/resume
+// ═══════════════════════════════════════════════════════════════
+
+export interface ResumeRequest {
+	/** Resume token from ConnectPendingFieldResponse */
+	resumeToken: string;
+	/** User-provided value for the requested field */
+	fieldValue: string;
+	/** Current session state */
+	session?: Record<string, string>;
+}
+
+export type ResumeResponse = ConnectResponse; // same as ConnectResponse
+
+// ═══════════════════════════════════════════════════════════════
+// Refresh (Auth token refresh)
+// POST /refresh
+// ═══════════════════════════════════════════════════════════════
+
+export interface RefreshRequest {
+	/** Current session to refresh */
+	session: Record<string, string>;
+}
+
+export interface RefreshSuccessResponse {
+	status: "success";
+	/** Updated session data */
+	sessionPatch: Record<string, string>;
+}
+
+export interface RefreshFailedResponse {
+	status: "failed";
+	error: string;
+	message?: string;
+}
+
+export type RefreshResponse = RefreshSuccessResponse | RefreshFailedResponse;
+
+// ═══════════════════════════════════════════════════════════════
+// Disconnect
+// POST /disconnect
+// ═══════════════════════════════════════════════════════════════
+
+export interface DisconnectRequest {
+	/** Session to clean up */
+	session: Record<string, string>;
+}
+
+export interface DisconnectResponse {
+	status: "success" | "failed";
+	error?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Health
+// GET /health
+// ═══════════════════════════════════════════════════════════════
+
+export interface HealthResponse {
+	status: "ok" | "degraded" | "error";
+	provider: string;
+	version: string;
+	uptime?: number;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Schema
+// GET /schema/:operationId
+// ═══════════════════════════════════════════════════════════════
+
+export interface SchemaResponse {
+	operationId: string;
+	description?: string;
+	input: Record<string, unknown>; // JSON Schema
+	output: Record<string, unknown>; // JSON Schema
+	hints?: Record<string, string>;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Error envelope (used for any error response)
+// ═══════════════════════════════════════════════════════════════
+
+export interface ContainerErrorResponse {
+	error: {
+		code: string;
+		message: string;
+		details?: unknown;
+	};
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Standard endpoint paths
+// ═══════════════════════════════════════════════════════════════
+
+export const CONTAINER_ENDPOINTS = {
+	execute: "/execute/:operationId",
+	connect: "/connect",
+	resume: "/connect/resume",
+	refresh: "/refresh",
+	disconnect: "/disconnect",
+	health: "/health",
+	schema: "/schema/:operationId",
+} as const;

package/src/recipes/gov-api.ts

@@ -0,0 +1,97 @@
+import { unwrapEnvelope } from "../utils/parse";
+
+function getResultCode(raw: unknown): string | undefined {
+	if (!raw || typeof raw !== "object") {
+		return undefined;
+	}
+
+	const record = raw as Record<string, unknown>;
+
+	if (typeof record.resultCode === "string") {
+		return record.resultCode;
+	}
+
+	const response = record.response as Record<string, unknown> | undefined;
+	const header = response?.header as Record<string, unknown> | undefined;
+
+	return typeof header?.resultCode === "string" ? header.resultCode : undefined;
+}
+
+/**
+ * Check Korean government API result code
+ * Returns true if resultCode matches successCodes (default: ['00', '000', '0000'])
+ */
+export function checkResultCode(
+	raw: unknown,
+	successCodes: string[] = ["00", "000", "0000"],
+): boolean {
+	const code = getResultCode(raw);
+	return code ? successCodes.includes(code) : false;
+}
+
+/**
+ * Replace placeholder values with null
+ * e.g., nullIfPlaceholder('해당없음', ['해당없음', '-', '']) → null
+ */
+export function nullIfPlaceholder(
+	v: unknown,
+	patterns: string[],
+): unknown | null {
+	if (v === null || v === undefined) {
+		return null;
+	}
+
+	if (typeof v !== "string") {
+		return v;
+	}
+
+	const normalized = v.trim();
+	return patterns.some((pattern) => normalized === pattern.trim()) ? null : v;
+}
+
+/**
+ * Unwrap Korean government API envelope
+ * Handles: {response: {body: {items: {item: ...}}}} nested structure
+ */
+export function unwrapGovEnvelope(raw: unknown): unknown {
+	const item = unwrapEnvelope(raw, "response.body.items.item");
+
+	if (Array.isArray(item)) {
+		return item;
+	}
+
+	if (item !== undefined && item !== null) {
+		return [item];
+	}
+
+	const items = unwrapEnvelope(raw, "response.body.items");
+	if (Array.isArray(items)) {
+		return items;
+	}
+
+	if (items !== undefined && items !== null) {
+		return items;
+	}
+
+	return raw;
+}
+
+/**
+ * Check if Korean government API returned empty result
+ */
+export function isEmptyResult(raw: unknown): boolean {
+	if (getResultCode(raw) === "03") {
+		return true;
+	}
+
+	const items = unwrapGovEnvelope(raw);
+	if (Array.isArray(items)) {
+		return items.length === 0;
+	}
+
+	if (items && typeof items === "object") {
+		return Object.keys(items as Record<string, unknown>).length === 0;
+	}
+
+	return false;
+}

package/src/recipes/rest-api.ts

@@ -0,0 +1,152 @@
+export interface PaginationInfo {
+	page: number;
+	perPage: number;
+	total: number;
+	totalPages: number;
+	hasNext: boolean;
+	hasPrev: boolean;
+}
+
+function toPositiveInteger(value: unknown): number | null {
+	if (typeof value === "number" && Number.isFinite(value)) {
+		return Math.trunc(value);
+	}
+
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number.parseInt(value, 10);
+		return Number.isNaN(parsed) ? null : parsed;
+	}
+
+	return null;
+}
+
+function readPath(raw: unknown, path: string): unknown {
+	if (!raw || typeof raw !== "object") {
+		return undefined;
+	}
+
+	let current: unknown = raw;
+	for (const segment of path.split(".")) {
+		if (!current || typeof current !== "object") {
+			return undefined;
+		}
+
+		current = (current as Record<string, unknown>)[segment];
+	}
+
+	return current;
+}
+
+/**
+ * Extract pagination info from various REST API response shapes.
+ * Handles: {page, per_page, total}, {meta: {pagination: {...}}}, {currentPage, totalCount, pageSize}
+ */
+export function extractPagination(raw: unknown): PaginationInfo | null {
+	const candidates = [
+		{
+			page: readPath(raw, "page"),
+			perPage: readPath(raw, "per_page"),
+			total: readPath(raw, "total"),
+		},
+		{
+			page: readPath(raw, "meta.pagination.page"),
+			perPage: readPath(raw, "meta.pagination.per_page"),
+			total: readPath(raw, "meta.pagination.total"),
+		},
+		{
+			page: readPath(raw, "meta.pagination.currentPage"),
+			perPage: readPath(raw, "meta.pagination.pageSize"),
+			total: readPath(raw, "meta.pagination.totalCount"),
+		},
+		{
+			page: readPath(raw, "currentPage"),
+			perPage: readPath(raw, "pageSize"),
+			total: readPath(raw, "totalCount"),
+		},
+	];
+
+	for (const candidate of candidates) {
+		const page = toPositiveInteger(candidate.page);
+		const perPage = toPositiveInteger(candidate.perPage);
+		const total = toPositiveInteger(candidate.total);
+
+		if (page === null || perPage === null || total === null) {
+			continue;
+		}
+
+		const totalPages = perPage > 0 ? Math.ceil(total / perPage) : 0;
+
+		return {
+			page,
+			perPage,
+			total,
+			totalPages,
+			hasNext: page < totalPages,
+			hasPrev: page > 1,
+		};
+	}
+
+	return null;
+}
+
+function extractMessage(value: unknown): string | null {
+	if (typeof value === "string" && value.trim() !== "") {
+		return value;
+	}
+
+	if (!value || typeof value !== "object") {
+		return null;
+	}
+
+	const record = value as Record<string, unknown>;
+
+	if (typeof record.message === "string" && record.message.trim() !== "") {
+		return record.message;
+	}
+
+	if (typeof record.error === "string" && record.error.trim() !== "") {
+		return record.error;
+	}
+
+	return null;
+}
+
+/**
+ * Normalize error response to a standard format.
+ * Handles: {error: string}, {message: string}, {errors: []}, {error: {message: string}}
+ */
+export function normalizeErrorResponse(
+	raw: unknown,
+): { message: string; code?: string } | null {
+	if (!raw || typeof raw !== "object") {
+		return null;
+	}
+
+	const record = raw as Record<string, unknown>;
+
+	const directMessage =
+		extractMessage(record.error) ?? extractMessage(record.message);
+	if (directMessage) {
+		const code =
+			typeof record.code === "string" && record.code.trim() !== ""
+				? record.code
+				: undefined;
+		return code ? { message: directMessage, code } : { message: directMessage };
+	}
+
+	const errors = record.errors;
+	if (Array.isArray(errors) && errors.length > 0) {
+		for (const item of errors) {
+			const message = extractMessage(item);
+			if (message) {
+				const code =
+					typeof record.code === "string" && record.code.trim() !== ""
+						? record.code
+						: undefined;
+				return code ? { message, code } : { message };
+			}
+		}
+	}
+
+	return null;
+}

package/src/runtime/auth.ts

@@ -0,0 +1,245 @@
+import { AuthError, TransportError } from "../errors";
+import type {
+	AuthConfig,
+	AuthContext,
+	AuthField,
+	ProviderContext,
+	SessionStore,
+} from "../types";
+
+const AUTH_SESSION_KEY = "__auth__";
+const REQUEST_FIELD_TIMEOUT_MS = 60_000;
+
+function createAuthSessionMarker(
+	marker: Record<string, boolean | number>,
+): string {
+	return JSON.stringify(marker);
+}
+
+type PendingFieldRequest = {
+	promise: Promise<string>;
+	resolve: (value: string) => void;
+	reject: (error: AuthError) => void;
+	timeoutId: ReturnType<typeof setTimeout>;
+};
+
+export interface AuthManager {
+	exchange(
+		ctx: ProviderContext,
+		credentials: Record<string, string>,
+	): Promise<void>;
+	refresh(ctx: ProviderContext): Promise<void>;
+	disconnect(ctx: ProviderContext): Promise<void>;
+	wrapWithAutoRefresh<T>(
+		ctx: ProviderContext,
+		operation: () => Promise<T>,
+	): Promise<T>;
+	getFields(): AuthField[];
+	createAuthContext(): AuthContext;
+	resolveField(name: string, value: string): void;
+	getPendingFields(): string[];
+	isAuthNone(): boolean;
+}
+
+function toAuthError(error: unknown): AuthError {
+	if (error instanceof AuthError) {
+		return error;
+	}
+
+	if (error instanceof Error) {
+		return new AuthError(error.message, { cause: error });
+	}
+
+	return new AuthError("Auth exchange failed");
+}
+
+function is401or403(error: unknown): error is TransportError {
+	return (
+		error instanceof TransportError &&
+		(error.status === 401 || error.status === 403)
+	);
+}
+
+export function createAuthManager(
+	config: AuthConfig | undefined,
+	session: SessionStore,
+): AuthManager {
+	const pendingFieldRequests = new Map<string, PendingFieldRequest>();
+	const resolvedFieldValues = new Map<string, string>();
+	let refreshPromise: Promise<void> | null = null;
+
+	function createTimedFieldRequest(name: string): Promise<string> {
+		const existingRequest = pendingFieldRequests.get(name);
+		if (existingRequest) {
+			return existingRequest.promise;
+		}
+
+		const preResolvedValue = resolvedFieldValues.get(name);
+		if (preResolvedValue !== undefined) {
+			resolvedFieldValues.delete(name);
+			return Promise.resolve(preResolvedValue);
+		}
+
+		let resolvePromise!: (value: string) => void;
+		let rejectPromise!: (error: AuthError) => void;
+
+		const promise = new Promise<string>((resolve, reject) => {
+			resolvePromise = resolve;
+			rejectPromise = reject;
+		});
+
+		const timeoutId = setTimeout(() => {
+			pendingFieldRequests.delete(name);
+			rejectPromise(new AuthError(`Auth field request timed out: ${name}`));
+		}, REQUEST_FIELD_TIMEOUT_MS);
+
+		pendingFieldRequests.set(name, {
+			promise,
+			resolve: (value) => {
+				clearTimeout(timeoutId);
+				pendingFieldRequests.delete(name);
+				resolvePromise(value);
+			},
+			reject: (error) => {
+				clearTimeout(timeoutId);
+				pendingFieldRequests.delete(name);
+				rejectPromise(error);
+			},
+			timeoutId,
+		});
+
+		return promise;
+	}
+
+	const authContext: AuthContext = {
+		requestField(name) {
+			return createTimedFieldRequest(name);
+		},
+	};
+
+	const manager: AuthManager = {
+		async exchange(ctx, credentials) {
+			if (!config || config.mode === "none") {
+				throw new AuthError("No auth configured");
+			}
+
+			if (!config.exchange) {
+				throw new AuthError("Auth exchange is not configured");
+			}
+
+			ctx.auth = authContext;
+
+			await ctx.trace.span("auth.exchange", async () => {
+				try {
+					await config.exchange?.(ctx, credentials);
+				} catch (error) {
+					throw toAuthError(error);
+				}
+
+				await session.set(
+					AUTH_SESSION_KEY,
+					createAuthSessionMarker({
+						authenticated: true,
+						timestamp: Date.now(),
+					}),
+				);
+			});
+		},
+		async refresh(ctx) {
+			if (refreshPromise) {
+				return refreshPromise;
+			}
+
+			if (!config?.refresh) {
+				throw new AuthError("No refresh configured");
+			}
+
+			const doRefresh = async () => {
+				await ctx.trace.span("auth.refresh", async () => {
+					try {
+						await config.refresh?.(ctx);
+					} catch (error) {
+						throw toAuthError(error);
+					}
+
+					await session.set(
+						AUTH_SESSION_KEY,
+						createAuthSessionMarker({
+							authenticated: true,
+							refreshed: true,
+							timestamp: Date.now(),
+						}),
+					);
+				});
+			};
+
+			refreshPromise = doRefresh().finally(() => {
+				refreshPromise = null;
+			});
+
+			return refreshPromise;
+		},
+		async disconnect(ctx) {
+			await ctx.trace.span("auth.disconnect", async () => {
+				let disconnectError: AuthError | null = null;
+
+				try {
+					if (config?.disconnect) {
+						await config.disconnect(ctx);
+					}
+				} catch (error) {
+					disconnectError = toAuthError(error);
+				} finally {
+					await session.delete(AUTH_SESSION_KEY);
+				}
+
+				if (disconnectError) {
+					throw disconnectError;
+				}
+			});
+		},
+		async wrapWithAutoRefresh(ctx, operation) {
+			try {
+				return await operation();
+			} catch (error) {
+				if (is401or403(error) && config?.refresh) {
+					const originalError = error;
+					await manager.refresh(ctx);
+
+					try {
+						return await operation();
+					} catch {
+						throw originalError;
+					}
+				}
+
+				throw error;
+			}
+		},
+		getFields() {
+			return config?.fields ?? [];
+		},
+		createAuthContext() {
+			return authContext;
+		},
+		resolveField(name, value) {
+			const pendingRequest = pendingFieldRequests.get(name);
+
+			if (!pendingRequest) {
+				resolvedFieldValues.set(name, value);
+				return;
+			}
+
+			clearTimeout(pendingRequest.timeoutId);
+			pendingRequest.resolve(value);
+		},
+		getPendingFields() {
+			return Array.from(pendingFieldRequests.keys());
+		},
+		isAuthNone() {
+			return !config || config.mode === "none";
+		},
+	};
+
+	return manager;
+}