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

package/dist/lib/server/endpoint/wrapper.js

@@ -0,0 +1,971 @@
+/**
+ * Core vibeskit wrapper implementation
+ *
+ * Provides a clean, middleware-based API wrapper with:
+ * - Authentication and authorization
+ * - Rate limiting
+ * - Caching
+ * - Billing and quota management
+ * - Request validation
+ * - Performance monitoring
+ */
+import { json, error } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { DEV } from 'esm-env';
+import { SubscriptionRequiredError, QuotaExceededError, BillingServiceUnavailableError, InsufficientCreditsError } from '../../errors.js';
+import { defaultOpenAPIRegistry } from '../api/openapi-registry.js';
+import { settle, settleNow } from '../../attempt.js';
+import { errorInstance, failureAsError, guardedInstanceOf, parseGuarded, serializeError } from '../hooks/errors.js';
+import { getVibesKit } from '../../instance.js';
+import { kitLogger } from '../../kit-logger';
+import { asVibesKitLocals, requireKitRuntime } from '../locals.js';
+const _logger = kitLogger('vibeskit-endpoint');
+// Import middleware
+import { applyRateLimit, RateLimitError } from '../middleware/rate-limiter';
+import { applyCacheGet, applyCacheSet } from '../middleware/cache-manager';
+import { applyPermissionCheck, AuthenticationError, PermissionError } from '../middleware/permission-checker';
+const performanceApi = globalThis.performance ?? { now: () => Date.now() };
+const VIBES_OPENAPI_ROUTE_METADATA = Symbol.for('vibeskit.openapi.routeMetadata');
+function attachOpenApiRouteMetadata(handler, method, config) {
+    Object.defineProperty(handler, VIBES_OPENAPI_ROUTE_METADATA, {
+        value: { method: method.toUpperCase(), config },
+        enumerable: false
+    });
+    return handler;
+}
+/**
+ * The route metadata a wrapped handler carries, or nothing for an export that
+ * is not one (a module's other exports, a missing method). Pass what a route
+ * module exports under an HTTP method name; a value that is not a function
+ * carries none.
+ */
+export function getVibesOpenApiRouteMetadata(handler) {
+    return carriesRouteMetadata(handler) ? handler[VIBES_OPENAPI_ROUTE_METADATA] : undefined;
+}
+/**
+ * Callers hand over a route module's export under a method name: a missing or
+ * non-function export carries no metadata and must not throw.
+ */
+function carriesRouteMetadata(handler) {
+    return typeof handler === 'function' && Object.hasOwn(handler, VIBES_OPENAPI_ROUTE_METADATA);
+}
+function resolveDevelopmentMode(config) {
+    const developmentMode = config.developmentMode;
+    const showDetailedErrors = developmentMode?.resolveEnabled?.() ?? developmentMode?.enabled ?? DEV;
+    const showDevelopmentModeWarning = !DEV && showDetailedErrors && (developmentMode?.resolveWarningEnabled?.() ?? true);
+    return { showDetailedErrors, showDevelopmentModeWarning };
+}
+/**
+ * Generate unique request ID for tracing
+ */
+function generateRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+ * Validate request using Zod schemas
+ */
+async function validateRequest(event, validation) {
+    const validated = {};
+    const kit = getVibesKit();
+    const logger = kit.config.services?.logger;
+    const attempted = await settle(async () => {
+        // Validate body
+        if (validation.body) {
+            const body = await event.request.json();
+            validated.body = validation.body.parse(body);
+        }
+        // Validate query parameters
+        if (validation.query) {
+            const query = Object.fromEntries(event.url.searchParams);
+            // Temporary logging for debugging
+            if (event.url.pathname.includes('/docs')) {
+                logger?.info('[Validation] Query params before validation', {
+                    query,
+                    schema: JSON.stringify(validation.query)
+                });
+            }
+            validated.query = validation.query.parse(query);
+        }
+        // Validate URL parameters
+        if (validation.params) {
+            validated.params = validation.params.parse(event.params);
+        }
+        // Validate headers
+        if (validation.headers) {
+            const headers = Object.fromEntries(event.request.headers);
+            validated.headers = validation.headers.parse(headers);
+        }
+        return validated;
+    });
+    if (attempted.ok)
+        return attempted.value;
+    const failure = attempted.error;
+    if (guardedInstanceOf(failure, z.ZodError)) {
+        // Zod v4 uses `issues` property for validation errors
+        const issues = failure.issues || [];
+        logger?.error(`Validation failed: ${issues.length} issues on ${event.url.pathname}`);
+        // Surface the failing field path(s) in the top-level message so
+        // API consumers don't have to dig into `errors[].path` to know
+        // what to fix. Falls back to the generic phrase when no path is
+        // available (rare — almost every Zod issue has a path).
+        const fieldList = issues
+            .map((issue) => issue.path?.join('.'))
+            .filter((p) => typeof p === 'string' && p.length > 0);
+        const message = fieldList.length > 0 ? `Validation failed: ${fieldList.join(', ')}` : 'Validation failed';
+        // The validation details ride in the error body; SvelteKit serializes it
+        // as the JSON response body.
+        const body = { message, errors: issues, issues };
+        throw error(400, body);
+    }
+    // Not a schema refusal (an unreadable body, say): the client is told a fixed
+    // fact, and what failed goes to the log.
+    logger?.warn('Request input could not be read', { error: failureAsError(failure).message });
+    throw error(400, { message: 'Invalid request data' });
+}
+/**
+ * Superusers and staff bypass every billing gate (feature access, credit
+ * headroom, quota deduction). Treated as having infinite entitlement so
+ * operators are never throttled while running platform/admin work.
+ *
+ * This is a billing decision only. It is consulted by the billing step, which
+ * every pipeline runs AFTER the authorization verdict (authentication,
+ * permissions, ownership, admin-only): an authorization refusal has already
+ * left the pipeline by then, and this override never stands in for it.
+ */
+function hasOperatorBillingOverride(user) {
+    return user.isSuperuser === true || user.staff === true;
+}
+/** The thrown value when it is one of the pipeline's own refusals before billing; guarded against hostile values. */
+function authorizationVerdict(thrown) {
+    if (guardedInstanceOf(thrown, AuthenticationError))
+        return thrown;
+    if (guardedInstanceOf(thrown, PermissionError))
+        return thrown;
+    if (guardedInstanceOf(thrown, RateLimitError))
+        return thrown;
+    return undefined;
+}
+/** The thrown value when it is one of billing's own refusals. */
+function billingVerdict(thrown) {
+    if (guardedInstanceOf(thrown, SubscriptionRequiredError))
+        return thrown;
+    if (guardedInstanceOf(thrown, QuotaExceededError))
+        return thrown;
+    if (guardedInstanceOf(thrown, BillingServiceUnavailableError))
+        return thrown;
+    if (guardedInstanceOf(thrown, InsufficientCreditsError))
+        return thrown;
+    return undefined;
+}
+/** A thrown SvelteKit `error()` / `redirect()` carries a `status`. */
+const StatusCarrierSchema = z.object({ status: z.number() });
+/**
+ * Whether the thrown value is a SvelteKit HttpError or Redirect: it carries a
+ * numeric `status` that can be read. A value whose `status` throws or is not a
+ * number is not one, and is handled as an unexpected failure.
+ */
+function carriesStatus(thrown) {
+    return parseGuarded(StatusCarrierSchema, thrown) !== undefined;
+}
+/** The response a pipeline refusal answers with, or nothing when `thrown` is not one. */
+function refusalResponse(thrown) {
+    return (authorizationVerdict(thrown) ?? billingVerdict(thrown))?.toResponse();
+}
+function isUsableAmount(amount) {
+    return amount === undefined || (Number.isFinite(amount) && amount >= 0);
+}
+/** Refuse (typed, value-free) a billing config whose credit amounts are NaN, infinite or negative. */
+function requireValidBillingAmounts(billing) {
+    if (!isUsableAmount(billing.credits) || !isUsableAmount(billing.requireMinCreditBalance)) {
+        throw new BillingServiceUnavailableError('Billing configuration invalid');
+    }
+}
+/**
+ * The credits this request is checked against: the calculator's amount for the
+ * request's size when the endpoint declares both (`dynamicCredits` /
+ * `tieredBilling` plus `requestSize`), else the configured `credits` (default 1).
+ * A calculator or size reader that throws, or an amount that is not a finite,
+ * non-negative number, refuses the request with a typed, value-free 503; the
+ * gate never opens on a failed calculation.
+ */
+async function creditAmount(event, billing) {
+    const { creditsFor, requestSize } = billing;
+    if (!creditsFor || !requestSize)
+        return billing.credits ?? 1;
+    const priced = await settle(async () => {
+        // `requestSize` produces this config's `TSize` and `creditsFor` prices that
+        // same `TSize`, so the calculator the endpoint declared is called with the
+        // size it prices. It validates the size it is given and the result is
+        // re-checked just below.
+        return creditsFor(await requestSize(event));
+    });
+    if (priced.ok && isUsableAmount(priced.value))
+        return priced.value;
+    // A failing or invalid calculation is refused with a fixed answer; what the
+    // calculator threw goes to the log, never to the response.
+    if (!priced.ok) {
+        _logger.warn('Billing amount calculation failed', {
+            error: failureAsError(priced.error).message
+        });
+    }
+    throw new BillingServiceUnavailableError('Billing amount unavailable');
+}
+/** An org id a richer app user may carry beside the fields `VibesKitUser` names. */
+const MemberOrgSchema = z.object({ orgId: z.string().nullish() });
+/**
+ * Handle billing checks
+ */
+async function handleBilling(event, billing) {
+    const _klocals = asVibesKitLocals(event.locals);
+    if (!_klocals.user) {
+        return; // Skip billing for unauthenticated users
+    }
+    if (hasOperatorBillingOverride(_klocals.user)) {
+        return;
+    }
+    const userId = _klocals.user.id;
+    const kit = getVibesKit();
+    const billingService = kit.config.services?.billing;
+    const logger = kit.config.services?.logger;
+    if (!billingService) {
+        if (billing.allowFallbackOnError) {
+            logger?.warn('Billing service not configured, allowing request via fallback');
+            return;
+        }
+        throw new BillingServiceUnavailableError('Billing service not configured');
+    }
+    const runtime = requireKitRuntime(_klocals);
+    const checked = await settle(async () => {
+        // A configured amount that is not a finite, non-negative number would make a
+        // comparison below silently pass (NaN) or a gate meaningless (negative), so
+        // the gate refuses instead of opening.
+        requireValidBillingAmounts(billing);
+        // Check feature access (single or multiple)
+        const requiredFeatures = [];
+        if (billing.feature)
+            requiredFeatures.push(billing.feature);
+        if (billing.features && Array.isArray(billing.features)) {
+            for (const f of billing.features)
+                if (f)
+                    requiredFeatures.push(f);
+        }
+        if (requiredFeatures.length > 0) {
+            for (const feat of requiredFeatures) {
+                const hasAccess = await billingService.hasFeatureAccess(runtime, userId, feat);
+                if (!hasAccess) {
+                    // Implementation detail: The service knows the current plan, but we might want to fetch it for the error message
+                    // For now, providing a generic message. The service could throw this error itself, but the interface returns boolean.
+                    throw new SubscriptionRequiredError(feat, 'premium', // Placeholder, or fetch from service if needed
+                    undefined, `Access to ${feat} requires a subscription upgrade.`);
+                }
+            }
+        }
+        // Pre-flight credit balance gate. Refuses requests when the user
+        // has no headroom; post-hoc rated deduction still does the real
+        // accounting via `recordGenerationUsage`.
+        if (billing.requireMinCreditBalance !== undefined) {
+            const minBalance = billing.requireMinCreditBalance;
+            let snapshot = await billingService.getBalance(runtime, userId);
+            // Org-first billing: if the member's own pool is short but their org
+            // has opted in to paying for members (and they're under allocation
+            // with org pool funds), the charge will draw from the org pool — so
+            // re-check headroom against it. Only fires on an already-short user
+            // balance, so the happy path keeps its single balance read and no
+            // org lookup runs for anyone who isn't actually low.
+            const memberOrgId = MemberOrgSchema.safeParse(_klocals.user).data?.orgId ?? null;
+            if (snapshot !== null && snapshot.balance < minBalance && memberOrgId) {
+                const orgAware = await billingService.getBalance(runtime, userId, {
+                    memberActiveOrgId: memberOrgId
+                });
+                if (orgAware !== null)
+                    snapshot = orgAware;
+            }
+            if (snapshot === null) {
+                if (!billing.allowFallbackOnError) {
+                    throw new BillingServiceUnavailableError('Credit balance check unavailable');
+                }
+                logger?.warn('Credit balance read failed; allowing via fallback', {
+                    userId,
+                    minBalance
+                });
+            }
+            else if (!(snapshot.balance >= minBalance)) {
+                // Written so a balance that is not a number (NaN) is refused, not passed.
+                const upgradeUrl = billing.upgradeUrl;
+                throw new InsufficientCreditsError(snapshot.balance, minBalance, upgradeUrl, `You need at least ${minBalance.toFixed(2)} credits to use this feature. Your balance is ${snapshot.balance.toFixed(2)}.`);
+            }
+        }
+        // Check and consume credits
+        const quotaFeature = billing.quotaFeature;
+        const amount = await creditAmount(event, billing);
+        if (quotaFeature) {
+            const quotaCheck = await billingService.checkQuota(runtime, userId, quotaFeature, amount);
+            if (!quotaCheck.allowed) {
+                throw new QuotaExceededError(quotaFeature, quotaCheck.currentUsage, quotaCheck.limit || 0, undefined, // resetTime could be passed from service checkQuota response if extended
+                undefined, `Usage quota exceeded for ${quotaFeature}.`);
+            }
+            // Phase 6: wrapper does quota check only — no usage record,
+            // no flat-rate deduction. Emitters call
+            // `recordGenerationUsage` / `recordPlatformResource` /
+            // `recordSandboxUptime` post-hoc; those routes through the
+            // rating engine + credit pools and produce the single
+            // canonical ledger row + usage_records row per request.
+        }
+        // Inject billing context if requested
+        if (billing.injectContext) {
+            const subscription = await billingService.getUserSubscription(runtime, userId);
+            const planSlug = await billingService.getUserPlanSlug(runtime, userId);
+            _klocals.billing = {
+                subscription,
+                planSlug,
+                planTier: planSlug,
+                normalizedPlan: planSlug,
+                hasActiveSubscription: !!subscription && subscription.status === 'active'
+            };
+        }
+    });
+    if (checked.ok)
+        return;
+    const failure = checked.error;
+    const verdict = billingVerdict(failure);
+    if (verdict) {
+        throw verdict;
+    }
+    logger?.error('Billing check error', failureAsError(failure), {
+        userId,
+        endpoint: event.url.pathname,
+        category: 'billing'
+    });
+    // Fail open by default if configured
+    if (billing.allowFallbackOnError) {
+        logger?.warn('Billing service error, allowing request', {
+            userId,
+            endpoint: event.url.pathname,
+            category: 'billing'
+        });
+        return;
+    }
+    throw new BillingServiceUnavailableError();
+}
+/**
+ * Log request/response for monitoring
+ */
+function logRequest(event, context, failed) {
+    const duration = performanceApi.now() - context.startTime;
+    const logData = {
+        requestId: context.requestId,
+        method: event.request.method,
+        url: event.url.pathname + event.url.search,
+        userAgent: event.request.headers.get('user-agent') ?? undefined,
+        userId: context.user?.id,
+        duration: Math.round(duration),
+        status: failed ? failed.status : 200,
+        error: failed?.message,
+        timestamp: new Date().toISOString()
+    };
+    // A failing logger must not replace the request's own outcome, so the write
+    // is attempted and its failure is not allowed to propagate.
+    settleNow(() => {
+        if (failed) {
+            // The kit logger seam takes the failure in the context and hands the
+            // injected Logger its `(message, error, meta)` form.
+            _logger.error('API request failed', {
+                ...logData,
+                category: 'api-request',
+                error: failed.error
+            });
+        }
+        else {
+            _logger.info('API request completed', {
+                ...logData,
+                category: 'api-request'
+            });
+        }
+    });
+}
+/** Describe a failed request without trusting the error: its status and message are read guarded and bounded. */
+function failedRequest(error) {
+    const serialized = serializeError(error);
+    return { error, status: serialized.statusCode || 500, message: serialized.message };
+}
+/**
+ * The configured `responses`, each entry in the registry's `{ description,
+ * schema }` form. A bare schema documents itself: its own description when it
+ * has one, else a generic line.
+ */
+function documentedResponses(responses) {
+    if (!responses)
+        return undefined;
+    const documented = {};
+    for (const [statusCode, response] of Object.entries(responses)) {
+        documented[statusCode] =
+            response instanceof z.ZodType
+                ? { description: response.description ?? `${statusCode} response`, schema: response }
+                : response;
+    }
+    return documented;
+}
+/**
+ * Register endpoint with OpenAPI registry
+ */
+export function registerWithOpenAPI(method, path, config, options = {}) {
+    // Skip OpenAPI registration while the host declares a build
+    if (options.building && !options.allowDuringBuild) {
+        return;
+    }
+    if (path === 'unknown') {
+        _logger.warn('OpenAPI registration skipped because route path could not be determined', {
+            method,
+            category: 'openapi'
+        });
+        return;
+    }
+    const authConfigForOpenAPI = config.auth || config.permissions;
+    const registered = settleNow(() => (options.registry ?? defaultOpenAPIRegistry()).register(method, path, {
+        metadata: config.metadata,
+        validation: config.validation,
+        responses: documentedResponses(config.responses),
+        auth: {
+            required: authConfigForOpenAPI?.required || authConfigForOpenAPI?.requireAuth,
+            permissions: authConfigForOpenAPI?.permissions
+                ? [...authConfigForOpenAPI.permissions]
+                : undefined,
+            superuser: false // We don't use this pattern
+        },
+        rateLimit: config.rateLimit
+            ? {
+                window: '1m',
+                max: config.rateLimit.rpm
+            }
+            : undefined
+    }, { building: options.building, allowDuringBuild: options.allowDuringBuild }));
+    if (!registered.ok) {
+        _logger.warn('OpenAPI registration failed', {
+            method,
+            path,
+            error: failureAsError(registered.error).message,
+            category: 'openapi'
+        });
+    }
+}
+/**
+ * Get the API path from stack trace
+ */
+function getPathFromStack() {
+    const stack = new Error().stack;
+    if (!stack)
+        return 'unknown';
+    const normalised = stack.replace(/\\/g, '/');
+    // Direct source match (dev, test)
+    const srcMatch = normalised.match(/\/src\/routes(\/[^\n:]+?)\/\+server\.[tj]s/);
+    if (srcMatch?.[1]) {
+        return ensureLeadingSlash(srcMatch[1]);
+    }
+    // Compiled output match (prod builds)
+    const compiledMatch = normalised.match(/\.svelte-kit\/output\/server\/entries\/endpoints\/(\(app\)\/)?([^\n:]+?)\/_server(?:\.[tj]s)?(?:\.js)?/);
+    if (compiledMatch?.[2]) {
+        const rawPath = compiledMatch[2];
+        return ensureLeadingSlash(decodeCompiledEndpointPath(rawPath));
+    }
+    return 'unknown';
+}
+function ensureLeadingSlash(path) {
+    if (!path)
+        return '/';
+    return path.startsWith('/') ? path : `/${path}`;
+}
+function decodeCompiledEndpointPath(rawPath) {
+    return (rawPath
+        .split('/')
+        .filter((segment) => segment && segment !== '(app)')
+        .map((segment) => {
+        if (/^_.+_$/.test(segment)) {
+            const inner = segment.slice(1, -1);
+            if (inner.startsWith('...')) {
+                return `[...${inner.slice(3)}]`;
+            }
+            if (inner.startsWith('[') && inner.endsWith(']')) {
+                return inner;
+            }
+            return `[${inner}]`;
+        }
+        return segment;
+    })
+        .join('/') || rawPath);
+}
+/**
+ * Core vibeskit wrapper function
+ */
+export function vibesWrapper(config, handler) {
+    return async (event) => {
+        const startTime = performanceApi.now();
+        const requestId = generateRequestId();
+        const context = {
+            startTime,
+            requestId,
+            validated: {}
+        };
+        const kit = getVibesKit();
+        const logger = kit.config.services?.logger;
+        const ran = await settle(async () => {
+            // 1. Authentication and permissions (support both 'auth' and 'permissions' keys)
+            const authConfig = config.auth || config.permissions;
+            if (authConfig) {
+                const authResult = await applyPermissionCheck(event, authConfig);
+                context.user = authResult.user;
+            }
+            // 2. Rate limiting
+            if (config.rateLimit) {
+                await applyRateLimit(event, config.rateLimit);
+            }
+            // 3. Billing checks
+            const billingBypassed = config.billing?.shouldBypass
+                ? await config.billing.shouldBypass(event)
+                : false;
+            if (config.billing && !billingBypassed) {
+                await handleBilling(event, config.billing);
+                // Add billing context to our context if it was injected
+                const _billingLocals = asVibesKitLocals(event.locals);
+                if (_billingLocals.billing) {
+                    context.billing = {
+                        planSlug: _billingLocals.billing.planSlug,
+                        planTier: _billingLocals.billing.planTier,
+                        normalizedPlan: _billingLocals.billing.normalizedPlan,
+                        subscription: _billingLocals.billing.subscription ?? null,
+                        hasActiveSubscription: _billingLocals.billing.hasActiveSubscription
+                    };
+                }
+            }
+            // 4. Request validation
+            if (config.validation) {
+                context.validated = await validateRequest(event, config.validation);
+            }
+            // 5. Check cache (if enabled) - only for GET/HEAD requests
+            let responseData;
+            let _cacheHit = false;
+            const isCacheableMethod = event.request.method === 'GET' || event.request.method === 'HEAD';
+            if (config.caching?.enabled && isCacheableMethod) {
+                const cacheResult = await applyCacheGet(event, config.caching);
+                const cacheKey = cacheResult.key;
+                _cacheHit = cacheResult.hit;
+                if (cacheResult.hit && cacheResult.data !== undefined) {
+                    responseData = cacheResult.data;
+                    logger?.debug('Response served from cache', {
+                        requestId,
+                        cacheKey,
+                        category: 'caching'
+                    });
+                }
+                else {
+                    // Cache miss - execute handler
+                    responseData = await handler(event, context);
+                    // Native Responses carry status/headers/streams that the
+                    // object cache cannot serialize faithfully. Leave those to
+                    // `withResponseCache`, which caches the complete response.
+                    if (!(responseData instanceof Response)) {
+                        await applyCacheSet(cacheKey, responseData, config.caching, event);
+                    }
+                }
+            }
+            else {
+                // No caching - execute handler directly
+                responseData = await handler(event, context);
+            }
+            // 6. Log successful request
+            if (config.logging !== false) {
+                logRequest(event, context);
+            }
+            // 7. Response handling
+            // If handler returned a native Response (e.g., file/binary), pass it through
+            if (responseData instanceof Response) {
+                return responseData; // preserve headers/body
+            }
+            return json(responseData);
+        });
+        if (ran.ok)
+            return ran.value;
+        // The pipeline failed: answer it by kind (refusals, SvelteKit errors, schema
+        // errors) or, for anything unexpected, with a fixed value-free 500.
+        const err = ran.error;
+        // Handle specific error types
+        const refusal = refusalResponse(err);
+        if (refusal)
+            return refusal;
+        // Log error
+        if (config.logging !== false) {
+            const failure = errorInstance(err);
+            logRequest(event, context, failure && failedRequest(failure));
+        }
+        // Handle SvelteKit errors
+        if (carriesStatus(err)) {
+            throw err;
+        }
+        // Handle Zod validation errors (Zod v4 uses `issues`)
+        if (guardedInstanceOf(err, z.ZodError)) {
+            const body = { message: 'Validation error', errors: err.issues, issues: err.issues };
+            throw error(400, body);
+        }
+        // Generic error
+        logger?.error(`Unhandled error in vibeskit wrapper: ${requestId} on ${event.url.pathname}`, failureAsError(err), {
+            method: event.request.method,
+            category: 'api-error'
+        });
+        // A 500 answers with fixed, value-free facts only: what the thrown value
+        // said (message, stack, cause, code, payload) went to the log above, and
+        // the request id ties the two together.
+        const { showDetailedErrors, showDevelopmentModeWarning } = resolveDevelopmentMode(kit.config);
+        const body = {
+            message: 'Internal server error',
+            name: 'Error',
+            requestId,
+            method: event.request.method,
+            path: event.url.pathname,
+            routeId: event.route?.id || undefined,
+            statusCode: 500,
+            category: 'api-error',
+            environment: DEV ? 'development' : 'production',
+            showDetailedErrors,
+            showDevelopmentModeWarning
+        };
+        throw error(500, body);
+    };
+}
+const NOT_BUILDING = Object.freeze({ building: false });
+function methodEndpoint(host, method) {
+    return (config, handler) => {
+        if (!host.building) {
+            registerWithOpenAPI(method, getPathFromStack(), config);
+        }
+        // SAFETY: `TConfig['validation']` types `context.validated` as the output of
+        // the schemas in `config.validation`, and `vibesWrapper` fills
+        // `context.validated` by parsing exactly those schemas before the handler
+        // runs, so the untyped context it passes has the shape the handler was
+        // typed for. Generic erasure across the config type parameter.
+        return attachOpenApiRouteMetadata(vibesWrapper(config, handler), method, config);
+    };
+}
+export const vibesGET = methodEndpoint(NOT_BUILDING, 'GET');
+export const vibesPOST = methodEndpoint(NOT_BUILDING, 'POST');
+export const vibesPUT = methodEndpoint(NOT_BUILDING, 'PUT');
+export const vibesPATCH = methodEndpoint(NOT_BUILDING, 'PATCH');
+export const vibesDELETE = methodEndpoint(NOT_BUILDING, 'DELETE');
+/**
+ * SSE (Server-Sent Events) wrapper with full vibeskit middleware support
+ *
+ * Provides auth, rate limiting, billing (including credit deduction), and validation
+ * for streaming endpoints. Credit deduction happens before streaming begins.
+ *
+ * @example
+ * export const POST = vibesSSE(
+ *   {
+ *     metadata: { summary: 'Stream events', tags: ['Stream'] },
+ *     ...quick.auth(),
+ *     billing: billing.credits('stream-tokens', 1)
+ *   },
+ *   async (event, context) => {
+ *     const { stream } = context;
+ *
+ *     // Send events
+ *     stream.send({ data: { message: 'Hello' } });
+ *     stream.send({ event: 'update', data: { count: 1 } });
+ *
+ *     // Close when done
+ *     stream.close();
+ *   }
+ * );
+ */
+const sseEndpoint = (host) => (config, handler) => {
+    if (!host.building) {
+        const path = getPathFromStack();
+        // SSE endpoints use POST for streaming operations
+        registerWithOpenAPI('POST', path, config);
+    }
+    const endpoint = async (event) => {
+        const startTime = performanceApi.now();
+        const requestId = generateRequestId();
+        const context = {
+            startTime,
+            requestId,
+            validated: {}
+        };
+        const kit = getVibesKit();
+        const logger = kit.config.services?.logger;
+        // Set up SSE stream
+        let streamController = null;
+        let isClosed = false;
+        let eventCount = 0;
+        let _providerType = 'user';
+        const eventSchemas = config.sse?.events;
+        const encoder = new TextEncoder();
+        let lastBalanceCheckTime = -5000;
+        let eventsSinceLastCheck = 0;
+        let billingBypassed = false;
+        const send = (sseEvent) => {
+            if (!streamController || isClosed)
+                return;
+            // Perform periodic mid-stream quota balance verification if billing is configured.
+            // To prevent overloading the database/service with balance checks, we throttle this
+            // to at most once every 10 events or 3 seconds.
+            const billingService = kit.config.services?.billing;
+            const userId = context.user?.id;
+            if (billingService && userId !== undefined && config.billing && !billingBypassed) {
+                eventsSinceLastCheck++;
+                const now = performanceApi.now();
+                if (eventsSinceLastCheck >= 10 || now - lastBalanceCheckTime > 3000) {
+                    lastBalanceCheckTime = now;
+                    eventsSinceLastCheck = 0;
+                    settle(() => billingService.getBalance(requireKitRuntime(asVibesKitLocals(event.locals)), userId)).then((balance) => {
+                        if (!balance.ok) {
+                            logger?.warn('Failed to fetch mid-stream credit balance snapshot', {
+                                requestId,
+                                userId,
+                                error: failureAsError(balance.error).message,
+                                category: 'billing-gate'
+                            });
+                            return;
+                        }
+                        const snapshot = balance.value;
+                        // `!(> 0)` so a balance that is not a number ends the stream too.
+                        if (snapshot && !(snapshot.balance > 0) && !isClosed) {
+                            logger?.warn('Active mid-stream credit pool depletion detected. Aborting SSE stream.', {
+                                requestId,
+                                userId,
+                                balance: snapshot.balance,
+                                category: 'billing-gate'
+                            });
+                            abort(new Error('INSUFFICIENT_CREDITS'));
+                        }
+                    });
+                }
+            }
+            let eventName = sseEvent.event;
+            let eventData = sseEvent.data;
+            if (eventSchemas && eventName && eventSchemas[eventName]) {
+                const result = eventSchemas[eventName].safeParse(eventData);
+                if (!result.success) {
+                    logger?.warn('SSE event validation failed', {
+                        requestId,
+                        event: eventName,
+                        errors: JSON.stringify(result.error.issues.map((i) => i.message)),
+                        category: 'sse-validation'
+                    });
+                    eventName = 'error';
+                    eventData = {
+                        type: 'error',
+                        error: { code: 'VALIDATION_ERROR', message: 'Event data failed schema validation' }
+                    };
+                }
+            }
+            let payload = '';
+            if (sseEvent.id)
+                payload += `id: ${sseEvent.id}\n`;
+            if (eventName)
+                payload += `event: ${eventName}\n`;
+            if (sseEvent.retry)
+                payload += `retry: ${sseEvent.retry}\n`;
+            const text = z.string().safeParse(eventData);
+            const data = text.success ? text.data : JSON.stringify(eventData);
+            payload += `data: ${data}\n\n`;
+            const controller = streamController;
+            const sent = settleNow(() => controller.enqueue(encoder.encode(payload)));
+            if (sent.ok) {
+                eventCount++;
+            }
+            else {
+                logger?.warn('Failed to send SSE event', {
+                    requestId,
+                    error: failureAsError(sent.error).message
+                });
+            }
+        };
+        const setProviderType = (type) => {
+            _providerType = type;
+        };
+        const comment = (text) => {
+            if (!streamController || isClosed)
+                return;
+            const controller = streamController;
+            // best-effort: a controller that is already closed refuses the comment
+            settleNow(() => controller.enqueue(encoder.encode(`: ${text}\n\n`)));
+        };
+        const close = () => {
+            if (!streamController || isClosed)
+                return;
+            isClosed = true;
+            const controller = streamController;
+            // best-effort cleanup: the controller may already be closed
+            settleNow(() => controller.close());
+        };
+        const abort = (error) => {
+            if (!streamController || isClosed)
+                return;
+            isClosed = true;
+            const controller = streamController;
+            // Send error event before closing
+            if (error) {
+                // best-effort: with the controller already closed the error event cannot be delivered
+                settleNow(() => controller.enqueue(encoder.encode(`event: error\ndata: ${JSON.stringify({ message: serializeError(error).message })}\n\n`)));
+            }
+            // best-effort cleanup: the controller may already be closed
+            settleNow(() => controller.close());
+        };
+        // Run middleware before creating stream
+        const preflight = await settle(async () => {
+            // 1. Authentication and permissions
+            const authConfig = config.auth || config.permissions;
+            if (authConfig) {
+                const authResult = await applyPermissionCheck(event, authConfig);
+                context.user = authResult.user;
+            }
+            // 2. Rate limiting
+            if (config.rateLimit) {
+                await applyRateLimit(event, config.rateLimit);
+            }
+            // 3. Billing checks (THIS IS THE KEY PART - deducts credits before streaming)
+            const _sseBillingLocals = asVibesKitLocals(event.locals);
+            const upstreamBilling = config.billing?.shouldBypass
+                ? await config.billing.shouldBypass(event)
+                : false;
+            // Operators are exempt from every billing gate, including the mid-stream
+            // balance check below, so it is skipped for them as the preflight is.
+            billingBypassed =
+                upstreamBilling ||
+                    (_sseBillingLocals.user ? hasOperatorBillingOverride(_sseBillingLocals.user) : false);
+            if (config.billing && !billingBypassed) {
+                await handleBilling(event, config.billing);
+                if (_sseBillingLocals.billing) {
+                    context.billing = {
+                        planSlug: _sseBillingLocals.billing.planSlug,
+                        planTier: _sseBillingLocals.billing.planTier,
+                        normalizedPlan: _sseBillingLocals.billing.normalizedPlan,
+                        subscription: _sseBillingLocals.billing.subscription ?? null,
+                        hasActiveSubscription: _sseBillingLocals.billing.hasActiveSubscription
+                    };
+                }
+            }
+            // 4. Request validation
+            if (config.validation) {
+                context.validated = await validateRequest(event, config.validation);
+            }
+        });
+        if (!preflight.ok) {
+            const err = preflight.error;
+            // Handle middleware errors before stream starts (can return JSON errors)
+            const refusal = refusalResponse(err);
+            if (refusal)
+                return refusal;
+            if (config.logging !== false) {
+                const failure = errorInstance(err);
+                logRequest(event, context, failure && failedRequest(failure));
+            }
+            if (carriesStatus(err)) {
+                throw err;
+            }
+            if (guardedInstanceOf(err, z.ZodError)) {
+                const body = { message: 'Validation error', errors: err.issues, issues: err.issues };
+                throw error(400, body);
+            }
+            logger?.error('SSE middleware error', failureAsError(err), {
+                requestId,
+                path: event.url.pathname,
+                category: 'sse-error'
+            });
+            return json({ message: 'Internal server error' }, { status: 500 });
+        }
+        // Create the SSE stream
+        const stream = new ReadableStream({
+            start(controller) {
+                streamController = controller;
+                // Execute handler
+                settle(async () => {
+                    const ran = await settle(() => handler(event, {
+                        ...context,
+                        stream: { send, comment, close, abort, setProviderType }
+                    }));
+                    if (ran.ok) {
+                        // Ensure stream is closed if handler didn't close it
+                        if (!isClosed) {
+                            close();
+                        }
+                        return;
+                    }
+                    logger?.error('SSE handler error', failureAsError(ran.error), {
+                        requestId,
+                        path: event.url.pathname,
+                        eventCount,
+                        duration: Math.round(performanceApi.now() - startTime),
+                        category: 'sse-handler-error'
+                    });
+                    // The client is told a fixed fact; what the handler threw is in the log.
+                    abort(new Error('Handler failed'));
+                    // Billing is preflight-only in the wrapper. Post-hoc
+                    // emitters own rated deductions, so there is no wrapper
+                    // transaction to refund on stream failure.
+                }).then((outcome) => {
+                    if (outcome.ok)
+                        return;
+                    logger?.error('SSE stream failed', failureAsError(outcome.error), {
+                        requestId,
+                        category: 'sse-handler-error'
+                    });
+                    abort(new Error('Unhandled SSE error'));
+                });
+            },
+            cancel() {
+                // Client disconnected
+                isClosed = true;
+                logger?.info('SSE stream cancelled by client', {
+                    requestId,
+                    eventCount,
+                    duration: Math.round(performanceApi.now() - startTime),
+                    category: 'sse-cancel'
+                });
+            }
+        });
+        // Log successful SSE start
+        if (config.logging !== false) {
+            logger?.info('SSE stream started', {
+                requestId,
+                userId: context.user?.id,
+                path: event.url.pathname,
+                category: 'sse-start'
+            });
+        }
+        return new Response(stream, {
+            headers: {
+                'Content-Type': 'text/event-stream; charset=utf-8',
+                'Cache-Control': 'no-cache, no-transform',
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no'
+            }
+        });
+    };
+    return attachOpenApiRouteMetadata(endpoint, 'POST', config);
+};
+export const vibesSSE = sseEndpoint(NOT_BUILDING);
+const manualEndpoint = (host) => (method, path, config, handler) => {
+    registerWithOpenAPI(method, path, config, { building: host.building });
+    return attachOpenApiRouteMetadata(vibesWrapper(config, handler), method, config);
+};
+/**
+ * Alternative exports for manual path specification
+ */
+export const vibesEndpoint = manualEndpoint(NOT_BUILDING);
+/**
+ * The endpoint wrappers bound to what the host declares. A SvelteKit app calls
+ * this once in its own `$lib` with `$app/environment`'s `building`, and its
+ * routes import the wrappers from there. The plain exports above declare no
+ * build phase.
+ */
+export function createVibesEndpoints(host) {
+    const declared = Object.freeze({ building: host.building });
+    return {
+        vibesGET: methodEndpoint(declared, 'GET'),
+        vibesPOST: methodEndpoint(declared, 'POST'),
+        vibesPUT: methodEndpoint(declared, 'PUT'),
+        vibesPATCH: methodEndpoint(declared, 'PATCH'),
+        vibesDELETE: methodEndpoint(declared, 'DELETE'),
+        vibesSSE: sseEndpoint(declared),
+        vibesEndpoint: manualEndpoint(declared)
+    };
+}