@vibesdotdev/client 0.1.0

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@vibesdotdev/client",
+  "version": "0.1.0",
+  "description": "Base API client with runtime kind integration and per-app client factories",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "bun": "./src/plugin.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./factory": {
+      "types": "./dist/factory.d.ts",
+      "bun": "./src/factory.ts",
+      "import": "./dist/factory.js",
+      "default": "./dist/factory.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas.d.ts",
+      "bun": "./src/schemas.ts",
+      "import": "./dist/schemas.js",
+      "default": "./dist/schemas.js"
+    },
+    "./core": {
+      "types": "./dist/lib/client/core.d.ts",
+      "bun": "./src/lib/client/core.ts",
+      "import": "./dist/lib/client/core.js",
+      "default": "./dist/lib/client/core.js"
+    },
+    "./types": {
+      "types": "./dist/lib/client/types.d.ts",
+      "bun": "./src/lib/client/types.ts",
+      "import": "./dist/lib/client/types.js",
+      "default": "./dist/lib/client/types.js"
+    },
+    "./node": {
+      "types": "./dist/lib/client/node.d.ts",
+      "bun": "./src/lib/client/node.ts",
+      "import": "./dist/lib/client/node.js",
+      "default": "./dist/lib/client/node.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibesdotdev/monorepo.git",
+    "directory": "packages/client"
+  },
+  "dependencies": {
+    "@vibesdotdev/runtime": "0.0.1",
+    "@vibesdotdev/logging": "0.0.1",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun test",
+    "check": "bun --bun tsc -p tsconfig.json --noEmit"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "README.md",
+    "SPEC.md",
+    "LICENSE",
+    "!src/**/__tests__/**",
+    "!src/**/__stubs__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!dist/**/__tests__/**",
+    "!dist/**/__stubs__/**",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/**/*.spec.js",
+    "!dist/**/*.spec.js.map",
+    "!dist/**/*.spec.d.ts",
+    "!dist/**/*.spec.d.ts.map"
+  ],
+  "vibes": {
+    "visibility": "public-framework"
+  }
+}

package/src/factory.ts

@@ -0,0 +1,114 @@
+import { VibesClient } from './lib/client/core.ts';
+import type { ClientConfig, AuthConfig } from './lib/client/types.ts';
+import type {
+	ApiClientImplementation,
+	ApiRequestOptions,
+	ApiStreamEvent,
+	ApiStreamOptions
+} from './schemas.ts';
+
+export interface ApiClientConfig {
+	/** Unique identifier for this client instance */
+	id?: string;
+	/** Base URL for API requests */
+	baseUrl?: string;
+	/** Authentication configuration */
+	auth?: AuthConfig;
+	/** Custom fetch implementation */
+	fetch?: typeof fetch;
+	/** Request timeout in milliseconds */
+	timeout?: number;
+	/** Enable debug logging */
+	debug?: boolean;
+	/** Custom headers applied to all requests */
+	headers?: Record<string, string>;
+}
+
+/**
+ * Wrap a VibesClient to satisfy the ApiClientImplementation interface.
+ */
+function wrapVibesClient(client: VibesClient): ApiClientImplementation {
+	return {
+		get<T = unknown>(endpoint: string, options?: ApiRequestOptions): Promise<T> {
+			return client.get<T>(endpoint, { method: 'GET', path: endpoint, ...options });
+		},
+		post<T = unknown>(endpoint: string, body?: unknown, options?: ApiRequestOptions): Promise<T> {
+			return client.post<T>(endpoint, body, { method: 'POST', path: endpoint, ...options });
+		},
+		put<T = unknown>(endpoint: string, body?: unknown, options?: ApiRequestOptions): Promise<T> {
+			return client.put<T>(endpoint, body, { method: 'PUT', path: endpoint, ...options });
+		},
+		patch<T = unknown>(endpoint: string, body?: unknown, options?: ApiRequestOptions): Promise<T> {
+			return client.request<T>(endpoint, { method: 'PATCH', body, ...options });
+		},
+		delete<T = unknown>(endpoint: string, options?: ApiRequestOptions): Promise<T> {
+			return client.delete<T>(endpoint, { method: 'DELETE', path: endpoint, ...options });
+		},
+		request<T = unknown>(
+			endpoint: string,
+			options?: ApiRequestOptions & { method?: string; body?: unknown }
+		): Promise<T> {
+			return client.request<T>(endpoint, {
+				method: options?.method ?? 'GET',
+				...options
+			});
+		},
+		stream<T = unknown>(
+			endpoint: string,
+			options?: ApiStreamOptions
+		): AsyncIterableIterator<ApiStreamEvent<T>> {
+			return client.stream<T>(endpoint, {
+				method: options?.method ?? 'POST',
+				body: options?.body,
+				headers: options?.headers,
+				params: options?.params,
+				query: options?.query,
+				timeout: options?.timeout
+			}) as AsyncIterableIterator<ApiStreamEvent<T>>;
+		}
+	};
+}
+
+/**
+ * Create an API client instance.
+ *
+ * @example
+ * ```ts
+ * const client = vibesApiClient({ baseUrl: 'https://api.vibes.dev' });
+ * const data = await client.get('/users');
+ * ```
+ */
+export function vibesApiClient(config: ApiClientConfig = {}): ApiClientImplementation {
+	const clientConfig: ClientConfig = {
+		baseUrl: config.baseUrl,
+		auth: config.auth,
+		fetch: config.fetch,
+		timeout: config.timeout,
+		debug: config.debug
+	};
+
+	if (config.headers && Object.keys(config.headers).length > 0) {
+		const headers = config.headers;
+		clientConfig.hooks = {
+			beforeRequest: async (request: Request): Promise<Request> => {
+				const updated = new Headers(request.headers);
+				for (const [key, value] of Object.entries(headers)) {
+					if (value !== undefined) {
+						updated.set(key, value);
+					}
+				}
+				return new Request(request, { headers: updated });
+			}
+		};
+	}
+
+	const vibes = new VibesClient(clientConfig);
+	return wrapVibesClient(vibes);
+}
+
+/**
+ * Create an API client from an existing VibesClient instance.
+ */
+export function fromVibesClient(client: VibesClient): ApiClientImplementation {
+	return wrapVibesClient(client);
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { vibesApiClient, fromVibesClient } from './factory.ts';
+export type { ApiClientConfig } from './factory.ts';
+export type {
+	ApiClientDescriptor,
+	ApiClientImplementation,
+	ApiRequestOptions,
+	ApiStreamOptions,
+	ApiStreamEvent
+} from './schemas.ts';
+export { ApiClientDescriptorSchema } from './schemas.ts';
+export { default as clientPlugin } from './plugin.ts';
+export { SSEClient, createSSEClient } from './sse-client.ts';
+export type { SSEClientOptions, SSEConnectionStatus } from './sse-client.ts';
+export { VibesClient } from './lib/client/core.ts';
+export type { ClientConfig, AuthConfig, ClientHooks, ClientError } from './lib/client/types.ts';

package/src/lib/client/core.ts

@@ -0,0 +1,13 @@
+export { VibesClient } from './internal/vibes-client.ts';
+export type { SSEEvent } from './internal/sse-stream.ts';
+export type {
+	ClientConfig,
+	AuthConfig,
+	ClientHooks,
+	ClientUser,
+	RequestOptions
+} from './types.ts';
+export { ClientError } from './types.ts';
+export { BaseAPIClient } from './internal/base-client.ts';
+export type { BaseAPIConfig, EndpointOptions } from './internal/base-types.ts';
+export { Endpoint } from './internal/endpoint.ts';

package/src/lib/client/internal/base-client.ts

@@ -0,0 +1,107 @@
+import { type BaseAPIConfig, type EndpointOptions, APIError } from './base-types.ts';
+import { buildHeaders, buildUrl, createApiError } from './base-helpers.ts';
+import { Endpoint } from './endpoint.ts';
+
+export abstract class BaseAPIClient {
+	protected config: Required<Omit<BaseAPIConfig, 'auth'>> & {
+		auth: BaseAPIConfig['auth'];
+	};
+	private abortControllers = new Set<AbortController>();
+
+	constructor(config: BaseAPIConfig) {
+		const merged: Required<Omit<BaseAPIConfig, 'auth'>> & {
+			auth: BaseAPIConfig['auth'];
+		} = {
+			baseUrl: config.baseUrl,
+			fetch: (config.fetch || globalThis.fetch?.bind(globalThis)) as typeof fetch,
+			headers: config.headers || {},
+			timeout: config.timeout || 30000,
+			debug: config.debug || false,
+			hooks: config.hooks || {},
+			auth: config.auth ?? null
+		};
+		if (!merged.fetch)
+			throw new Error('Fetch is not available. Please provide a fetch implementation.');
+		this.config = merged;
+	}
+
+	protected endpoint(path: string): Endpoint {
+		const cleanPath = path.startsWith('/') ? path : `/${path}`;
+		return new Endpoint(this, cleanPath);
+	}
+
+	async request<T = unknown>(
+		request: {
+			method: string;
+			path: string;
+			body?: unknown;
+		} & EndpointOptions<T>
+	): Promise<T> {
+		const url = buildUrl(this.config.baseUrl, request.path, request.query);
+		const controller = new AbortController();
+		this.abortControllers.add(controller);
+		try {
+			const authForHeaders = this.config.auth ?? { type: 'none' as const };
+		const headers = await buildHeaders({
+				auth: authForHeaders,
+				headers: { ...this.config.headers, ...request.headers },
+				includeJsonDefaults: request.body !== undefined
+			});
+			const init: RequestInit = {
+				method: request.method,
+				headers,
+				signal: controller.signal
+			};
+			const timeout = setTimeout(() => controller.abort(), request.timeout ?? this.config.timeout);
+			if (request.body !== undefined) init.body = JSON.stringify(request.body);
+			let req = new Request(url.toString(), init);
+			if (this.config.hooks?.beforeRequest) req = await this.config.hooks.beforeRequest(req);
+			const response = await this.config.fetch(req, init);
+			clearTimeout(timeout);
+			const finalResponse = this.config.hooks?.afterResponse
+				? await this.config.hooks.afterResponse(response)
+				: response;
+			if (!finalResponse.ok) {
+				const error = await createApiError(finalResponse, req);
+				if (this.config.hooks?.onError) await this.config.hooks.onError(error);
+				throw error;
+			}
+			let data: unknown;
+			if (finalResponse.status === 204 || finalResponse.headers.get('Content-Length') === '0')
+				data = undefined;
+			else if (finalResponse.headers.get('Content-Type')?.includes('application/json'))
+				data = await finalResponse.json();
+			else data = await finalResponse.text();
+			if (request.transform) data = request.transform(data);
+			if (request.schema) {
+				const result = request.schema.safeParse(data);
+				if (!result.success) {
+					throw new APIError(
+						`Response validation failed: ${result.error.message}`,
+						422,
+						finalResponse,
+						req,
+						data
+					);
+				}
+				return result.data;
+			}
+			return data as T;
+		} finally {
+			this.abortControllers.delete(controller);
+		}
+	}
+
+	cancelAll(): void {
+		for (const controller of this.abortControllers) controller.abort();
+		this.abortControllers.clear();
+	}
+
+	setAuth(auth: BaseAPIConfig['auth']): void {
+		this.config.auth = auth ?? null;
+	}
+
+	updateConfig(config: Partial<BaseAPIConfig>): void {
+		Object.assign(this.config, config);
+	}
+}

package/src/lib/client/internal/base-helpers.ts

@@ -0,0 +1,74 @@
+import { type BaseAPIConfig, type EndpointOptions, APIError } from './base-types.ts';
+
+export function buildUrl(baseUrl: string, path: string, query?: EndpointOptions['query']): URL {
+	const url = new URL(path, baseUrl);
+	if (query) {
+		for (const [key, value] of Object.entries(query)) {
+			if (value === undefined) continue;
+			if (Array.isArray(value)) value.forEach((v) => url.searchParams.append(key, String(v)));
+			else url.searchParams.set(key, String(value));
+		}
+	}
+	return url;
+}
+
+export async function buildHeaders(args: {
+	auth: NonNullable<BaseAPIConfig['auth']>;
+	headers: Record<string, string>;
+	includeJsonDefaults: boolean;
+}): Promise<Headers> {
+	const requestHeaders = new Headers(args.headers);
+	if (args.includeJsonDefaults && !requestHeaders.has('Content-Type')) {
+		requestHeaders.set('Content-Type', 'application/json');
+	}
+	if (!requestHeaders.has('Accept')) requestHeaders.set('Accept', 'application/json');
+
+	const auth = args.auth;
+	if (auth) {
+		const token = auth.credentials || (await auth.provider?.());
+		if (token) {
+			switch (auth.type) {
+				case 'bearer':
+					requestHeaders.set('Authorization', `Bearer ${token}`);
+					break;
+				case 'apiKey': {
+					const headerName = auth.headerName || 'X-API-Key';
+					requestHeaders.set(headerName, token);
+					break;
+				}
+				case 'basic':
+					requestHeaders.set('Authorization', `Basic ${token}`);
+					break;
+				case 'custom':
+					if (auth.headerName && auth.prefix) {
+						requestHeaders.set(auth.headerName, `${auth.prefix} ${token}`);
+					}
+					break;
+			}
+		}
+	}
+	return requestHeaders;
+}
+
+export async function createApiError(response: Response, request: Request): Promise<APIError> {
+	let message = `${response.status} ${response.statusText}`;
+	let body: unknown;
+	try {
+		const contentType = response.headers.get('Content-Type');
+		if (contentType?.includes('application/json')) {
+			body = await response.json();
+			if (typeof body === 'object' && body !== null) {
+				const errorBody = body as { message?: unknown; error?: unknown };
+				if (typeof errorBody.message === 'string') message = errorBody.message;
+				else if (typeof errorBody.error === 'string') message = errorBody.error;
+				else if (errorBody.error !== undefined) message = JSON.stringify(errorBody.error);
+			}
+		} else {
+			const text = await response.text();
+			if (text) { message = text; body = text; }
+		}
+	} catch {
+		// ignore parsing errors
+	}
+	return new APIError(message, response.status, response, request, body);
+}

package/src/lib/client/internal/base-types.ts

@@ -0,0 +1,42 @@
+import type { z } from 'zod/v4';
+
+export interface BaseAPIConfig {
+	baseUrl: string;
+	fetch?: typeof fetch;
+	headers?: Record<string, string>;
+	timeout?: number;
+	auth?: {
+		type: 'none' | 'bearer' | 'apiKey' | 'basic' | 'custom';
+		credentials?: string;
+		headerName?: string;
+		prefix?: string;
+		provider?: () => Promise<string | null>;
+	} | null;
+	debug?: boolean;
+	hooks?: {
+		beforeRequest?: (request: Request) => Promise<Request> | Request;
+		afterResponse?: (response: Response) => Promise<Response> | Response;
+		onError?: (error: APIError) => Promise<void> | void;
+	};
+}
+
+export class APIError extends Error {
+	constructor(
+		message: string,
+		public readonly status: number,
+		public readonly response?: Response,
+		public readonly request?: Request,
+		public readonly body?: unknown
+	) {
+		super(message);
+		this.name = 'APIError';
+	}
+}
+
+export interface EndpointOptions<T = unknown> {
+	headers?: Record<string, string>;
+	query?: Record<string, string | number | boolean | string[] | undefined>;
+	timeout?: number;
+	schema?: z.ZodSchema<T>;
+	transform?: (data: unknown) => T;
+}

package/src/lib/client/internal/endpoint.ts

@@ -0,0 +1,51 @@
+import type { EndpointOptions } from './base-types.ts';
+
+type RequestExecutor = {
+	request<T = unknown>(
+		options: {
+			method: string;
+			path: string;
+			body?: unknown;
+		} & EndpointOptions<T>
+	): Promise<T>;
+};
+
+export class Endpoint {
+	constructor(
+		private client: RequestExecutor,
+		private path: string
+	) {}
+
+	endpoint(subPath: string): Endpoint {
+		const cleanPath = subPath.startsWith('/') ? subPath : `/${subPath}`;
+		return new Endpoint(this.client, `${this.path}${cleanPath}`);
+	}
+
+	methods<T extends Record<string, (...args: never[]) => unknown>>(methods: T): T {
+		const bound = {} as { [K in keyof T]: T[K] };
+		for (const key of Object.keys(methods) as Array<keyof T>) {
+			bound[key] = methods[key].bind(this) as T[typeof key];
+		}
+		return bound as T;
+	}
+
+	get<T = unknown>(path = '', options?: EndpointOptions<T>): Promise<T> {
+		return this.client.request<T>({ method: 'GET', path: `${this.path}${path}`, ...options });
+	}
+
+	post<T = unknown>(path = '', body?: unknown, options?: EndpointOptions<T>): Promise<T> {
+		return this.client.request<T>({ method: 'POST', path: `${this.path}${path}`, body, ...options });
+	}
+
+	put<T = unknown>(path = '', body?: unknown, options?: EndpointOptions<T>): Promise<T> {
+		return this.client.request<T>({ method: 'PUT', path: `${this.path}${path}`, body, ...options });
+	}
+
+	patch<T = unknown>(path = '', body?: unknown, options?: EndpointOptions<T>): Promise<T> {
+		return this.client.request<T>({ method: 'PATCH', path: `${this.path}${path}`, body, ...options });
+	}
+
+	delete<T = unknown>(path = '', options?: EndpointOptions<T>): Promise<T> {
+		return this.client.request<T>({ method: 'DELETE', path: `${this.path}${path}`, ...options });
+	}
+}