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

package/dist/lib/server/api/response.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Standardized API response formats for consistency across all endpoints
+ *
+ * This module provides SvelteKit-specific response helpers that build on top of
+ * the shared API types from the shared API type owner.
+ */
+import { type HttpError } from '@sveltejs/kit';
+import type { ValidationError } from '../../types/errors';
+/** A value that survives JSON serialisation: what may cross the wire in meta and stream events. */
+export type ResponseJsonValue = string | number | boolean | null | ResponseJsonValue[] | {
+    [key: string]: ResponseJsonValue;
+};
+export interface ResponseMeta {
+    pagination?: PaginationMeta;
+    timestamp?: string;
+    [key: string]: ResponseJsonValue | PaginationMeta | undefined;
+}
+export interface PaginationMeta {
+    page: number;
+    totalPages: number;
+    total: number;
+    pageSize: number;
+    hasNext?: boolean;
+    hasPrev?: boolean;
+}
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    message?: string;
+    code?: string;
+    errors?: ValidationError[];
+    meta?: ResponseMeta;
+}
+export type { ValidationError } from '../../types/errors';
+/**
+ * Create a standardized success response
+ */
+export declare function createSuccessResponse<T>(data: T, meta?: ResponseMeta, status?: number): Response;
+/**
+ * Create a standardized error response
+ */
+export declare function createErrorResponse(message: string, code?: string, status?: number, errors?: ValidationError[]): Response;
+/**
+ * Create a paginated response with standardized pagination metadata
+ */
+export declare function createPaginatedResponse<T>(items: T[], pagination: PaginationMeta, status?: number): Response;
+/**
+ * Create validation error response
+ */
+export declare function createValidationErrorResponse(errors: ValidationError[], message?: string): Response;
+/**
+ * Create not found error response
+ */
+export declare function createNotFoundResponse(resource?: string, id?: string): Response;
+/**
+ * Create unauthorized error response
+ */
+export declare function createUnauthorizedResponse(message?: string): Response;
+/**
+ * Create forbidden error response
+ */
+export declare function createForbiddenResponse(message?: string): Response;
+/**
+ * Create server error response
+ */
+export declare function createServerErrorResponse(message?: string, code?: string): Response;
+/**
+ * Convert SvelteKit HttpError to standardized response
+ */
+export declare function fromHttpError(error: HttpError): Response;
+/**
+ * Stream event for streaming responses
+ */
+export interface StreamEvent {
+    type: 'start' | 'chunk' | 'error' | 'done';
+    content?: string;
+    error?: string;
+    metadata?: Record<string, ResponseJsonValue>;
+}
+export interface StreamingResponse {
+    stream: ReadableStream;
+    response: Response;
+    sendEvent: (event: StreamEvent) => void;
+    close: () => void;
+}
+/**
+ * Handle streaming responses for AI endpoints
+ */
+export declare function createStreamingResponse(): StreamingResponse;
+/**
+ * Wrap async handlers with standardized error handling
+ */
+export declare function withErrorHandling<T extends unknown[]>(handler: (...args: T) => Promise<Response>): (...args: T) => Promise<Response>;
+/**
+ * Response format migration utility for existing endpoints
+ */
+export declare function migrateResponse<TResponse>(oldResponse: TResponse): Response;

package/dist/lib/server/api/response.js

@@ -0,0 +1,253 @@
+/**
+ * Standardized API response formats for consistency across all endpoints
+ *
+ * This module provides SvelteKit-specific response helpers that build on top of
+ * the shared API types from the shared API type owner.
+ */
+import { isRedirect, json } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { failureClass } from '../../failure-class';
+import { kitLogger } from '../../kit-logger';
+import { settle, settleNow } from './settled';
+const logger = kitLogger('api-response');
+/**
+ * Create a standardized success response
+ */
+export function createSuccessResponse(data, meta, status = 200) {
+    const response = {
+        success: true,
+        data,
+        ...(meta && { meta: { ...meta, timestamp: new Date().toISOString() } })
+    };
+    return json(response, { status });
+}
+/**
+ * Create a standardized error response
+ */
+export function createErrorResponse(message, code, status = 400, errors) {
+    const response = {
+        success: false,
+        message,
+        ...(code && { code }),
+        ...(errors && { errors }),
+        meta: {
+            timestamp: new Date().toISOString()
+        }
+    };
+    return json(response, { status });
+}
+/**
+ * Create a paginated response with standardized pagination metadata
+ */
+export function createPaginatedResponse(items, pagination, status = 200) {
+    const response = {
+        success: true,
+        data: items,
+        meta: {
+            pagination: {
+                ...pagination,
+                hasNext: pagination.page < pagination.totalPages,
+                hasPrev: pagination.page > 1
+            },
+            timestamp: new Date().toISOString()
+        }
+    };
+    return json(response, { status });
+}
+/**
+ * Create validation error response
+ */
+export function createValidationErrorResponse(errors, message = 'Validation failed') {
+    return createErrorResponse(message, 'VALIDATION_ERROR', 400, errors);
+}
+/**
+ * Create not found error response
+ */
+export function createNotFoundResponse(resource = 'Resource', id) {
+    const message = id ? `${resource} with ID '${id}' not found` : `${resource} not found`;
+    return createErrorResponse(message, 'NOT_FOUND', 404);
+}
+/**
+ * Create unauthorized error response
+ */
+export function createUnauthorizedResponse(message = 'Authentication required') {
+    return createErrorResponse(message, 'UNAUTHORIZED', 401);
+}
+/**
+ * Create forbidden error response
+ */
+export function createForbiddenResponse(message = 'Access denied') {
+    return createErrorResponse(message, 'FORBIDDEN', 403);
+}
+/**
+ * Create server error response
+ */
+export function createServerErrorResponse(message = 'Internal server error', code = 'INTERNAL_ERROR') {
+    return createErrorResponse(message, code, 500);
+}
+/**
+ * Convert SvelteKit HttpError to standardized response
+ */
+export function fromHttpError(error) {
+    return responseForStatus(error.status, error.body?.message);
+}
+const HTTP_ERROR_CODES = new Map([
+    [400, 'BAD_REQUEST'],
+    [401, 'UNAUTHORIZED'],
+    [403, 'FORBIDDEN'],
+    [404, 'NOT_FOUND'],
+    [409, 'CONFLICT'],
+    [422, 'UNPROCESSABLE_ENTITY'],
+    [429, 'RATE_LIMITED'],
+    [500, 'INTERNAL_ERROR'],
+    [502, 'BAD_GATEWAY'],
+    [503, 'SERVICE_UNAVAILABLE']
+]);
+function responseForStatus(status, message) {
+    return createErrorResponse(message || 'An error occurred', HTTP_ERROR_CODES.get(status) || 'UNKNOWN_ERROR', status);
+}
+/**
+ * Handle streaming responses for AI endpoints
+ */
+export function createStreamingResponse() {
+    const encoder = new TextEncoder();
+    let controller;
+    const stream = new ReadableStream({
+        start(ctrl) {
+            controller = ctrl;
+        }
+    });
+    // Same-origin SSE by default — never hardcode ACAO:* (credentialed stream risk).
+    // Apps that need CORS set an allowlisted Origin via their own CORS handle.
+    const response = new Response(stream, {
+        headers: {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive'
+        }
+    });
+    const sendEvent = (event) => {
+        const data = JSON.stringify(event);
+        controller.enqueue(encoder.encode(`data: ${data}\n\n`));
+    };
+    const close = () => {
+        sendEvent({ type: 'done' });
+        controller.close();
+    };
+    return { stream, response, sendEvent, close };
+}
+/**
+ * What a thrown value must look like to be answered as an HTTP error: a usable
+ * response status and, optionally, a body carrying the message to show.
+ */
+const httpErrorSchema = z.looseObject({
+    status: z.number().int().min(200).max(599),
+    body: z.looseObject({ message: z.string().optional() }).optional().catch(undefined)
+});
+/** A Zod validation failure, recognised by name so another copy of Zod still matches. */
+const zodFailureSchema = z.looseObject({
+    name: z.literal('ZodError'),
+    issues: z
+        .array(z.object({
+        path: z.array(z.union([z.string(), z.number(), z.symbol()])),
+        message: z.string(),
+        code: z.string()
+    }))
+        .optional()
+        .catch(undefined)
+});
+/**
+ * Choose the response for a thrown value. Inspecting an arbitrary thrown value
+ * can itself throw (getters, proxies); that must never replace the response.
+ */
+function classifyFailure(failure) {
+    const inspected = settleNow(() => inspectFailure(failure));
+    if (!inspected.ok) {
+        reportFailureClass('API error could not be inspected; answering with the generic failure', inspected.error);
+        return createServerErrorResponse('An unexpected error occurred');
+    }
+    return inspected.value;
+}
+function inspectFailure(failure) {
+    const httpError = httpErrorSchema.safeParse(failure);
+    if (httpError.success) {
+        return responseForStatus(httpError.data.status, httpError.data.body?.message);
+    }
+    if (failure instanceof Error) {
+        const zodFailure = zodFailureSchema.safeParse(failure);
+        if (zodFailure.success) {
+            const validationErrors = (zodFailure.data.issues ?? []).map((issue) => ({
+                field: issue.path.map(String).join('.'),
+                message: issue.message,
+                code: issue.code
+            }));
+            return createValidationErrorResponse(validationErrors);
+        }
+        // A plain Error's message is internal detail: the body states only fixed facts.
+        return createServerErrorResponse();
+    }
+    return createServerErrorResponse('An unexpected error occurred');
+}
+/**
+ * A thrown SvelteKit `redirect()` is control flow, not a failure: answer it as the
+ * redirect it is. Returns undefined for anything else (including a value that
+ * cannot be inspected).
+ */
+function redirectResponse(failure) {
+    const redirect = settleNow(() => isRedirect(failure)
+        ? new Response(null, { status: failure.status, headers: { Location: failure.location } })
+        : undefined);
+    if (!redirect.ok) {
+        reportFailureClass('API error could not be inspected for a redirect', redirect.error);
+        return undefined;
+    }
+    return redirect.value;
+}
+/**
+ * Record only the failure class. The logger itself is untrusted at this error
+ * boundary: if it throws, the fixed response still wins.
+ */
+function reportFailureClass(message, failure) {
+    void settleNow(() => logger.warn(message, { reason: failureClass(failure) }));
+}
+/**
+ * Wrap async handlers with standardized error handling
+ */
+export function withErrorHandling(handler) {
+    return async (...args) => {
+        const settled = await settle(() => handler(...args));
+        if (settled.ok)
+            return settled.value;
+        const thrown = settled.error;
+        const redirected = redirectResponse(thrown);
+        if (redirected)
+            return redirected;
+        const response = classifyFailure(thrown);
+        reportFailureClass('API request failed', thrown);
+        return response;
+    };
+}
+/** Any object (arrays are handled before this is asked). */
+const objectSchema = z.looseObject({});
+/** A body already in the standard `{ success, data }` envelope. */
+const standardEnvelopeSchema = z.looseObject({ success: z.unknown(), data: z.unknown() });
+/**
+ * Response format migration utility for existing endpoints
+ */
+export function migrateResponse(oldResponse) {
+    // Handle existing bare responses
+    if (Array.isArray(oldResponse)) {
+        return createSuccessResponse(oldResponse);
+    }
+    // Handle existing object responses without standard format
+    if (objectSchema.safeParse(oldResponse).success) {
+        // Check if already in new format
+        if (standardEnvelopeSchema.safeParse(oldResponse).success) {
+            return json(oldResponse);
+        }
+        // Migrate old format
+        return createSuccessResponse(oldResponse);
+    }
+    // Handle primitives
+    return createSuccessResponse(oldResponse);
+}

package/dist/lib/server/api/settled.d.ts

@@ -0,0 +1,8 @@
+/**
+ * API-local projection of kit's one failure-as-value contract.
+ *
+ * Keeping the projection beside the API code makes its custody explicit while
+ * preserving the canonical `{ ok, value | error }` shape and implementation.
+ */
+export { settle, settleNow } from '../../attempt.js';
+export type { RecordedFailure, Settled } from '../../attempt.js';

package/dist/lib/server/api/settled.js

@@ -0,0 +1,7 @@
+/**
+ * API-local projection of kit's one failure-as-value contract.
+ *
+ * Keeping the projection beside the API code makes its custody explicit while
+ * preserving the canonical `{ ok, value | error }` shape and implementation.
+ */
+export { settle, settleNow } from '../../attempt.js';

package/dist/lib/server/api/static-spec.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Build-time OpenAPI spec exporter.
+ *
+ * Allows apps to generate their OpenAPI spec at build time rather than relying
+ * solely on dynamic runtime evaluation in SvelteKit serverless/edge environments.
+ *
+ * Kit has no filesystem of its own: the host supplies one through the small
+ * structural port below (the runtime filesystem adapter is assignable to it).
+ */
+import type { GenerateSpecOptions, OpenAPIRegistry } from './openapi-registry.js';
+/** The two filesystem operations the exporter needs. */
+export interface SpecFileSystem {
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    writeFile(path: string, data: string): Promise<void>;
+}
+export interface ExportSpecOptions extends GenerateSpecOptions {
+    outputPath: string;
+    registry?: OpenAPIRegistry;
+}
+export interface WriteSpecOptions extends ExportSpecOptions {
+    /** Host-supplied filesystem; kit has no default. */
+    fileSystem: SpecFileSystem;
+}
+/**
+ * Generate the OpenAPI spec and write it as JSON through the host's filesystem.
+ */
+export declare function writeOpenApiSpec(options: WriteSpecOptions): Promise<void>;
+/**
+ * The synchronous exporter wrote through node's filesystem, which kit no longer
+ * touches. It stays exported so imports keep resolving, but it refuses: use
+ * `writeOpenApiSpec` with a host-supplied filesystem.
+ */
+export declare function exportOpenApiSpec(_options: ExportSpecOptions): void;

package/dist/lib/server/api/static-spec.js

@@ -0,0 +1,43 @@
+/**
+ * Build-time OpenAPI spec exporter.
+ *
+ * Allows apps to generate their OpenAPI spec at build time rather than relying
+ * solely on dynamic runtime evaluation in SvelteKit serverless/edge environments.
+ *
+ * Kit has no filesystem of its own: the host supplies one through the small
+ * structural port below (the runtime filesystem adapter is assignable to it).
+ */
+import { defaultOpenAPIRegistry } from './openapi-registry.js';
+import { kitLogger } from '../../kit-logger';
+const logger = kitLogger('static-spec');
+/** The directory part of a `/` or `\` separated path ('' when there is none). */
+function parentDirectory(path) {
+    const normalised = path.replace(/\\/g, '/');
+    const cut = normalised.lastIndexOf('/');
+    if (cut < 0)
+        return '';
+    return cut === 0 ? '/' : normalised.slice(0, cut);
+}
+/**
+ * Generate the OpenAPI spec and write it as JSON through the host's filesystem.
+ */
+export async function writeOpenApiSpec(options) {
+    const { outputPath, registry = defaultOpenAPIRegistry(), fileSystem, ...specOptions } = options;
+    const spec = registry.generateSpec(specOptions);
+    const targetDir = parentDirectory(outputPath);
+    if (targetDir)
+        await fileSystem.mkdir(targetDir, { recursive: true });
+    await fileSystem.writeFile(outputPath, JSON.stringify(spec, null, 2));
+    logger.info('Wrote static OpenAPI spec', {
+        path: outputPath,
+        pathsCount: Object.keys(spec.paths).length
+    });
+}
+/**
+ * The synchronous exporter wrote through node's filesystem, which kit no longer
+ * touches. It stays exported so imports keep resolving, but it refuses: use
+ * `writeOpenApiSpec` with a host-supplied filesystem.
+ */
+export function exportOpenApiSpec(_options) {
+    throw new Error('exportOpenApiSpec needs a filesystem and kit has none: call writeOpenApiSpec({ ...options, fileSystem }) with the host filesystem');
+}

package/dist/lib/server/api/versioning.d.ts

@@ -0,0 +1,92 @@
+import type { RequestEvent } from '@sveltejs/kit';
+/**
+ * API Versioning Strategy for Vibes
+ *
+ * Supports multiple versioning methods:
+ * 1. URL path versioning: /api/v1/endpoint
+ * 2. Header versioning: Accept: application/vnd.vibes.v1+json
+ * 3. Query parameter: ?version=1
+ */
+export declare const CURRENT_VERSION = "1.0.0";
+export declare const SUPPORTED_VERSIONS: string[];
+export declare const DEFAULT_VERSION = "1.0.0";
+export interface ApiVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    string: string;
+}
+export interface VersionedEndpoint {
+    version: ApiVersion;
+    handler: (event: RequestEvent) => Promise<Response>;
+    deprecated?: boolean;
+    deprecationDate?: Date;
+    sunsetDate?: Date;
+}
+/**
+ * Parse version string into structured format
+ */
+export declare function parseVersion(versionString: string): ApiVersion;
+/**
+ * Compare two API versions
+ */
+export declare function compareVersions(a: ApiVersion, b: ApiVersion): number;
+/**
+ * Check if version is supported
+ */
+export declare function isVersionSupported(version: string): boolean;
+/**
+ * Extract API version from request
+ */
+export declare function extractVersion(event: RequestEvent): ApiVersion;
+/**
+ * Middleware to handle API versioning
+ */
+export declare function withVersioning(endpoints: Map<string, VersionedEndpoint[]>): (event: RequestEvent) => Promise<Response>;
+/**
+ * Create versioned endpoint registration
+ */
+export declare function createVersionedEndpoint(version: string, handler: (event: RequestEvent) => Promise<Response>, options?: {
+    deprecated?: boolean;
+    deprecationDate?: Date;
+    sunsetDate?: Date;
+}): VersionedEndpoint;
+/**
+ * Migration utilities for version upgrades
+ */
+export declare class VersionMigrator<TFrom = unknown, TTo = TFrom> {
+    private migrations;
+    /**
+     * Register a migration function for version transition
+     */
+    registerMigration(fromVersion: string, toVersion: string, migrator: (data: TFrom) => TTo): void;
+    /**
+     * Migrate data from one version to another
+     */
+    migrate(data: TFrom, fromVersion: string, toVersion: string): TTo;
+    /**
+     * Auto-migrate through multiple versions if needed
+     */
+    autoMigrate(data: TFrom, fromVersion: string, toVersion: string): TFrom | TTo;
+}
+/**
+ * Create the global version migrator instance
+ */
+export declare const globalMigrator: VersionMigrator<unknown, unknown>;
+export interface VersionInfo {
+    current: string;
+    supported: string[];
+    deprecated: string[];
+}
+/**
+ * Utility to get version info for documentation
+ */
+export declare function getVersionInfo(): VersionInfo;
+export interface ContentNegotiation {
+    type: 'json' | 'xml' | 'yaml';
+    version?: string;
+}
+/**
+ * Content negotiation helper
+ */
+export declare function negotiateContentType(acceptHeader: string | null): ContentNegotiation;