@velajs/vela 1.15.0 → 1.17.0

package/dist/http/decorators.d.ts

@@ -31,15 +31,24 @@ export declare function Controller(pathOrOptions?: string | ControllerOptions):
  */
 export declare function Version(version: number | number[]): MethodDecorator;
 export declare function getRouteVersion(target: Constructor, propertyKey: string | symbol): number | number[] | undefined;
-export declare const Get: (path?: string) => MethodDecorator;
-export declare const Post: (path?: string) => MethodDecorator;
-export declare const Put: (path?: string) => MethodDecorator;
-export declare const Patch: (path?: string) => MethodDecorator;
-export declare const Delete: (path?: string) => MethodDecorator;
-export declare const Options: (path?: string) => MethodDecorator;
-export declare const Head: (path?: string) => MethodDecorator;
-export declare const All: (path?: string) => MethodDecorator;
-export declare const Sse: (path?: string) => MethodDecorator;
+/** Per-route options for the HTTP method decorators (`@Get`, `@Post`, …). */
+export interface RouteOptions {
+    /**
+     * A stable, human-readable name for this route. Enables URL generation
+     * (`UrlGeneratorService.urlFor(name, …)`), surfaces on `app.describeRoutes()`,
+     * and — when set — becomes the OpenAPI `operationId`.
+     */
+    name?: string;
+}
+export declare const Get: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Post: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Put: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Patch: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Delete: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Options: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Head: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const All: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Sse: (path?: string, options?: RouteOptions) => MethodDecorator;
 export declare const Param: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;
 export declare const Query: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;
 export declare const Body: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;

package/dist/http/decorators.js

@@ -57,7 +57,7 @@ export function getRouteVersion(target, propertyKey) {
     return MetadataRegistry.getRouteVersion(target, propertyKey);
 }
 function createMethodDecorator(method) {
-    return (path = '')=>{
+    return (path = '', options)=>{
         return (target, propertyKey, _descriptor)=>{
             const ctor = target.constructor;
             const normalizedPath = normalizePath(path);
@@ -68,6 +68,9 @@ function createMethodDecorator(method) {
                 handlerName: propertyKey,
                 ...version !== undefined ? {
                     version
+                } : {},
+                ...options?.name !== undefined ? {
+                    name: options.name
                 } : {}
             });
         };

package/dist/http/index.d.ts

@@ -3,6 +3,10 @@ export type { RouteManagerOptions } from './route.manager';
 export { MiddlewareBuilder } from '../module/middleware';
 export type { MiddlewareConsumer, MiddlewareConfigProxy, RouteInfo, NestModule, MiddlewareRouteDefinition } from '../module/middleware';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, isController, } from './decorators';
+export type { RouteOptions } from './decorators';
 export { createLazyParamDecorator } from './lazy-param.decorator';
+export { UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET, } from './url/index';
+export type { UrlForOptions, SignedUrlGenerateOptions } from './url/index';
+export type { VelaRouteMap, RouteName, RouteParams } from './route-map';
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext, } from './ambient';
 export type { RouteMetadata, ControllerMetadata, ControllerOptions, ParamMetadata, ControllerRegistration, } from './types';

package/dist/http/index.js

@@ -2,4 +2,6 @@ export { RouteManager } from "./route.manager.js";
 export { MiddlewareBuilder } from "../module/middleware.js";
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, isController } from "./decorators.js";
 export { createLazyParamDecorator } from "./lazy-param.decorator.js";
+// Named-route URL generation + signed URLs
+export { UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET } from "./url/index.js";
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext } from "./ambient.js";

package/dist/http/route-map.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Augmentable map of route name → its path params. Users opt in to type-safe
+ * URL generation by augmenting this interface — no build step, no codegen:
+ *
+ * ```ts
+ * declare module '@velajs/vela' {
+ *   interface VelaRouteMap {
+ *     'users.index': Record<string, never>;
+ *     'users.show': { id: string };
+ *   }
+ * }
+ * ```
+ *
+ * Until augmented it stays empty, so `RouteName` falls back to `string` and
+ * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
+ * callers keep working unchanged.
+ */
+export interface VelaRouteMap {
+}
+/**
+ * Every valid route name. Falls back to `string` when `VelaRouteMap` has not
+ * been augmented, so `urlFor`/`signedUrl` accept any name in an untyped app.
+ */
+export type RouteName = keyof VelaRouteMap extends never ? string : Extract<keyof VelaRouteMap, string>;
+/**
+ * The params object required to build a named route's URL. When `VelaRouteMap`
+ * is augmented, resolves to the declared params shape for `N`; otherwise a
+ * loose `Record<string, string> | undefined`.
+ */
+export type RouteParams<N extends RouteName> = N extends keyof VelaRouteMap ? VelaRouteMap[N] : Record<string, string> | undefined;

package/dist/http/route-map.js

@@ -0,0 +1,27 @@
+// Zero-codegen, type-safe route names — mirrors the augmentation pattern from
+// stratal `packages/core/src/router/route-map.ts` (MIT © Temitayo Fadojutimi).
+// Adapted for vela: `VelaRouteMap` maps a route name directly to its params
+// object (stratal wraps params in `{ params: … }`; vela keeps it flat to match
+// the `urlFor(name, params)` call shape).
+/**
+ * Augmentable map of route name → its path params. Users opt in to type-safe
+ * URL generation by augmenting this interface — no build step, no codegen:
+ *
+ * ```ts
+ * declare module '@velajs/vela' {
+ *   interface VelaRouteMap {
+ *     'users.index': Record<string, never>;
+ *     'users.show': { id: string };
+ *   }
+ * }
+ * ```
+ *
+ * Until augmented it stays empty, so `RouteName` falls back to `string` and
+ * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
+ * callers keep working unchanged.
+ */ // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentable interface, intentionally empty until a consumer declares routes
+/**
+ * The params object required to build a named route's URL. When `VelaRouteMap`
+ * is augmented, resolves to the declared params shape for `N`; otherwise a
+ * loose `Record<string, string> | undefined`.
+ */ export { };

package/dist/http/route.manager.d.ts

@@ -21,6 +21,8 @@ export interface RouteDescription {
     controller: string;
     handler: string;
     version?: number;
+    /** Route name (`@Get(path, { name })`) — the URL-generation / `operationId` key. */
+    name?: string;
 }
 export interface RouteManagerOptions {
     getClientIp?: (c: Context) => string | null;

package/dist/http/route.manager.js

@@ -388,7 +388,10 @@ export class RouteManager {
                             path: fullPath || '/',
                             controller: controller.name,
                             handler: String(route.handlerName),
-                            version: versionsForPaths[pathIndex]
+                            version: versionsForPaths[pathIndex],
+                            ...route.name !== undefined ? {
+                                name: route.name
+                            } : {}
                         });
                     }
                 }

package/dist/http/types.d.ts

@@ -6,6 +6,8 @@ export interface RouteMetadata {
     path: string;
     handlerName: string | symbol;
     version?: number | number[];
+    /** Route name for URL generation / OpenAPI operationId (`@Get(path, { name })`). */
+    name?: string;
 }
 export interface ControllerOptions {
     path?: string;

package/dist/http/url/index.d.ts

@@ -0,0 +1,4 @@
+export { UrlGeneratorService } from './url-generator.service';
+export type { UrlForOptions, SignedUrlGenerateOptions } from './url-generator.service';
+export { SignedUrlGuard, SignedUrl } from './signed-url.guard';
+export { URL_SIGNING_SECRET } from './signing-secret';

package/dist/http/url/index.js

@@ -0,0 +1,3 @@
+export { UrlGeneratorService } from "./url-generator.service.js";
+export { SignedUrlGuard, SignedUrl } from "./signed-url.guard.js";
+export { URL_SIGNING_SECRET } from "./signing-secret.js";

package/dist/http/url/signed-url.guard.d.ts

@@ -0,0 +1,27 @@
+import { applyDecorators } from '../decorators';
+import type { CanActivate, ExecutionContext } from '../../pipeline/types';
+/**
+ * Verifies the HMAC signature (and `expires`) of the incoming request URL,
+ * using the same secret source as {@link UrlGeneratorService.signedUrl}: the
+ * {@link URL_SIGNING_SECRET} token, else `CONFIG_ENV`. Throws
+ * `ForbiddenException` (403) when the signature is missing, tampered, or
+ * expired. Registered app-wide by `bootstrap`; apply it per-route with
+ * {@link SignedUrl}.
+ */
+export declare class SignedUrlGuard implements CanActivate {
+    private readonly secretToken?;
+    private readonly env;
+    constructor(secretToken?: string | undefined, env?: Record<string, unknown>);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+/**
+ * Guards a route with {@link SignedUrlGuard} — the request must carry a valid,
+ * unexpired HMAC signature (produced by `UrlGeneratorService.signedUrl`).
+ *
+ * ```ts
+ * @Get('download', { name: 'file.download' })
+ * @SignedUrl()
+ * download() { ... }
+ * ```
+ */
+export declare function SignedUrl(): ReturnType<typeof applyDecorators>;

package/dist/http/url/signed-url.guard.js

@@ -0,0 +1,62 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Injectable, Inject, Optional } from "../../container/decorators.js";
+import { CONFIG_ENV } from "../../config/config.tokens.js";
+import { verifySignedUrl } from "../../crypto/signed-url.js";
+import { ForbiddenException } from "../../errors/http-exception.js";
+import { applyDecorators } from "../decorators.js";
+import { UseGuards } from "../../pipeline/decorators.js";
+import { URL_SIGNING_SECRET, resolveSigningSecret } from "./signing-secret.js";
+export class SignedUrlGuard {
+    secretToken;
+    env;
+    constructor(secretToken, env = {}){
+        this.secretToken = secretToken;
+        this.env = env;
+    }
+    async canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        const secret = resolveSigningSecret(undefined, this.secretToken, this.env);
+        const valid = await verifySignedUrl(request.url, secret);
+        if (!valid) {
+            throw new ForbiddenException('Invalid or expired signed URL');
+        }
+        return true;
+    }
+}
+SignedUrlGuard = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Optional()),
+    _ts_param(0, Inject(URL_SIGNING_SECRET)),
+    _ts_param(1, Optional()),
+    _ts_param(1, Inject(CONFIG_ENV)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        String,
+        typeof Record === "undefined" ? Object : Record
+    ])
+], SignedUrlGuard);
+/**
+ * Guards a route with {@link SignedUrlGuard} — the request must carry a valid,
+ * unexpired HMAC signature (produced by `UrlGeneratorService.signedUrl`).
+ *
+ * ```ts
+ * @Get('download', { name: 'file.download' })
+ * @SignedUrl()
+ * download() { ... }
+ * ```
+ */ export function SignedUrl() {
+    return applyDecorators(UseGuards(SignedUrlGuard));
+}

package/dist/http/url/signing-secret.d.ts

@@ -0,0 +1,20 @@
+import { InjectionToken } from '../../container/types';
+/**
+ * Optional DI token holding the HMAC secret used to sign / verify URLs. Provide
+ * it globally (e.g. from a platform adapter or a `@Global` module) so both
+ * {@link UrlGeneratorService} and the signed-URL guard can read it:
+ *
+ * ```ts
+ * { provide: URL_SIGNING_SECRET, useValue: env.URL_SIGNING_SECRET }
+ * ```
+ */
+export declare const URL_SIGNING_SECRET: InjectionToken<string>;
+/** Key read from `CONFIG_ENV` when no explicit secret / token is available. */
+export declare const URL_SIGNING_SECRET_ENV_KEY = "URL_SIGNING_SECRET";
+/**
+ * Resolve the signing secret from, in order: an explicit argument, the
+ * {@link URL_SIGNING_SECRET} token, then `CONFIG_ENV[URL_SIGNING_SECRET]`.
+ * Throws a descriptive error when none is available — signing must never fall
+ * back to an empty/implicit key.
+ */
+export declare function resolveSigningSecret(explicit: string | undefined, token: string | undefined, env: Record<string, unknown> | undefined): string;

package/dist/http/url/signing-secret.js

@@ -0,0 +1,24 @@
+import { InjectionToken } from "../../container/types.js";
+/**
+ * Optional DI token holding the HMAC secret used to sign / verify URLs. Provide
+ * it globally (e.g. from a platform adapter or a `@Global` module) so both
+ * {@link UrlGeneratorService} and the signed-URL guard can read it:
+ *
+ * ```ts
+ * { provide: URL_SIGNING_SECRET, useValue: env.URL_SIGNING_SECRET }
+ * ```
+ */ export const URL_SIGNING_SECRET = new InjectionToken('URL_SIGNING_SECRET');
+/** Key read from `CONFIG_ENV` when no explicit secret / token is available. */ export const URL_SIGNING_SECRET_ENV_KEY = 'URL_SIGNING_SECRET';
+/**
+ * Resolve the signing secret from, in order: an explicit argument, the
+ * {@link URL_SIGNING_SECRET} token, then `CONFIG_ENV[URL_SIGNING_SECRET]`.
+ * Throws a descriptive error when none is available — signing must never fall
+ * back to an empty/implicit key.
+ */ export function resolveSigningSecret(explicit, token, env) {
+    const fromEnv = env?.[URL_SIGNING_SECRET_ENV_KEY];
+    const secret = explicit ?? token ?? (typeof fromEnv === 'string' ? fromEnv : undefined);
+    if (!secret) {
+        throw new Error('No URL signing secret is available. Pass one explicitly, register a ' + '`URL_SIGNING_SECRET` provider, or set `URL_SIGNING_SECRET` in `CONFIG_ENV`.');
+    }
+    return secret;
+}

package/dist/http/url/url-generator.service.d.ts

@@ -0,0 +1,52 @@
+import { RouteManager } from '../route.manager';
+import type { RouteName, RouteParams } from '../route-map';
+/** Value accepted for a path param or query entry. */
+type UrlParamValue = string | number | boolean;
+/** Extra options for {@link UrlGeneratorService.urlFor}. */
+export interface UrlForOptions {
+    /** Additional query-string entries merged after any leftover params. */
+    query?: Record<string, UrlParamValue>;
+}
+/** Options for {@link UrlGeneratorService.signedUrl}. */
+export interface SignedUrlGenerateOptions {
+    /** Time-to-live in seconds; enforced on verification via the `expires` param. */
+    expiresIn?: number;
+    /** Override the signing secret (else the `URL_SIGNING_SECRET` token / `CONFIG_ENV`). */
+    secret?: string;
+}
+/**
+ * Builds URLs for named routes (Laravel-flavoured `route()` ergonomics).
+ *
+ * Route descriptions are read LAZILY from the {@link RouteManager} on first use
+ * — post-build, so composition (global prefix + version + controller prefix) is
+ * already baked into each path — and it never instantiates controllers, so it
+ * plays nicely with lazy modules. Registered as an app-level singleton by
+ * `bootstrap`, so it is injectable anywhere.
+ */
+export declare class UrlGeneratorService {
+    private readonly routeManager;
+    private readonly secretToken?;
+    private readonly env;
+    private routeMap;
+    constructor(routeManager: RouteManager, secretToken?: string | undefined, env?: Record<string, unknown>);
+    /**
+     * Build the path for a named route, filling `:param` placeholders from
+     * `params`. Params that don't match a placeholder become query-string
+     * entries; `opts.query` is merged after them.
+     *
+     * @throws if no route carries `name`, or a required `:param` is missing.
+     */
+    urlFor<N extends RouteName>(name: N, params?: RouteParams<N>, opts?: UrlForOptions): string;
+    /**
+     * Build a named-route URL and HMAC-sign it (path + query). The secret comes
+     * from `options.secret`, else the {@link URL_SIGNING_SECRET} token, else
+     * `CONFIG_ENV`; a descriptive error is thrown when none is available.
+     */
+    signedUrl<N extends RouteName>(name: N, params?: RouteParams<N>, options?: SignedUrlGenerateOptions): Promise<string>;
+    /**
+     * Lazily index named route descriptions. Rebuilt while empty (routes may not
+     * be built yet), cached once populated.
+     */
+    private routes;
+}
+export {};

package/dist/http/url/url-generator.service.js

@@ -0,0 +1,104 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Injectable, Inject, Optional } from "../../container/decorators.js";
+import { CONFIG_ENV } from "../../config/config.tokens.js";
+import { signUrl } from "../../crypto/signed-url.js";
+import { RouteManager } from "../route.manager.js";
+import { URL_SIGNING_SECRET, resolveSigningSecret } from "./signing-secret.js";
+export class UrlGeneratorService {
+    routeManager;
+    secretToken;
+    env;
+    routeMap = null;
+    constructor(routeManager, secretToken, env = {}){
+        this.routeManager = routeManager;
+        this.secretToken = secretToken;
+        this.env = env;
+    }
+    /**
+   * Build the path for a named route, filling `:param` placeholders from
+   * `params`. Params that don't match a placeholder become query-string
+   * entries; `opts.query` is merged after them.
+   *
+   * @throws if no route carries `name`, or a required `:param` is missing.
+   */ urlFor(name, params, opts) {
+        const description = this.routes().get(name);
+        if (!description) {
+            throw new Error(`No route named "${String(name)}" was found. Give the route a name ` + `via \`@Get(path, { name: '${String(name)}' })\`.`);
+        }
+        const provided = {
+            ...params ?? {}
+        };
+        const consumed = new Set();
+        const path = description.path.replace(/:([A-Za-z0-9_]+)/g, (_match, key)=>{
+            const value = provided[key];
+            if (value === undefined || value === null) {
+                throw new Error(`Missing route param "${key}" for route "${String(name)}".`);
+            }
+            consumed.add(key);
+            return encodeURIComponent(String(value));
+        });
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(provided)){
+            if (consumed.has(key) || value === undefined || value === null) continue;
+            query.set(key, String(value));
+        }
+        for (const [key, value] of Object.entries(opts?.query ?? {})){
+            if (value === undefined || value === null) continue;
+            query.set(key, String(value));
+        }
+        const qs = query.toString();
+        return qs ? `${path}?${qs}` : path;
+    }
+    /**
+   * Build a named-route URL and HMAC-sign it (path + query). The secret comes
+   * from `options.secret`, else the {@link URL_SIGNING_SECRET} token, else
+   * `CONFIG_ENV`; a descriptive error is thrown when none is available.
+   */ async signedUrl(name, params, options = {}) {
+        const url = this.urlFor(name, params);
+        const secret = resolveSigningSecret(options.secret, this.secretToken, this.env);
+        return signUrl(url, secret, options.expiresIn !== undefined ? {
+            expiresIn: options.expiresIn
+        } : undefined);
+    }
+    /**
+   * Lazily index named route descriptions. Rebuilt while empty (routes may not
+   * be built yet), cached once populated.
+   */ routes() {
+        if (this.routeMap && this.routeMap.size > 0) return this.routeMap;
+        const map = new Map();
+        for (const description of this.routeManager.getRouteDescriptions()){
+            if (description.name && !map.has(description.name)) {
+                map.set(description.name, description);
+            }
+        }
+        this.routeMap = map;
+        return map;
+    }
+}
+UrlGeneratorService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(RouteManager)),
+    _ts_param(1, Optional()),
+    _ts_param(1, Inject(URL_SIGNING_SECRET)),
+    _ts_param(2, Optional()),
+    _ts_param(2, Inject(CONFIG_ENV)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof RouteManager === "undefined" ? Object : RouteManager,
+        String,
+        typeof Record === "undefined" ? Object : Record
+    ])
+], UrlGeneratorService);

package/dist/index.d.ts

@@ -10,14 +10,17 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './container/index';
 export type { RouteDescription } from './http/route.manager';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
-export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, } from './http/index';
+export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET, } from './http/index';
+export type { RouteOptions, UrlForOptions, SignedUrlGenerateOptions, VelaRouteMap, RouteName, RouteParams, } from './http/index';
+export { signUrl, verifySignedUrl } from './crypto/signed-url';
+export type { SignedUrlOptions } from './crypto/signed-url';
 export { REQUEST_CONTEXT } from './http/request-context';
 export type { RequestContext } from './http/request-context';
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext, } from './http/ambient';
 export { Logger, LogLevel } from './services/index';
 export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './services/index';
-export { ConfigModule, ConfigService, CONFIG_OPTIONS } from './config/index';
-export type { ConfigModuleOptions } from './config/index';
+export { ConfigModule, ConfigService, ConfigStore, CONFIG_OPTIONS, CONFIG_ENV, registerAs, } from './config/index';
+export type { ConfigModuleOptions, ConfigSchema, ConfigNamespace, AnyConfigNamespace, InferConfigType, ConfigType, ConfigPath, ConfigPathValue, } from './config/index';
 export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } from './fetch/index';
 export type { HttpModuleOptions, HttpResponse, HttpRequestConfig } from './fetch/index';
 export { CorsModule, CORS_OPTIONS } from './cors/index';
@@ -28,8 +31,8 @@ export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_E
 export type { EventHandler, OnEventMetadata } from './event-emitter/index';
 export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA, } from './schedule/index';
 export type { RegisteredCronJob, RegisteredIntervalJob, CronMetadata, IntervalMetadata, CronMatcher, } from './schedule/index';
-export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsDispatcher, WsException, WS_SERVER, } from './websocket/index';
-export type { WebSocketModuleOptions, WsClient, WsServer, WsMessage, WsResponse, WsExecutionContext, WsArgumentsHost, BroadcastCommand, SyncDriver, RoomRegistry, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket/index';
+export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, ReservedWsEvent, WsDispatcher, WsException, WS_SERVER, RESERVED_WS_EVENT_PREFIX, } from './websocket/index';
+export type { WebSocketModuleOptions, WsClient, WsServer, WsMessage, WsResponse, ReservedWsEventMetadata, ReservedWsEventHandler, WsExecutionContext, WsArgumentsHost, BroadcastCommand, SyncDriver, RoomRegistry, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket/index';
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator, } from './health/index';
 export type { HealthCheckResult, HealthCheckStatus, HealthIndicatorResult, HealthIndicatorFunction, ResponseCheckCallback, HttpPingOptions, } from './health/index';
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA, } from './throttler/index';

package/dist/index.js

@@ -11,7 +11,9 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
-export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators } from "./http/index.js";
+export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET } from "./http/index.js";
+// Edge-safe HMAC signed-URL primitives (also re-exported from `@velajs/vela/storage`)
+export { signUrl, verifySignedUrl } from "./crypto/signed-url.js";
 // Request-scoped context primitive
 export { REQUEST_CONTEXT } from "./http/request-context.js";
 // Opt-in ambient container access (ALS via hono/context-storage)
@@ -19,7 +21,7 @@ export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext }
 // Services
 export { Logger, LogLevel } from "./services/index.js";
 // Config
-export { ConfigModule, ConfigService, CONFIG_OPTIONS } from "./config/index.js";
+export { ConfigModule, ConfigService, ConfigStore, CONFIG_OPTIONS, CONFIG_ENV, registerAs } from "./config/index.js";
 // HTTP Client
 export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } from "./fetch/index.js";
 // CORS
@@ -31,7 +33,7 @@ export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_E
 // Schedule
 export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA } from "./schedule/index.js";
 // WebSocket (edge-safe core; transport-facing internals live at @velajs/vela/websocket)
-export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsDispatcher, WsException, WS_SERVER } from "./websocket/index.js";
+export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, ReservedWsEvent, WsDispatcher, WsException, WS_SERVER, RESERVED_WS_EVENT_PREFIX } from "./websocket/index.js";
 // Health
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator } from "./health/index.js";
 // Throttler

package/dist/live/index.d.ts

@@ -0,0 +1,12 @@
+export { LiveModule } from './live.module';
+export { LiveResolver, LiveQuery, getLiveQueries } from './live.decorators';
+export { LiveEngine, LIVE_SUBS_DATA_KEY, readPersistedLiveSubscriptions } from './live.engine';
+export { LiveInvalidation, localLive, stampCommitHeaders } from './live.invalidation';
+export { InMemoryCursorLog } from './live.cursor';
+export { encodeSubscriptionUpdate } from './live.delta';
+export { PresenceService, PresenceResolver, presenceTag, PRESENCE_ROSTER_QUERY } from './presence';
+export type { PresenceMember } from './presence';
+export { LIVE_DRIVER, LIVE_CURSOR_LOG, LIVE_MODULE_OPTIONS, LIVE_RESOLVER_METADATA, LIVE_QUERY_METADATA, } from './live.tokens';
+export type { CommitStamp, CursorLog, InvalidationCommand, LiveDriver, LiveEntrypointMeta, LiveIdentity, LiveInvalidationSink, LiveModuleOptions, LivePresenceOptions, LiveQueryContext, LiveQueryMetadata, LiveQueryOptions, LiveResolverMetadata, ResumeVerdict, SubscriptionRecord, } from './live.types';
+export { LIVE_PROTOCOL, LIVE_EVENT, LIVE_ERROR_CODES, COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, DEFAULT_KEY_FIELD, encodeLiveEnvelope, encodeLiveFrame, readLiveEnvelope, isClientLiveFrame, isServerLiveFrame, encodeListDelta, applyListDelta, } from '@velajs/live-protocol';
+export type { ClientLiveFrame, LiveFrame, RowOp, ServerLiveFrame } from '@velajs/live-protocol';

package/dist/live/index.js

@@ -0,0 +1,16 @@
+// @velajs/vela/live — first-party live-query subsystem (tag-based realtime
+// reactivity), authored entirely on the public API plus the shared wire
+// package @velajs/live-protocol (the live-openness audit test enforces it).
+// Subpath-only, like @velajs/vela/queue: the main barrel stays lean and the
+// name stays free for platform packages.
+export { LiveModule } from "./live.module.js";
+export { LiveResolver, LiveQuery, getLiveQueries } from "./live.decorators.js";
+export { LiveEngine, LIVE_SUBS_DATA_KEY, readPersistedLiveSubscriptions } from "./live.engine.js";
+export { LiveInvalidation, localLive, stampCommitHeaders } from "./live.invalidation.js";
+export { InMemoryCursorLog } from "./live.cursor.js";
+export { encodeSubscriptionUpdate } from "./live.delta.js";
+export { PresenceService, PresenceResolver, presenceTag, PRESENCE_ROSTER_QUERY } from "./presence.js";
+export { LIVE_DRIVER, LIVE_CURSOR_LOG, LIVE_MODULE_OPTIONS, LIVE_RESOLVER_METADATA, LIVE_QUERY_METADATA } from "./live.tokens.js";
+// The wire contract (frames, delta codec, headers) is re-exported so app code
+// and transports need a single import surface.
+export { LIVE_PROTOCOL, LIVE_EVENT, LIVE_ERROR_CODES, COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, DEFAULT_KEY_FIELD, encodeLiveEnvelope, encodeLiveFrame, readLiveEnvelope, isClientLiveFrame, isServerLiveFrame, encodeListDelta, applyListDelta } from "@velajs/live-protocol";

package/dist/live/live.cursor.d.ts

@@ -0,0 +1,22 @@
+import type { CommitStamp, CursorLog, ResumeVerdict } from './live.types';
+/**
+ * The in-core `CursorLog`: a bounded in-memory ring, epoch minted per process
+ * (Web Crypto). A restart rolls the epoch, so every reconnecting client falls
+ * back to snapshot — exactly the documented node/dev semantics. Within one
+ * process lifetime resume works for gaps the ring still covers; a trimmed gap
+ * degrades to snapshot (mirrors lunora's CDC retention rule,
+ * `ctx-db-cdc.ts` — retention gap → snapshot).
+ *
+ * The Cloudflare transport replaces this with a Durable-Object SQLite log so
+ * resume survives hibernation and eviction.
+ */
+export declare class InMemoryCursorLog implements CursorLog {
+    private readonly maxEntries;
+    private readonly epoch;
+    private readonly entries;
+    private seq;
+    constructor(maxEntries?: number);
+    append(tags: string[]): CommitStamp;
+    current(): CommitStamp;
+    evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict;
+}