@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.3

package/dist/lib/client/internal/generator.d.ts

@@ -0,0 +1,69 @@
+import * as z from 'zod/v4';
+import type { RequestBuilder, ResponseBody } from './request-builder.js';
+declare const ArgumentBagSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** A named-entry argument: the shape that carries a request body or a query. */
+export type ArgumentBag = z.infer<typeof ArgumentBagSchema>;
+/** A value a generated operation accepts as a call argument: a path id, a body, or a query bag. */
+export type OperationArgument = string | number | boolean | null | undefined | Date | unknown[] | ArgumentBag;
+/** One generated operation, e.g. `client.projects.list(query)`. */
+export type OperationFunction = (...args: OperationArgument[]) => Promise<ResponseBody>;
+/** The operations of one resource by name, e.g. `list`, `get`, `create`: `client.projects.list(...)`. */
+export type ResourceOperations = Record<string, OperationFunction>;
+/**
+ * OpenAPI spec subset sufficient for client generation. The document comes from the
+ * network, so each piece is parsed where it is read and a malformed piece is skipped.
+ */
+declare const ParameterSchema: z.ZodObject<{
+    name: z.ZodString;
+    in: z.ZodEnum<{
+        path: "path";
+        query: "query";
+        header: "header";
+        cookie: "cookie";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+declare const OperationSchema: z.ZodObject<{
+    operationId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    parameters: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodUnknown>>, z.ZodTransform<{
+        [x: string]: unknown;
+        name: string;
+        in: "path" | "query" | "header" | "cookie";
+        required?: boolean | undefined;
+    }[], unknown[] | undefined>>;
+    responses: z.ZodObject<{}, z.core.$loose>;
+}, z.core.$loose>;
+declare const PathItemSchema: z.ZodObject<{
+    parameters: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodUnknown>>, z.ZodTransform<{
+        [x: string]: unknown;
+        name: string;
+        in: "path" | "query" | "header" | "cookie";
+        required?: boolean | undefined;
+    }[], unknown[] | undefined>>;
+    get: z.ZodOptional<z.ZodUnknown>;
+    post: z.ZodOptional<z.ZodUnknown>;
+    put: z.ZodOptional<z.ZodUnknown>;
+    patch: z.ZodOptional<z.ZodUnknown>;
+    delete: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export declare const OpenAPISpecSchema: z.ZodObject<{
+    paths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type OpenAPIParameter = z.infer<typeof ParameterSchema>;
+export type OpenAPIOperation = z.infer<typeof OperationSchema>;
+export type OpenAPIPathItem = z.infer<typeof PathItemSchema>;
+export type OpenAPISpec = z.infer<typeof OpenAPISpecSchema>;
+export declare class APIGenerator {
+    private requestBuilder;
+    constructor(requestBuilder: RequestBuilder);
+    generateAPIs(spec: OpenAPISpec): Record<string, ResourceOperations>;
+    private groupPathsByResource;
+    private extractResourceName;
+    private getOperationName;
+    private createResourceAPI;
+    private createOperation;
+    private buildRequestOptions;
+    private addConvenienceMethods;
+    private toCamelCase;
+}
+export {};

package/dist/lib/client/internal/generator.js

@@ -0,0 +1,213 @@
+import * as z from 'zod/v4';
+import { settle } from '../../attempt.js';
+const ScalarSchema = z.union([z.string(), z.number(), z.boolean()]);
+const ArgumentBagSchema = z.record(z.string(), z.unknown());
+/**
+ * OpenAPI spec subset sufficient for client generation. The document comes from the
+ * network, so each piece is parsed where it is read and a malformed piece is skipped.
+ */
+const ParameterSchema = z.looseObject({
+    name: z.string(),
+    in: z.enum(['path', 'query', 'header', 'cookie']),
+    required: z.boolean().optional()
+});
+const ParameterListSchema = z
+    .array(z.unknown())
+    .optional()
+    .transform((items) => (items ?? []).flatMap((item) => {
+    const parameter = ParameterSchema.safeParse(item);
+    return parameter.success ? [parameter.data] : [];
+}));
+const OperationSchema = z.looseObject({
+    operationId: z.string().optional().catch(undefined),
+    parameters: ParameterListSchema,
+    // An operation is only an operation when it declares its responses.
+    responses: z.looseObject({})
+});
+const PathItemSchema = z.looseObject({
+    parameters: ParameterListSchema,
+    get: z.unknown().optional(),
+    post: z.unknown().optional(),
+    put: z.unknown().optional(),
+    patch: z.unknown().optional(),
+    delete: z.unknown().optional()
+});
+export const OpenAPISpecSchema = z.looseObject({
+    paths: z.record(z.string(), z.unknown()).optional()
+});
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+/** An object or array argument: the shapes that carry a body or a query; an array contributes its index entries. */
+const CompositeArgumentSchema = z
+    .union([ArgumentBagSchema, z.array(z.unknown())])
+    .transform((composite) => Object.fromEntries(Object.entries(composite)));
+const QueryValueSchema = z.union([
+    ScalarSchema,
+    z.undefined(),
+    z.array(z.unknown()).transform((items) => items.map(String)),
+    z.unknown().transform(String)
+]);
+const NotFoundSchema = z.object({ status: z.literal(404) });
+function coerceScalar(value) {
+    const scalar = ScalarSchema.safeParse(value);
+    return scalar.success ? scalar.data : String(value);
+}
+function coerceQuery(input) {
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        out[key] = QueryValueSchema.parse(value);
+    }
+    return out;
+}
+/** The named entries of a composite argument, or null when the argument is not one. */
+function asBag(value) {
+    const composite = CompositeArgumentSchema.safeParse(value);
+    return composite.success ? composite.data : null;
+}
+export class APIGenerator {
+    requestBuilder;
+    constructor(requestBuilder) {
+        this.requestBuilder = requestBuilder;
+    }
+    generateAPIs(spec) {
+        return Object.fromEntries([...this.groupPathsByResource(spec).values()].map((resource) => [
+            resource.name,
+            this.createResourceAPI(resource)
+        ]));
+    }
+    groupPathsByResource(spec) {
+        const resources = new Map();
+        for (const [path, rawPathItem] of Object.entries(spec.paths ?? {})) {
+            const pathItem = PathItemSchema.safeParse(rawPathItem);
+            if (!pathItem.success)
+                continue;
+            const resourceName = this.extractResourceName(path);
+            if (!resourceName)
+                continue;
+            let resource = resources.get(resourceName);
+            if (!resource) {
+                resource = { name: resourceName, operations: new Map() };
+                resources.set(resourceName, resource);
+            }
+            for (const method of HTTP_METHODS) {
+                const operation = OperationSchema.safeParse(pathItem.data[method]);
+                if (!operation.success)
+                    continue;
+                const pathInfo = {
+                    path,
+                    method: method.toUpperCase(),
+                    operationId: operation.data.operationId,
+                    parameters: [...pathItem.data.parameters, ...operation.data.parameters]
+                };
+                resource.operations.set(this.getOperationName(pathInfo), pathInfo);
+            }
+        }
+        return resources;
+    }
+    extractResourceName(path) {
+        const segments = path.split('/').filter(Boolean);
+        if (segments[0] !== 'api' || segments.length < 2) {
+            return null;
+        }
+        return this.toCamelCase(segments[1]);
+    }
+    getOperationName(pathInfo) {
+        const pathParts = pathInfo.path.split('/').filter(Boolean);
+        const method = pathInfo.method.toLowerCase();
+        const hasPathParam = pathInfo.path.includes('{');
+        const resourceName = pathParts[1];
+        if (method === 'get' && !hasPathParam)
+            return 'list';
+        if (method === 'get' && hasPathParam)
+            return 'get';
+        if (method === 'post' && !hasPathParam)
+            return 'create';
+        if ((method === 'put' || method === 'patch') && hasPathParam)
+            return 'update';
+        if (method === 'delete' && hasPathParam)
+            return 'delete';
+        if (pathInfo.operationId) {
+            let opName = pathInfo.operationId;
+            if (resourceName && opName.toLowerCase().startsWith(resourceName.slice(0, -1))) {
+                opName = opName.slice(resourceName.length - 1);
+            }
+            return this.toCamelCase(opName);
+        }
+        const lastPart = pathParts[pathParts.length - 1];
+        if (!lastPart.startsWith('{'))
+            return this.toCamelCase(lastPart);
+        return method;
+    }
+    createResourceAPI(resource) {
+        const api = Object.fromEntries([...resource.operations].map(([name, pathInfo]) => [name, this.createOperation(pathInfo)]));
+        this.addConvenienceMethods(api);
+        return api;
+    }
+    createOperation(pathInfo) {
+        return (...args) => {
+            const options = this.buildRequestOptions(pathInfo, args);
+            return this.requestBuilder.request(options);
+        };
+    }
+    buildRequestOptions(pathInfo, args) {
+        const options = {
+            method: pathInfo.method,
+            path: pathInfo.path
+        };
+        const params = {};
+        const query = {};
+        let body;
+        let argIndex = 0;
+        for (const param of pathInfo.parameters) {
+            if (param.in === 'path' && argIndex < args.length) {
+                params[param.name] = coerceScalar(args[argIndex++]);
+            }
+        }
+        if (argIndex < args.length) {
+            const nextBag = asBag(args[argIndex]);
+            if (nextBag) {
+                if (pathInfo.method === 'GET' || pathInfo.method === 'DELETE') {
+                    Object.assign(query, coerceQuery(nextBag));
+                }
+                else {
+                    body = args[argIndex];
+                    argIndex++;
+                    const tailBag = argIndex < args.length ? asBag(args[argIndex]) : null;
+                    if (tailBag)
+                        Object.assign(query, coerceQuery(tailBag));
+                }
+            }
+        }
+        if (Object.keys(params).length > 0)
+            options.params = params;
+        if (Object.keys(query).length > 0)
+            options.query = query;
+        if (body !== undefined)
+            options.body = body;
+        return options;
+    }
+    addConvenienceMethods(api) {
+        const { list, get, create } = api;
+        if (list && !api.search) {
+            api.search = (...args) => {
+                const [query, params] = args;
+                return list({ ...asBag(params), search: query });
+            };
+        }
+        if (get && create && !api.getOrCreate) {
+            api.getOrCreate = async (...args) => {
+                const [id, data] = args;
+                const found = await settle(() => get(id));
+                if (found.ok)
+                    return found.value;
+                if (!NotFoundSchema.safeParse(found.error).success)
+                    throw found.error;
+                return await create({ ...asBag(data), id });
+            };
+        }
+    }
+    toCamelCase(str) {
+        return str
+            .replace(/[-_](.)/g, (_, char) => char.toUpperCase())
+            .replace(/^(.)/, (_, char) => char.toLowerCase());
+    }
+}

package/dist/lib/client/internal/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Kit internal client exports.
+ */
+export { BaseAPIClient } from './base-client';
+export type { BaseAPIConfig, EndpointOptions } from './base-types';

package/dist/lib/client/internal/index.js

@@ -0,0 +1,4 @@
+/**
+ * Kit internal client exports.
+ */
+export { BaseAPIClient } from './base-client';

package/dist/lib/client/internal/node/http2-fetch.node.d.ts

@@ -0,0 +1,10 @@
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+export interface Http2FetchOptions {
+    rejectUnauthorized?: boolean;
+}
+/**
+ * Compatibility door: the HTTP/2 transport belongs to the selected host's
+ * `runtime/environment` (its `httpFetch` port), so the native client is
+ * resolved through the kind at call time instead of imported here.
+ */
+export declare function createHttp2Fetch(baseUrl: string, options?: Http2FetchOptions, runtime?: RuntimeRef): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

package/dist/lib/client/internal/node/http2-fetch.node.js

@@ -0,0 +1,24 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+/**
+ * Compatibility door: the HTTP/2 transport belongs to the selected host's
+ * `runtime/environment` (its `httpFetch` port), so the native client is
+ * resolved through the kind at call time instead of imported here.
+ */
+export function createHttp2Fetch(baseUrl, options = {}, runtime) {
+    const rejectUnauthorized = options.rejectUnauthorized ?? true;
+    return async (input, init) => {
+        const environment = runtime
+            ? await runtime
+                .query('runtime/environment')
+                .resolve()
+            : undefined;
+        const port = environment?.httpFetch;
+        if (!environment || !port) {
+            throw new CapabilityError('The selected host has no HTTP fetch transport.', 'UNAVAILABLE', {
+                reason: 'http-fetch-unavailable'
+            });
+        }
+        const target = input instanceof Request ? input : new URL(input, baseUrl);
+        return port.call(environment, target, init, { rejectUnauthorized });
+    };
+}

package/dist/lib/client/internal/request-builder.d.ts

@@ -0,0 +1,21 @@
+import type { AuthConfig, RequestOptions } from '../types.js';
+import type { FetchFunction } from './wrap-fetch.js';
+export type JsonResponse = string | number | boolean | null | JsonResponse[] | {
+    readonly [key: string]: JsonResponse;
+};
+/** What a successful response yields: its JSON value, its text, or nothing (204 / empty). */
+export type ResponseBody = JsonResponse | undefined;
+export declare class RequestBuilder {
+    private baseUrl;
+    private auth;
+    private fetchImpl;
+    private timeout;
+    private debug;
+    constructor(baseUrl: string, auth: AuthConfig, fetchImpl: FetchFunction, timeout?: number, debug?: boolean);
+    request<T = unknown>(options: RequestOptions): Promise<T>;
+    private readBody;
+    private buildUrl;
+    private buildHeaders;
+    private createAbortSignal;
+    private createError;
+}

package/dist/lib/client/internal/request-builder.js

@@ -0,0 +1,199 @@
+import * as z from 'zod/v4';
+import { ClientError } from '../types.js';
+import { settle } from '../../attempt.js';
+import { kitLogger } from '../../kit-logger.js';
+const logger = kitLogger('client');
+/** What a caller may hand the transport as a non-JSON request body. */
+const RawRequestBodySchema = z.union([
+    z.string(),
+    z.instanceof(Blob),
+    z.instanceof(FormData),
+    z.instanceof(URLSearchParams),
+    z.instanceof(ArrayBuffer),
+    z.instanceof(ReadableStream)
+]);
+/** One entry of a server's validation report; every field is optional and a malformed entry reads as empty. */
+const ValidationIssueSchema = z
+    .object({
+    path: z.array(z.unknown()).optional().catch(undefined),
+    message: z.string().optional().catch(undefined)
+})
+    .catch({});
+/** The error body shapes the platform's endpoints answer with. Anything else keeps the status line. */
+const ErrorBodySchema = z.object({
+    issues: z.array(ValidationIssueSchema).optional().catch(undefined),
+    errors: z.array(ValidationIssueSchema).optional().catch(undefined),
+    message: z.string().optional().catch(undefined),
+    error: z.unknown().optional()
+});
+function validationMessage(issues) {
+    const fieldErrors = issues
+        .map((issue) => {
+        const path = issue.path && issue.path.length > 0 ? issue.path.map(String).join('.') : 'unknown';
+        return `  - ${path}: ${issue.message ?? 'Invalid'}`;
+    })
+        .join('\n');
+    return `Validation failed:\n${fieldErrors}`;
+}
+/** The message a JSON error body carries, or null when it carries none the client understands. */
+function jsonErrorMessage(body) {
+    const parsed = ErrorBodySchema.safeParse(body);
+    if (!parsed.success)
+        return null;
+    const { issues, errors, message, error } = parsed.data;
+    const validationErrors = issues ?? errors;
+    if (validationErrors && validationErrors.length > 0)
+        return validationMessage(validationErrors);
+    if (message !== undefined)
+        return message;
+    if (error === undefined)
+        return null;
+    const text = z.string().safeParse(error);
+    return text.success ? text.data : JSON.stringify(error);
+}
+/**
+ * Where a request went, for diagnostics: the origin and path only. Query strings,
+ * headers, bodies and credentials never enter a log line or an error.
+ */
+function loggableTarget(url) {
+    return `${url.origin}${url.pathname}`;
+}
+export class RequestBuilder {
+    baseUrl;
+    auth;
+    fetchImpl;
+    timeout;
+    debug;
+    constructor(baseUrl, auth, fetchImpl, timeout = 30000, debug = false) {
+        this.baseUrl = baseUrl;
+        this.auth = auth;
+        this.fetchImpl = fetchImpl;
+        this.timeout = timeout;
+        this.debug = debug;
+    }
+    async request(options) {
+        const url = this.buildUrl(options);
+        const headers = await this.buildHeaders(options);
+        const init = {
+            method: options.method,
+            headers,
+            signal: this.createAbortSignal(options.timeout || this.timeout)
+        };
+        if (options.body !== undefined) {
+            const raw = RawRequestBodySchema.safeParse(options.body);
+            if (headers.get('Content-Type')?.includes('application/json') || !raw.success)
+                init.body = JSON.stringify(options.body);
+            else
+                init.body = raw.data;
+        }
+        const shouldLog = this.debug;
+        if (shouldLog) {
+            logger.info('Request', {
+                target: loggableTarget(url),
+                method: options.method,
+                headerNames: [...headers.keys()]
+            });
+        }
+        try {
+            const response = await this.fetchImpl(url.toString(), init);
+            if (shouldLog) {
+                logger.info('Response', {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headerNames: [...response.headers.keys()]
+                });
+            }
+            if (!response.ok)
+                throw await this.createError(response, options);
+            // SAFETY: T is the response type the caller declared for this path. This transport
+            // does not validate bodies (generic erasure at the HTTP boundary); a caller that needs
+            // validation parses the result, as BaseAPIClient does with its schema option.
+            return (await this.readBody(response));
+        }
+        catch (error) {
+            if (this.debug) {
+                logger.error('Request failed', {
+                    target: loggableTarget(url),
+                    method: options.method,
+                    errorName: error instanceof Error ? error.name : undefined
+                });
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new ClientError('Request timeout', 408, undefined, options);
+            }
+            throw error;
+        }
+    }
+    async readBody(response) {
+        if (response.status === 204 || response.headers.get('Content-Length') === '0')
+            return undefined;
+        const contentType = response.headers.get('Content-Type');
+        if (contentType?.includes('application/json'))
+            return response.json();
+        return response.text();
+    }
+    buildUrl(options) {
+        let path = options.path;
+        if (options.params) {
+            for (const [key, value] of Object.entries(options.params)) {
+                path = path.replace(`{${key}}`, encodeURIComponent(String(value)));
+            }
+        }
+        const url = new URL(path, this.baseUrl);
+        if (options.query) {
+            for (const [key, value] of Object.entries(options.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;
+    }
+    async buildHeaders(options) {
+        const headers = new Headers(options.headers);
+        if (!headers.has('Content-Type') && options.body !== undefined)
+            headers.set('Content-Type', 'application/json');
+        if (!headers.has('Accept'))
+            headers.set('Accept', 'application/json');
+        if (this.auth.type !== 'none') {
+            const token = this.auth.credentials || (await this.auth.tokenProvider?.());
+            if (token) {
+                switch (this.auth.type) {
+                    case 'apiKey':
+                    case 'bearer':
+                        headers.set('Authorization', `Bearer ${token}`);
+                        break;
+                    case 'session':
+                        headers.set('Cookie', `session=${token}`);
+                        break;
+                }
+            }
+        }
+        return headers;
+    }
+    createAbortSignal(timeout) {
+        return AbortSignal.timeout(timeout);
+    }
+    async createError(response, request) {
+        const statusLine = `${response.status} ${response.statusText}`;
+        const read = await settle(async () => {
+            const contentType = response.headers.get('Content-Type');
+            if (contentType?.includes('application/json')) {
+                const body = await response.json();
+                return jsonErrorMessage(body) ?? statusLine;
+            }
+            const text = await response.text();
+            return text || statusLine;
+        });
+        if (!read.ok) {
+            // The parse error can quote the body it failed on, so only its class is reported.
+            logger.warn('unparseable error body; status line stays the message', {
+                failureClass: read.error instanceof Error ? read.error.name : 'unknown failure'
+            });
+        }
+        return new ClientError(read.ok ? read.value : statusLine, response.status, response, request);
+    }
+}

package/dist/lib/client/internal/sse-stream.d.ts

@@ -0,0 +1,23 @@
+import { type AuthConfig, type RequestBodyInput } from '../types.js';
+import type { FetchFunction } from './wrap-fetch.js';
+export interface SSEEvent<T = unknown> {
+    event?: string;
+    data: T;
+    id?: string;
+    retry?: number;
+}
+export type SSEStreamOptions = {
+    method?: string;
+    params?: Record<string, string | number | boolean>;
+    query?: Record<string, string | number | boolean | string[] | undefined>;
+    body?: RequestBodyInput;
+    headers?: Record<string, string>;
+    timeout?: number;
+};
+export declare function streamSSE<T = unknown>(args: {
+    baseUrl: string;
+    auth: AuthConfig;
+    fetchImpl: FetchFunction;
+    path: string;
+    options?: SSEStreamOptions;
+}): AsyncIterableIterator<SSEEvent<T>>;