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

package/dist/lib/client/internal/sse-stream.js

@@ -0,0 +1,127 @@
+import { ClientError } from '../types.js';
+import { settleNow } from '../../attempt';
+import { kitLogger } from '../../kit-logger';
+const logger = kitLogger('sse-stream');
+export async function* streamSSE(args) {
+    const options = args.options ?? {};
+    let url = `${args.baseUrl}${args.path}`;
+    if (options.params) {
+        for (const [key, value] of Object.entries(options.params)) {
+            url = url.replace(`:${key}`, String(value));
+            url = url.replace(`{${key}}`, String(value));
+        }
+    }
+    if (options.query) {
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(options.query)) {
+            if (value === undefined || value === null)
+                continue;
+            if (Array.isArray(value))
+                value.forEach((v) => searchParams.append(key, String(v)));
+            else
+                searchParams.append(key, String(value));
+        }
+        const queryString = searchParams.toString();
+        if (queryString)
+            url += `?${queryString}`;
+    }
+    const headers = new Headers({ Accept: 'text/event-stream', ...options.headers });
+    if (!headers.has('Content-Type'))
+        headers.set('Content-Type', 'application/json');
+    if (args.auth.type === 'apiKey' && args.auth.credentials) {
+        headers.set('X-API-Key', args.auth.credentials);
+    }
+    else if (args.auth.type === 'bearer') {
+        const token = args.auth.tokenProvider ? await args.auth.tokenProvider() : args.auth.credentials;
+        if (token)
+            headers.set('Authorization', `Bearer ${token}`);
+    }
+    else if (args.auth.type === 'session') {
+        const token = args.auth.tokenProvider ? await args.auth.tokenProvider() : args.auth.credentials;
+        if (token)
+            headers.set('Cookie', `session=${token}`);
+    }
+    const requestOptions = {
+        method: options.method || 'POST',
+        path: args.path,
+        params: options.params,
+        query: options.query,
+        body: options.body,
+        headers: options.headers,
+        timeout: options.timeout
+    };
+    const requestInit = {
+        method: requestOptions.method,
+        headers
+    };
+    if (requestOptions.timeout) {
+        requestInit.signal = AbortSignal.timeout(requestOptions.timeout);
+    }
+    if (options.body !== undefined)
+        requestInit.body = JSON.stringify(options.body);
+    const response = await args.fetchImpl(url, requestInit);
+    if (!response.ok) {
+        throw new ClientError(`SSE stream failed: ${response.statusText}`, response.status, response, requestOptions);
+    }
+    if (!response.body) {
+        throw new ClientError('No response body for SSE stream', response.status, response, requestOptions);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || '';
+            let currentEvent = {};
+            for (const line of lines) {
+                if (line.trim() === '') {
+                    if (currentEvent.data !== undefined) {
+                        // SAFETY: `data` is defined (checked above), the one required field of SSEEvent.
+                        yield currentEvent;
+                        currentEvent = {};
+                    }
+                    continue;
+                }
+                if (line.startsWith('event:')) {
+                    currentEvent.event = line.slice(6).trim();
+                    continue;
+                }
+                if (line.startsWith('data:')) {
+                    const dataStr = line.slice(5).trim();
+                    if (dataStr === '[DONE]')
+                        return;
+                    const parsedData = settleNow(() => JSON.parse(dataStr));
+                    if (parsedData.ok) {
+                        // `T` is the event data type the caller declared for this stream (generic
+                        // erasure at the wire boundary); this transport does not validate it.
+                        currentEvent.data = parsedData.value;
+                    }
+                    else {
+                        logger.debug('SSE data is not JSON; forwarding raw string', {
+                            error: parsedData.error instanceof Error ? parsedData.error.name : 'unknown failure'
+                        });
+                        // SAFETY: a line that is not JSON is forwarded as its raw string; a caller that
+                        // declares a non-string `T` must expect strings from such lines.
+                        currentEvent.data = dataStr;
+                    }
+                    continue;
+                }
+                if (line.startsWith('id:')) {
+                    currentEvent.id = line.slice(3).trim();
+                    continue;
+                }
+                if (line.startsWith('retry:')) {
+                    currentEvent.retry = parseInt(line.slice(6).trim());
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/lib/client/internal/vibes-client.d.ts

@@ -0,0 +1,37 @@
+import type { AuthConfig, ClientConfig, RequestBodyInput, RequestOptions } from '../types.js';
+import { type OpenAPISpec } from './generator.js';
+import { type SSEEvent, type SSEStreamOptions } from './sse-stream.js';
+export declare class VibesClient {
+    private config;
+    private requestBuilder;
+    private apiGenerator;
+    private apis;
+    private specPromise;
+    constructor(config: ClientConfig);
+    private initialize;
+    getOpenAPISpec(): Promise<OpenAPISpec>;
+    private fetchOpenAPISpec;
+    private buildAPIs;
+    request<T = unknown>(path: string, options?: {
+        method?: string;
+        params?: Record<string, string | number | boolean>;
+        query?: Record<string, string | number | boolean | string[] | undefined>;
+        body?: RequestBodyInput;
+        headers?: Record<string, string>;
+        timeout?: number;
+    }): Promise<T>;
+    setAuth(auth: AuthConfig): void;
+    /**
+     * Rebuilds the resource APIs on the new request builder once the spec load settles. This
+     * continuation owns its own failure: the caller of `getOpenAPISpec()` sees the rejection,
+     * and nothing else is left holding an unobserved rejected promise.
+     */
+    private rebuildAPIsFrom;
+    getResources(): string[];
+    hasResource(name: string): boolean;
+    get<T = unknown>(endpoint: string, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(endpoint: string, body?: RequestBodyInput, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(endpoint: string, body?: RequestBodyInput, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(endpoint: string, options?: RequestOptions): Promise<T>;
+    stream<T = unknown>(path: string, options?: SSEStreamOptions): AsyncIterableIterator<SSEEvent<T>>;
+}

package/dist/lib/client/internal/vibes-client.js

@@ -0,0 +1,137 @@
+import { settle } from '../../attempt.js';
+import { kitLogger } from '../../kit-logger.js';
+import { ClientConfigError } from '../types.js';
+import { APIGenerator } from './generator.js';
+import { RequestBuilder } from './request-builder.js';
+import { streamSSE } from './sse-stream.js';
+import { createHookedFetch, globalFetch } from './wrap-fetch.js';
+const logger = kitLogger('client');
+export class VibesClient {
+    config;
+    requestBuilder;
+    apiGenerator;
+    apis = {};
+    specPromise = null;
+    constructor(config) {
+        const baseUrl = config?.baseUrl;
+        if (!baseUrl)
+            throw new ClientConfigError('VibesClient requires an explicit baseUrl; the client guesses no default host.');
+        const fetchImpl = config.fetch || globalFetch();
+        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,
+            hooks,
+            timeout: config.timeout || 30000,
+            debug: config.debug || false,
+            warnOnOasMismatch: config.warnOnOasMismatch || false
+        };
+        const hookedFetch = createHookedFetch({
+            fetchImpl: this.config.fetch,
+            hooks: this.config.hooks
+        });
+        this.requestBuilder = new RequestBuilder(this.config.baseUrl, this.config.auth, hookedFetch, this.config.timeout, this.config.debug);
+        this.apiGenerator = new APIGenerator(this.requestBuilder);
+    }
+    async initialize() {
+        const loaded = await settle(async () => {
+            const spec = await this.getOpenAPISpec();
+            this.buildAPIs(spec);
+        });
+        const shouldWarn = this.config.debug || this.config.warnOnOasMismatch;
+        if (!loaded.ok && shouldWarn) {
+            logger.warn('Failed to load OpenAPI spec, client will have limited functionality', {
+                failure: loaded.error instanceof Error ? loaded.error.message : 'unknown failure'
+            });
+        }
+    }
+    getOpenAPISpec() {
+        if (!this.specPromise)
+            this.specPromise = this.fetchOpenAPISpec();
+        return this.specPromise;
+    }
+    async fetchOpenAPISpec() {
+        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();
+    }
+    buildAPIs(spec) {
+        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(path, options = {}) {
+        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) {
+        this.config.auth = auth;
+        const hookedFetch = createHookedFetch({
+            fetchImpl: this.config.fetch,
+            hooks: this.config.hooks
+        });
+        this.requestBuilder = new RequestBuilder(this.config.baseUrl, auth, hookedFetch, this.config.timeout, this.config.debug);
+        this.apiGenerator = new APIGenerator(this.requestBuilder);
+        if (this.specPromise)
+            void this.rebuildAPIsFrom(this.specPromise);
+    }
+    /**
+     * Rebuilds the resource APIs on the new request builder once the spec load settles. This
+     * continuation owns its own failure: the caller of `getOpenAPISpec()` sees the rejection,
+     * and nothing else is left holding an unobserved rejected promise.
+     */
+    async rebuildAPIsFrom(pending) {
+        const rebuilt = await settle(async () => {
+            this.buildAPIs(await pending);
+        });
+        if (!rebuilt.ok && (this.config.debug || this.config.warnOnOasMismatch)) {
+            logger.warn('Failed to rebuild resource APIs after setAuth, client keeps limited functionality', {
+                failure: rebuilt.error instanceof Error ? rebuilt.error.message : 'unknown failure'
+            });
+        }
+    }
+    getResources() {
+        return Object.keys(this.apis);
+    }
+    hasResource(name) {
+        return name in this.apis;
+    }
+    get(endpoint, options) {
+        return this.request(endpoint, { ...options, method: 'GET' });
+    }
+    post(endpoint, body, options) {
+        return this.request(endpoint, { ...options, method: 'POST', body });
+    }
+    put(endpoint, body, options) {
+        return this.request(endpoint, { ...options, method: 'PUT', body });
+    }
+    delete(endpoint, options) {
+        return this.request(endpoint, { ...options, method: 'DELETE' });
+    }
+    async *stream(path, options = {}) {
+        yield* streamSSE({
+            baseUrl: this.config.baseUrl,
+            auth: this.config.auth,
+            fetchImpl: this.config.fetch,
+            path,
+            options
+        });
+    }
+}

package/dist/lib/client/internal/wrap-fetch.d.ts

@@ -0,0 +1,13 @@
+import { type ClientHooks } from '../types.js';
+/** The part of `fetch` the client relies on (a fetch with extra statics is assignable to it). */
+export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * The runtime's global `fetch` as a client fetch, or undefined when the runtime
+ * has none. The call goes through `globalThis.fetch` each time, so the global is
+ * never detached from its receiver.
+ */
+export declare function globalFetch(): FetchFunction | undefined;
+export declare function createHookedFetch(args: {
+    fetchImpl: FetchFunction;
+    hooks: ClientHooks;
+}): FetchFunction;

package/dist/lib/client/internal/wrap-fetch.js

@@ -0,0 +1,51 @@
+import { ClientError } from '../types.js';
+/**
+ * The runtime's global `fetch` as a client fetch, or undefined when the runtime
+ * has none. The call goes through `globalThis.fetch` each time, so the global is
+ * never detached from its receiver.
+ */
+export function globalFetch() {
+    return globalThis.fetch ? (input, init) => globalThis.fetch(input, init) : undefined;
+}
+/** Report a failed transport call to the host's onError hook, without the request or its credentials. */
+async function reportNetworkFailure(hooks, message) {
+    if (!hooks.onError)
+        return;
+    await hooks.onError(new ClientError(message, 0, undefined, undefined));
+}
+export function createHookedFetch(args) {
+    return async (input, init) => {
+        let response;
+        if (!args.hooks.beforeRequest) {
+            try {
+                response = await args.fetchImpl(input, init);
+            }
+            catch (error) {
+                await reportNetworkFailure(args.hooks, error instanceof Error ? error.message : 'Network error');
+                throw error;
+            }
+        }
+        else {
+            const originalRequest = new Request(input, init);
+            const returned = await args.hooks.beforeRequest(originalRequest);
+            // The Request the hook returned is what is sent: its URL, method, headers and body are
+            // authoritative. The caller's own cancellation/timeout stays attached when the hook built
+            // a fresh Request that does not carry it.
+            const outgoing = returned === originalRequest
+                ? returned
+                : new Request(returned, {
+                    signal: AbortSignal.any([returned.signal, originalRequest.signal])
+                });
+            try {
+                response = await args.fetchImpl(outgoing);
+            }
+            catch (error) {
+                await reportNetworkFailure(args.hooks, error instanceof Error ? error.message : 'Network error');
+                throw error;
+            }
+        }
+        if (args.hooks.afterResponse)
+            response = await args.hooks.afterResponse(response);
+        return response;
+    };
+}

package/dist/lib/client/layout/mount.d.ts

@@ -0,0 +1,13 @@
+/**
+ * VibesKit client-side layout mount helper.
+ * Sets page metadata (title, description) on mount.
+ *
+ * NOTE: Feature gating is handled server-side via vibesLayoutFeature().
+ * This function should ONLY be used for setting meta tags.
+ */
+export declare function vibesLayoutMount(options: {
+    title?: string;
+    titleSuffix?: string;
+    description?: string;
+}): void;
+export declare const vibesLayoutInit: typeof vibesLayoutMount;

package/dist/lib/client/layout/mount.js

@@ -0,0 +1,26 @@
+/**
+ * VibesKit client-side layout mount helper.
+ * Sets page metadata (title, description) on mount.
+ *
+ * NOTE: Feature gating is handled server-side via vibesLayoutFeature().
+ * This function should ONLY be used for setting meta tags.
+ */
+export function vibesLayoutMount(options) {
+    // Set title
+    if (options.title) {
+        const suffix = options.titleSuffix ? ` ${options.titleSuffix}` : '';
+        document.title = `${options.title}${suffix}`;
+    }
+    // Set description meta tag
+    if (options.description) {
+        let meta = document.querySelector('meta[name="description"]');
+        if (!meta) {
+            meta = document.createElement('meta');
+            meta.setAttribute('name', 'description');
+            document.head.appendChild(meta);
+        }
+        meta.setAttribute('content', options.description);
+    }
+}
+// Alias for semantics
+export const vibesLayoutInit = vibesLayoutMount;

package/dist/lib/client/node.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Kit Node.js client factory.
+ */
+export { createHttp2Fetch } from './internal/node/http2-fetch.node';
+import { VibesClient } from './internal/vibes-client';
+import type { ClientConfig } from './types';
+export declare function createCLIClient(config: ClientConfig): VibesClient;

package/dist/lib/client/node.js

@@ -0,0 +1,8 @@
+/**
+ * Kit Node.js client factory.
+ */
+export { createHttp2Fetch } from './internal/node/http2-fetch.node';
+import { VibesClient } from './internal/vibes-client';
+export function createCLIClient(config) {
+    return new VibesClient(config);
+}

package/dist/lib/client/page/enhance.d.ts

@@ -0,0 +1,6 @@
+import type { PageGateOptions } from '../schemas/gate.ts';
+export declare function vibesPage(options: PageGateOptions): {
+    enhanceHook: ({ cancel }: {
+        cancel: () => void;
+    }) => () => Promise<void>;
+};

package/dist/lib/client/page/enhance.js

@@ -0,0 +1,22 @@
+import { preflightQuota } from "../guard/gate.js";
+export function vibesPage(options) {
+    async function beforeSubmit() {
+        if (!options.quota)
+            return true;
+        const { feature, amount = 1, accountOrigin, endpoint, failOpen } = options.quota;
+        const status = await preflightQuota(feature, amount, { accountOrigin, endpoint, failOpen });
+        if (!status.allowed) {
+            options.onBlocked?.(status);
+            return false;
+        }
+        return true;
+    }
+    function enhanceHook({ cancel }) {
+        return async () => {
+            const ok = await beforeSubmit();
+            if (!ok)
+                cancel();
+        };
+    }
+    return { enhanceHook };
+}

package/dist/lib/client/schemas/gate.d.ts

@@ -0,0 +1,31 @@
+export type QuotaSpec = {
+    feature: string;
+    amount?: number;
+    accountOrigin?: string | null;
+    endpoint?: string;
+    failOpen?: boolean;
+};
+export type QuotaBlockReason = 'quota' | 'unavailable';
+export type QuotaStatus = {
+    allowed: boolean;
+    feature: string;
+    requested: number;
+    usage: number;
+    limit: number | null;
+    remaining: number | null;
+    reason?: QuotaBlockReason;
+    status?: number;
+    accountOrigin: string;
+};
+export type GateOptions = {
+    quota?: QuotaSpec;
+    failOpen?: boolean;
+    showCreditsOnQuotaBlocked?: boolean;
+    onShowCredits?: (quotaFeature: string) => void;
+    onBlocked?: (status: QuotaStatus) => void;
+    onError?: (error: Error) => void;
+};
+export type PageGateOptions = {
+    quota?: QuotaSpec;
+    onBlocked?: (status: QuotaStatus) => void;
+};

package/dist/lib/client/schemas/gate.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/client/services/permissions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Client-side permission utilities
+ *
+ * Provides permission checking functions that work with user data from the API.
+ * These functions work with the enhanced user data that includes roles and permissions.
+ */
+export interface ClientUser {
+    id: string;
+    email: string;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+    isSuperuser?: boolean;
+    isSuperUser?: boolean;
+    staff?: boolean;
+    isStaff?: boolean;
+    roles?: Array<{
+        id: string;
+        name: string;
+        description: string | null;
+        isSystemRole: boolean;
+    }>;
+    permissions?: string[];
+}
+export declare function hasClientPermission(user: ClientUser | null, resource: string, action: string): boolean;
+export declare function hasAnyClientPermission(user: ClientUser | null, permissions: Array<{
+    resource: string;
+    action: string;
+}>): boolean;
+export declare function hasAllClientPermissions(user: ClientUser | null, permissions: Array<{
+    resource: string;
+    action: string;
+}>): boolean;
+export declare function hasClientRole(user: ClientUser | null, roleName: string): boolean;
+export declare function hasAnyClientRole(user: ClientUser | null, roleNames: string[]): boolean;
+export declare function isClientAdmin(user: ClientUser | null): boolean;
+export declare function canAccessSystem(user: ClientUser | null): boolean;
+export declare function canManageUsers(user: ClientUser | null): boolean;
+export declare function canManageProjects(user: ClientUser | null): boolean;
+export declare function canManageBilling(user: ClientUser | null): boolean;
+export declare function getUserRoleDisplay(user: ClientUser | null): string;
+export declare function canAccessOwnResource(user: ClientUser | null, resource: string, action: string, resourceOwnerId: string): boolean;

package/dist/lib/client/services/permissions.js

@@ -0,0 +1,103 @@
+/**
+ * Client-side permission utilities
+ *
+ * Provides permission checking functions that work with user data from the API.
+ * These functions work with the enhanced user data that includes roles and permissions.
+ */
+export function hasClientPermission(user, resource, action) {
+    if (!user)
+        return false;
+    if (user.isSuperuser || user.isSuperUser)
+        return true;
+    if (user.permissions) {
+        const permissionKey = `${resource}:${action}`;
+        const ownPermissionKey = `${resource}:${action}:own`;
+        return user.permissions.some((perm) => {
+            if (perm === permissionKey)
+                return true;
+            if (perm === ownPermissionKey)
+                return true;
+            if (perm === '*:*')
+                return true;
+            if (perm === `*:${action}`)
+                return true;
+            if (perm === `${resource}:*`)
+                return true;
+            return false;
+        });
+    }
+    return false;
+}
+export function hasAnyClientPermission(user, permissions) {
+    if (!user)
+        return false;
+    return permissions.some(({ resource, action }) => hasClientPermission(user, resource, action));
+}
+export function hasAllClientPermissions(user, permissions) {
+    if (!user)
+        return false;
+    return permissions.every(({ resource, action }) => hasClientPermission(user, resource, action));
+}
+export function hasClientRole(user, roleName) {
+    if (!user)
+        return false;
+    if ((user.isSuperuser || user.isSuperUser) && roleName === 'admin')
+        return true;
+    if (user.roles)
+        return user.roles.some((role) => role.name === roleName);
+    return false;
+}
+export function hasAnyClientRole(user, roleNames) {
+    if (!user)
+        return false;
+    return roleNames.some((roleName) => hasClientRole(user, roleName));
+}
+export function isClientAdmin(user) {
+    if (!user)
+        return false;
+    if (user.isSuperuser || user.isSuperUser || user.staff || user.isStaff)
+        return true;
+    if (hasAnyClientRole(user, ['admin', 'superadmin']))
+        return true;
+    if (hasClientPermission(user, '*', '*'))
+        return true;
+    return false;
+}
+export function canAccessSystem(user) {
+    return isClientAdmin(user) || hasClientPermission(user, 'system', 'read');
+}
+export function canManageUsers(user) {
+    return isClientAdmin(user) || hasClientPermission(user, 'users', 'write');
+}
+export function canManageProjects(user) {
+    return isClientAdmin(user) || hasClientPermission(user, 'projects', 'write');
+}
+export function canManageBilling(user) {
+    return isClientAdmin(user) || hasClientPermission(user, 'billing', 'write');
+}
+export function getUserRoleDisplay(user) {
+    if (!user)
+        return 'Guest';
+    if (user.isSuperuser || user.isSuperUser)
+        return 'Superuser';
+    if (user.roles && user.roles.length > 0) {
+        const priorityOrder = ['superadmin', 'admin', 'project_admin', 'developer', 'user', 'readonly'];
+        for (const priority of priorityOrder) {
+            if (user.roles.some((role) => role.name === priority)) {
+                return priority.replace('_', ' ').replace(/\b\w/g, (l) => l.toUpperCase());
+            }
+        }
+        return user.roles[0].name.replace('_', ' ').replace(/\b\w/g, (l) => l.toUpperCase());
+    }
+    return 'User';
+}
+export function canAccessOwnResource(user, resource, action, resourceOwnerId) {
+    if (!user)
+        return false;
+    if (isClientAdmin(user))
+        return true;
+    if (user.id !== resourceOwnerId)
+        return false;
+    return (hasClientPermission(user, resource, `${action}:own`) ||
+        hasClientPermission(user, resource, action));
+}