@vibesdotdev/client 0.1.0

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

@@ -0,0 +1,167 @@
+import type { AuthConfig, ClientConfig, ClientHooks, RequestOptions } from '../types.ts';
+import { APIGenerator, type OpenAPISpec } from './generator.ts';
+import { getRuntimeEnv } from '@vibesdotdev/runtime';
+import { RequestBuilder } from './request-builder.ts';
+import { streamSSE, type SSEEvent, type SSEStreamOptions } from './sse-stream.ts';
+import { createHookedFetch } from './wrap-fetch.ts';
+
+interface ResolvedClientConfig {
+	baseUrl: string;
+	auth: AuthConfig;
+	fetch: typeof fetch;
+	hooks: ClientHooks;
+	timeout: number;
+	debug: boolean;
+}
+
+export class VibesClient {
+	private config: ResolvedClientConfig;
+	private requestBuilder: RequestBuilder;
+	private apiGenerator: APIGenerator;
+	private apis: Record<string, unknown> = {};
+	private specPromise: Promise<OpenAPISpec> | null = null;
+
+	constructor(config: ClientConfig = {}) {
+		const baseUrl =
+			config.baseUrl ||
+			getRuntimeEnv('VIBES_API_URL') ||
+			'http://localhost:5173';
+		const fetchImpl = config.fetch || globalThis.fetch?.bind(globalThis);
+		if (!fetchImpl)
+			throw new Error('Fetch is not available. Please provide a fetch implementation.');
+		const hooks = config.hooks || {};
+		this.config = {
+			baseUrl,
+			auth: config.auth || { type: 'none' },
+			fetch: fetchImpl as typeof fetch,
+			hooks,
+			timeout: config.timeout || 30000,
+			debug: config.debug || false
+		};
+		const hookedFetch = createHookedFetch({
+			fetchImpl: this.config.fetch,
+			hooks: this.config.hooks
+		});
+		this.requestBuilder = new RequestBuilder(
+			this.config.baseUrl,
+			this.config.auth,
+			hookedFetch as typeof fetch,
+			this.config.timeout,
+			this.config.debug
+		);
+		this.apiGenerator = new APIGenerator(this.requestBuilder);
+	}
+
+	private async initialize(): Promise<void> {
+		try {
+			const spec = await this.getOpenAPISpec();
+			this.buildAPIs(spec);
+		} catch (error) {
+			const shouldWarn =
+				this.config.debug ||
+				(typeof process !== 'undefined' && process.env?.VIBES_CLIENT_WARN_OAS === 'true');
+			if (shouldWarn) {
+				console.warn('Failed to load OpenAPI spec, client will have limited functionality:', error);
+			}
+		}
+	}
+
+	getOpenAPISpec(): Promise<OpenAPISpec> {
+		if (!this.specPromise) this.specPromise = this.fetchOpenAPISpec();
+		return this.specPromise;
+	}
+
+	private async fetchOpenAPISpec(): Promise<OpenAPISpec> {
+		const response = await this.config.fetch(`${this.config.baseUrl}/api/docs/openapi.json`);
+		if (!response.ok) throw new Error(`Failed to fetch OpenAPI spec: ${response.statusText}`);
+		return response.json() as Promise<OpenAPISpec>;
+	}
+
+	private buildAPIs(spec: OpenAPISpec): void {
+		const apis = this.apiGenerator.generateAPIs(spec);
+		for (const [name, api] of Object.entries(apis)) {
+			this.apis[name] = api;
+			Object.defineProperty(this, name, {
+				get: () => this.apis[name],
+				enumerable: true,
+				configurable: true
+			});
+		}
+	}
+
+	request<T = unknown>(
+		path: string,
+		options: {
+			method?: string;
+			params?: Record<string, string | number | boolean>;
+			query?: Record<string, string | number | boolean | string[] | undefined>;
+			body?: unknown;
+			headers?: Record<string, string>;
+			timeout?: number;
+		} = {}
+	): Promise<T> {
+		return this.requestBuilder.request({
+			path,
+			method: options.method || 'GET',
+			params: options.params,
+			query: options.query,
+			body: options.body,
+			headers: options.headers,
+			timeout: options.timeout
+		});
+	}
+
+	setAuth(auth: AuthConfig): void {
+		this.config.auth = auth;
+		const hookedFetch = createHookedFetch({
+			fetchImpl: this.config.fetch,
+			hooks: this.config.hooks
+		});
+		this.requestBuilder = new RequestBuilder(
+			this.config.baseUrl,
+			auth,
+			hookedFetch as typeof fetch,
+			this.config.timeout,
+			this.config.debug
+		);
+		this.apiGenerator = new APIGenerator(this.requestBuilder);
+		if (this.specPromise) this.specPromise.then((spec) => this.buildAPIs(spec));
+	}
+
+	getResources(): string[] {
+		return Object.keys(this.apis);
+	}
+
+	hasResource(name: string): boolean {
+		return name in this.apis;
+	}
+
+	get<T = unknown>(endpoint: string, options?: RequestOptions): Promise<T> {
+		return this.request<T>(endpoint, { ...options, method: 'GET' });
+	}
+
+	post<T = unknown>(endpoint: string, body?: unknown, options?: RequestOptions): Promise<T> {
+		return this.request<T>(endpoint, { ...options, method: 'POST', body });
+	}
+
+	put<T = unknown>(endpoint: string, body?: unknown, options?: RequestOptions): Promise<T> {
+		return this.request<T>(endpoint, { ...options, method: 'PUT', body });
+	}
+
+	delete<T = unknown>(endpoint: string, options?: RequestOptions): Promise<T> {
+		return this.request<T>(endpoint, { ...options, method: 'DELETE' });
+	}
+
+	async *stream<T = unknown>(
+		path: string,
+		options: SSEStreamOptions = {}
+	): AsyncIterableIterator<SSEEvent<T>> {
+		yield* streamSSE<T>({
+			baseUrl: this.config.baseUrl,
+			auth: this.config.auth,
+			fetchImpl: this.config.fetch,
+			path,
+			options
+		});
+	}
+}

package/src/lib/client/internal/wrap-fetch.ts

@@ -0,0 +1,59 @@
+import { ClientError, type ClientHooks } from '../types.ts';
+
+export function createHookedFetch(args: {
+	fetchImpl: typeof fetch;
+	hooks: ClientHooks;
+}): (input: Parameters<typeof fetch>[0], init?: RequestInit) => Promise<Response> {
+	return async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+		if (!args.hooks.beforeRequest) {
+			let response: Response;
+			try {
+				response = await args.fetchImpl(input, init);
+			} catch (error) {
+				if (args.hooks.onError) {
+					await args.hooks.onError(
+						new ClientError(
+							error instanceof Error ? error.message : 'Network error',
+							0,
+							undefined,
+							undefined
+						)
+					);
+				}
+				throw error;
+			}
+			if (args.hooks.afterResponse) response = await args.hooks.afterResponse(response);
+			return response;
+		}
+		const requestInput = input instanceof URL
+			? new Request(input.href, init)
+			: typeof input === 'string'
+				? new Request(input, init)
+				: new Request(input, init);
+		const modifiedRequest = await args.hooks.beforeRequest(requestInput);
+		const modifiedInit: RequestInit = {
+			...init,
+			method: modifiedRequest.method,
+			headers: Object.fromEntries(modifiedRequest.headers.entries()),
+			...(modifiedRequest.body !== requestInput.body && { body: modifiedRequest.body })
+		};
+		let response: Response;
+		try {
+			response = await args.fetchImpl(modifiedRequest.url, modifiedInit);
+		} catch (error) {
+			if (args.hooks.onError) {
+				await args.hooks.onError(
+					new ClientError(
+						error instanceof Error ? error.message : 'Network error',
+						0,
+						undefined,
+						undefined
+					)
+				);
+			}
+			throw error;
+		}
+		if (args.hooks.afterResponse) response = await args.hooks.afterResponse(response);
+		return response;
+	};
+}

package/src/lib/client/node.ts

@@ -0,0 +1,36 @@
+import { getRuntimeEnv } from '@vibesdotdev/runtime';
+import type { ClientConfig } from './types.ts';
+import { VibesClient } from './internal/vibes-client.ts';
+
+export { createHttp2Fetch } from './internal/node/http2-fetch.node.ts';
+
+async function resolveNodeFetch(baseUrl: string): Promise<typeof globalThis.fetch> {
+	const isHttps = baseUrl.startsWith('https://');
+	const isLocal =
+		baseUrl.includes('.local') || baseUrl.includes('localhost') || baseUrl.includes('127.0.0.1');
+	if (isHttps && isLocal) {
+		try {
+			if (!getRuntimeEnv('REJECT_UNAUTHORIZED')) {
+				globalThis.process?.['env'] && (globalThis.process.env.REJECT_UNAUTHORIZED = 'false');
+			}
+			const { createHttp2Fetch } = await import('./internal/node/http2-fetch.node.js');
+			return createHttp2Fetch(baseUrl) as unknown as typeof globalThis.fetch;
+		} catch {
+			// Fallback to regular fetch if h2 module unavailable
+		}
+	}
+	return globalThis.fetch;
+}
+
+export async function createCLIClient(config?: Partial<ClientConfig>): Promise<VibesClient> {
+	const baseUrl = config?.baseUrl || getRuntimeEnv('VIBES_API_URL') || 'http://localhost:5173';
+	const fetchImpl = config?.fetch || (await resolveNodeFetch(baseUrl));
+	const clientConfig: ClientConfig = {
+		baseUrl,
+		auth: config?.auth || { type: 'none' },
+		fetch: fetchImpl,
+		debug: getRuntimeEnv('VIBES_DEBUG') === 'true',
+		...config
+	};
+	return new VibesClient(clientConfig);
+}

package/src/lib/client/types.ts

@@ -0,0 +1,156 @@
+/**
+ * Vibes Client Types
+ *
+ * Configuration, errors, and type contracts for the VibesClient HTTP API client.
+ * Extracted from libraries/vibeskit (PR #447 migration) to canonicalize as a
+ * pure-isomorphic @vibesdotdev/client surface.
+ */
+
+/** Authentication configuration */
+export interface AuthConfig {
+	/** Authentication type */
+	type: 'apiKey' | 'session' | 'bearer' | 'none';
+	/** Static credentials */
+	credentials?: string;
+	/** Dynamic token provider */
+	tokenProvider?: () => Promise<string | null>;
+	/** Session refresh handler for expired sessions */
+	refreshHandler?: () => Promise<AuthConfig | null>;
+}
+
+/** Client lifecycle hooks */
+export interface ClientHooks {
+	/** Called before each request */
+	beforeRequest?: (request: Request) => Promise<Request> | Request;
+	/** Called after each response */
+	afterResponse?: (response: Response) => Promise<Response> | Response;
+	/** Called on request error */
+	onError?: (error: ClientError) => Promise<void> | void;
+}
+
+/** Request options */
+export interface RequestOptions {
+	/** HTTP method */
+	method: string;
+	/** Request path (will be appended to baseUrl) */
+	path: string;
+	/** URL parameters */
+	params?: Record<string, string | number | boolean>;
+	/** Query parameters */
+	query?: Record<string, string | number | boolean | string[] | undefined>;
+	/** Request body */
+	body?: unknown;
+	/** Additional headers */
+	headers?: Record<string, string>;
+	/** Override timeout for this request */
+	timeout?: number;
+}
+
+/** Client configuration options */
+export interface ClientConfig {
+	/** Base URL for API requests */
+	baseUrl?: string;
+	/** Authentication configuration */
+	auth?: AuthConfig;
+	/** Custom fetch implementation */
+	fetch?: typeof fetch;
+	/** Request/response hooks */
+	hooks?: ClientHooks;
+	/** Request timeout in milliseconds */
+	timeout?: number;
+	/** Enable debug logging */
+	debug?: boolean;
+}
+
+/** Client error with additional context */
+export class ClientError extends Error {
+	constructor(
+		message: string,
+		public status?: number,
+		public response?: Response,
+		public request?: RequestOptions
+	) {
+		super(message);
+		this.name = 'ClientError';
+	}
+}
+
+/** Paginated response wrapper */
+export interface PaginatedResponse<T> {
+	data: T[];
+	total: number;
+	page: number;
+	pageSize: number;
+	hasMore: boolean;
+}
+
+/** Standard list parameters */
+export interface ListParams {
+	/** Page number (1-based) */
+	page?: number;
+	/** Items per page */
+	limit?: number;
+	/** Sort field */
+	sortBy?: string;
+	/** Sort direction */
+	sortOrder?: 'asc' | 'desc';
+	/** Search query */
+	search?: string;
+	/** Additional filters */
+	filters?: Record<string, unknown>;
+}
+
+/** OpenAPI path info (generic -- no openapi-types dependency) */
+export interface PathInfo {
+	path: string;
+	method: string;
+	operationId?: string;
+	parameters?: Record<string, unknown>[];
+	requestBody?: Record<string, unknown>;
+	responses?: Record<string, unknown>;
+	tags?: string[];
+	summary?: string;
+	description?: string;
+}
+
+/** Grouped API resources */
+export interface APIResource {
+	name: string;
+	basePath: string;
+	operations: Map<string, PathInfo>;
+}
+
+/**
+ * Migration debt: ClientUser is an auth-domain type owned by @vibesdotdev/auth.
+ * Defined here temporarily so @vibesdotdev/kit/client consumers can migrate.
+ * Target: move to packages/auth/src/shared/client-user.ts and re-export from client/core.
+ */
+export interface ClientUser {
+	id: string;
+	email: string;
+	displayName?: string | null;
+	avatarUrl?: string | null;
+	isSuperuser?: boolean;
+	roles?: Array<{
+		id: string;
+		name: string;
+		description: string | null;
+		isSystemRole: boolean;
+	}>;
+	permissions?: string[];
+}
+
+/**
+ * Type helpers for schema conversion
+ */
+export type SchemaToType<T> = T extends { type: 'string' }
+	? string
+	: T extends { type: 'number' }
+		? number
+		: T extends { type: 'boolean' }
+			? boolean
+			: T extends { type: 'array'; items: infer I }
+				? Array<SchemaToType<I>>
+				: T extends { type: 'object'; properties: infer P }
+					? { [K in keyof P]: SchemaToType<P[K]> }
+						: unknown;

package/src/plugin.ts

@@ -0,0 +1,104 @@
+import { createRuntimePlugin, loader } from '@vibesdotdev/runtime';
+import type { RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/descriptor';
+import {
+	ApiClientDescriptorSchema,
+	type ApiClientDescriptor,
+	type ApiClientImplementation,
+	type ApiStreamEvent
+} from './schemas.ts';
+import { vibesApiClient } from './factory.ts';
+import type { KindContext, RuntimeKindDescriptorRecord } from '@vibesdotdev/runtime/schemas/kind';
+import apiRequestToolDescriptor from './tools/api-request/api-request.descriptor.ts';
+
+function isApiClientDescriptor(descriptor: RuntimeDescriptor): descriptor is ApiClientDescriptor {
+	return descriptor.kind === 'api/client' && typeof descriptor.id === 'string';
+}
+
+/**
+ * Default API client implementation.
+ *
+ * When no specific client implementation is registered for a descriptor,
+ * this default constructs a client using the descriptor's baseUrl.
+ */
+class DefaultApiClient implements ApiClientImplementation {
+	private client: ApiClientImplementation;
+
+	constructor(descriptor: RuntimeDescriptor, _context: KindContext) {
+		if (!isApiClientDescriptor(descriptor)) {
+			throw new Error(`Invalid api/client descriptor '${descriptor.id ?? 'unknown'}'`);
+		}
+
+		this.client = vibesApiClient({
+			id: descriptor.id,
+			baseUrl: descriptor.baseUrl,
+			timeout: descriptor.timeout,
+			debug: descriptor.debug
+		});
+	}
+
+	get<T = unknown>(endpoint: string, options?: Parameters<ApiClientImplementation['get']>[1]): Promise<T> {
+		return this.client.get<T>(endpoint, options);
+	}
+
+	post<T = unknown>(endpoint: string, body?: unknown, options?: Parameters<ApiClientImplementation['post']>[2]): Promise<T> {
+		return this.client.post<T>(endpoint, body, options);
+	}
+
+	put<T = unknown>(endpoint: string, body?: unknown, options?: Parameters<ApiClientImplementation['put']>[2]): Promise<T> {
+		return this.client.put<T>(endpoint, body, options);
+	}
+
+	patch<T = unknown>(endpoint: string, body?: unknown, options?: Parameters<ApiClientImplementation['patch']>[2]): Promise<T> {
+		return this.client.patch<T>(endpoint, body, options);
+	}
+
+	delete<T = unknown>(endpoint: string, options?: Parameters<ApiClientImplementation['delete']>[1]): Promise<T> {
+		return this.client.delete<T>(endpoint, options);
+	}
+
+	request<T = unknown>(endpoint: string, options?: Parameters<ApiClientImplementation['request']>[1]): Promise<T> {
+		return this.client.request<T>(endpoint, options);
+	}
+
+	stream<T = unknown>(
+		endpoint: string,
+		options?: Parameters<ApiClientImplementation['stream']>[1]
+	): AsyncIterableIterator<ApiStreamEvent<T>> {
+		return this.client.stream<T>(endpoint, options) as AsyncIterableIterator<ApiStreamEvent<T>>;
+	}
+}
+
+const apiClientKind = {
+	id: 'api/client',
+	descriptorSchema: ApiClientDescriptorSchema,
+	defaultImplementation: DefaultApiClient
+} satisfies RuntimeKindDescriptorRecord<ApiClientImplementation>;
+
+/**
+ * Client plugin — registers the `api/client` kind with the runtime.
+ *
+ * @example
+ * ```ts
+ * import { getVibesRuntime } from '@vibesdotdev/runtime';
+ * import clientPlugin from '@vibesdotdev/client/plugin';
+ *
+ * const runtime = getVibesRuntime();
+ * await runtime.registerPlugin(clientPlugin);
+ *
+ * // Query a registered API client
+ * const authClient = await runtime.query('api/client').withId('auth').resolve();
+ * await authClient.get('/api/health');
+ * ```
+ */
+export default createRuntimePlugin({
+	id: 'client',
+	name: 'API Client Module',
+	description: 'Runtime API client kind with environment-aware factories',
+	kinds: [apiClientKind],
+	descriptors: [apiRequestToolDescriptor],
+	loaders: [
+		loader('api-request', { kind: 'tools/tool', scope: 'consumer' }, () =>
+			import('./tools/api-request/api-request.impl.consumer.js')
+		)
+	]
+});

package/src/schemas.ts

@@ -0,0 +1,91 @@
+import * as z from 'zod/v4';
+import {
+	RuntimeDescriptorSchema,
+	type RuntimeDescriptor
+} from '@vibesdotdev/runtime/schemas/descriptor';
+
+/**
+ * API Client descriptor — metadata for a registered API client asset.
+ */
+export interface ApiClientDescriptor extends RuntimeDescriptor {
+	kind: 'api/client';
+	/** Base URL for this client's API */
+	baseUrl?: string;
+	/** Default timeout in milliseconds */
+	timeout?: number;
+	/** Whether to enable debug logging */
+	debug?: boolean;
+}
+
+export const ApiClientDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('api/client'),
+	baseUrl: z.string().optional(),
+	timeout: z.number().int().positive().optional(),
+	debug: z.boolean().optional()
+});
+
+/**
+ * API Client implementation interface.
+ *
+ * Any runtime API client implementation must satisfy this contract.
+ */
+export interface ApiClientImplementation {
+	/** Make a GET request */
+	get<T = unknown>(endpoint: string, options?: ApiRequestOptions): Promise<T>;
+	/** Make a POST request */
+	post<T = unknown>(endpoint: string, body?: unknown, options?: ApiRequestOptions): Promise<T>;
+	/** Make a PUT request */
+	put<T = unknown>(endpoint: string, body?: unknown, options?: ApiRequestOptions): Promise<T>;
+	/** Make a PATCH request */
+	patch<T = unknown>(endpoint: string, body?: unknown, options?: ApiRequestOptions): Promise<T>;
+	/** Make a DELETE request */
+	delete<T = unknown>(endpoint: string, options?: ApiRequestOptions): Promise<T>;
+	/** Make a generic request */
+	request<T = unknown>(
+		endpoint: string,
+		options?: ApiRequestOptions & { method?: string; body?: unknown }
+	): Promise<T>;
+	/**
+	 * Stream Server-Sent Events from an endpoint.
+	 *
+	 * Yields parsed SSE frames as they arrive. Each frame has already been
+	 * split into event/data/id/retry fields and the data payload is
+	 * JSON-parsed when possible. Returning from the generator — or the
+	 * server closing the stream — ends iteration; an explicit `[DONE]`
+	 * sentinel in the data stream also terminates.
+	 *
+	 * Use this instead of manually parsing SSE-wrapped POST bodies — the
+	 * raw-fetch workaround (line-split + regex for `data: ...` lines) is
+	 * brittle and fails on multi-line data, retry hints, and reconnects.
+	 */
+	stream<T = unknown>(
+		endpoint: string,
+		options?: ApiStreamOptions
+	): AsyncIterableIterator<ApiStreamEvent<T>>;
+}
+
+export interface ApiRequestOptions {
+	query?: Record<string, string | number | boolean | string[] | undefined>;
+	headers?: Record<string, string>;
+	timeout?: number;
+	params?: Record<string, string | number | boolean>;
+}
+
+export interface ApiStreamOptions extends ApiRequestOptions {
+	method?: string;
+	body?: unknown;
+}
+
+/**
+ * A single Server-Sent Event frame.
+ *
+ * `data` is JSON-parsed when the frame payload is valid JSON, otherwise
+ * the raw string is returned. `event`, `id`, and `retry` map to the
+ * corresponding SSE fields when present.
+ */
+export interface ApiStreamEvent<T = unknown> {
+	event?: string;
+	data: T;
+	id?: string;
+	retry?: number;
+}