tempest-express-sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -3,10 +3,11 @@ export { z } from 'zod';
 import * as tempest_db_js from 'tempest-db-js';
 import { Model, ModelClass, BaseRepository, InferModel, WhereInput, InferInsert, PaginationFilter as PaginationFilter$1, PaginationResult } from 'tempest-db-js';
 export { AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseRepository, BelongsTo, ColType, Column, ColumnFlags, CompiledQuery, CondNode, Condition, DeleteBuilder, DeleteNode, Dialect, EngineOptions, Executable, HasMany, InferInsert, InferModel, InsertBuilder, InsertNode, Model, ModelClass, NoResultError, NodeSqliteDriver, Operator, OrderTerm, PaginationResult, ParsedDatabaseUrl, PostgresDialect, QueryNode, RecordNotFound, Relation, RelationValue, PaginationFilter as RepositoryPaginationFilter, Returning, RowOf, SelectBuilder, SelectNode, SortDirection, SqliteDialect, SyncEngine, SyncSession, UpdateBuilder, UpdateNode, WhereArg, WhereInput, WithRelations, and, belongsTo, column, columnsOf, createEngine, createSyncEngine, del, detectDialect, getDialect, hasMany, insert, join, loadRelations, not, or, parseDatabaseUrl, select, sql, update } from 'tempest-db-js';
-import { Request, RequestHandler, Router, ErrorRequestHandler, Express } from 'express';
+import { RequestHandler, Request, Response, Router, ErrorRequestHandler, Express } from 'express';
+import * as ws from 'ws';
+import { Server } from 'node:http';
 import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
 export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
-import { Server } from 'node:http';
 
 /**
  * Request-scoped context propagation via `AsyncLocalStorage`.
@@ -1129,6 +1130,751 @@ declare class AttemptThrottle {
     reset(key: string): Promise<void>;
 }
 
+/**
+ * Cache managers, mirroring `cache.redis_manager`.
+ *
+ * A narrow async cache interface ({@link CacheManager}) with two backends: an
+ * in-process {@link MemoryCacheManager} (dev/tests/single replica) and a
+ * {@link RedisCacheManager} backed by the optional `redis` peer (lazily
+ * imported, like the auth helpers). Values are JSON-serialized.
+ */
+/** Narrow async cache surface every backend implements. */
+interface CacheManager {
+    /** Read a value by key, or `null` when missing/expired. */
+    get<T>(key: string): Promise<T | null>;
+    /** Write a value with an optional TTL in seconds. */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /** Delete a key. Idempotent. */
+    delete(key: string): Promise<void>;
+    /** Whether a live (non-expired) value exists for `key`. */
+    has(key: string): Promise<boolean>;
+    /** Remove every entry. */
+    clear(): Promise<void>;
+}
+/** In-process {@link CacheManager} backed by a `Map`, with lazy TTL expiry. */
+declare class MemoryCacheManager implements CacheManager {
+    private readonly store;
+    private live;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+}
+/** A minimal subset of the `redis` client this manager relies on. */
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        EX?: number;
+    }): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    exists(key: string): Promise<number>;
+    flushDb(): Promise<unknown>;
+}
+/** Redis-backed {@link CacheManager}. Pass a connected `redis` v4 client. */
+declare class RedisCacheManager implements CacheManager {
+    private readonly client;
+    private readonly prefix;
+    /**
+     * @param client - A connected `redis` (node-redis v4) client or compatible.
+     * @param prefix - Optional key prefix applied to every operation.
+     */
+    constructor(client: RedisLike, prefix?: string);
+    private key;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Read-through memoization helper, mirroring `cache.decorator.cached`.
+ *
+ * Wraps an async function so its result is cached under a derived key. On a hit
+ * the cached value is returned without calling the function; on a miss the
+ * function runs and its result is stored with an optional TTL.
+ */
+
+/** Options for {@link cached}. */
+interface CachedOptions<A extends unknown[]> {
+    /** The cache backend to read/write. */
+    manager: CacheManager;
+    /** Build the cache key from the call arguments. */
+    key: (...args: A) => string;
+    /** TTL in seconds for stored values. Omit for no expiry. */
+    ttlSeconds?: number;
+}
+/**
+ * Wrap an async function with read-through caching.
+ *
+ * @param fn - The async function to memoize.
+ * @param options - Cache backend, key builder and optional TTL.
+ * @returns A function with the same signature, served from cache when possible.
+ *
+ * @example
+ * ```ts
+ * const getUser = cached(fetchUser, {
+ *   manager,
+ *   key: (id: string) => `user:${id}`,
+ *   ttlSeconds: 60,
+ * });
+ * ```
+ */
+declare function cached<A extends unknown[], R>(fn: (...args: A) => Promise<R>, options: CachedOptions<A>): (...args: A) => Promise<R>;
+
+/**
+ * Session model + store, mirroring `sessions.store` / `sessions.schemas`.
+ *
+ * Sessions are keyed by the SHA-256 hash of the opaque cookie value, so a leak
+ * of the store yields no reusable cookies. The {@link SessionStore} interface is
+ * narrow; {@link MemorySessionStore} is the in-process implementation for
+ * dev/tests/single-replica (a Redis store is a planned follow-up).
+ */
+/** A persisted session row. */
+interface Session {
+    /** SHA-256 hash of the opaque cookie value (the store key). */
+    idHash: string;
+    /** The owning user id. */
+    userId: string;
+    /** Arbitrary JSON-serializable session payload. */
+    data: Record<string, unknown>;
+    /** Creation timestamp (epoch ms). */
+    createdAt: number;
+    /** Expiry timestamp (epoch ms). */
+    expiresAt: number;
+}
+/** Persistence port every session backend implements. */
+interface SessionStore {
+    /** Return the live session for `idHash`, or `null` when missing/expired. */
+    get(idHash: string): Promise<Session | null>;
+    /** Persist or overwrite a session. */
+    set(session: Session): Promise<void>;
+    /** Remove a single session. Idempotent. */
+    delete(idHash: string): Promise<void>;
+    /** Remove every session for `userId`; returns the count deleted. */
+    deleteByUser(userId: string): Promise<number>;
+    /** Return every live session for `userId` (oldest first). */
+    listByUser(userId: string): Promise<Session[]>;
+}
+/** In-process {@link SessionStore} with a secondary user index. */
+declare class MemorySessionStore implements SessionStore {
+    private readonly byHash;
+    private live;
+    get(idHash: string): Promise<Session | null>;
+    set(session: Session): Promise<void>;
+    delete(idHash: string): Promise<void>;
+    deleteByUser(userId: string): Promise<number>;
+    listByUser(userId: string): Promise<Session[]>;
+}
+
+/**
+ * Session service, mirroring `sessions.service`.
+ *
+ * Issues opaque session cookies, persists only their SHA-256 hash, and resolves
+ * an incoming cookie back to a live {@link Session}. Built on the SDK's opaque
+ * token helpers so the store never holds a usable cookie value.
+ */
+
+/** Options for {@link SessionService}. */
+interface SessionServiceOptions {
+    /** The backing store. */
+    store: SessionStore;
+    /** Default session lifetime in seconds. Default 604800 (7 days). */
+    ttlSeconds?: number;
+}
+/** A freshly created session and its one-time plaintext cookie value. */
+interface IssuedSession {
+    /** The opaque cookie value to set on the client (shown once). */
+    token: string;
+    /** The persisted session row. */
+    session: Session;
+}
+declare class SessionService {
+    private readonly store;
+    private readonly ttlSeconds;
+    /**
+     * @param options - Store and default TTL.
+     */
+    constructor(options: SessionServiceOptions);
+    /**
+     * Create a session for `userId` and return its one-time cookie value.
+     *
+     * @param userId - The owning user id.
+     * @param data - Arbitrary session payload.
+     * @param ttlSeconds - Override the default lifetime.
+     * @returns The plaintext token (set as a cookie) and the stored session.
+     */
+    create(userId: string, data?: Record<string, unknown>, ttlSeconds?: number): Promise<IssuedSession>;
+    /**
+     * Resolve an opaque cookie value to its live session.
+     *
+     * @param token - The plaintext cookie value.
+     * @returns The session, or `null` when missing/expired.
+     */
+    resolve(token: string): Promise<Session | null>;
+    /**
+     * Revoke a single session by its cookie value.
+     *
+     * @param token - The plaintext cookie value.
+     */
+    destroy(token: string): Promise<void>;
+    /**
+     * Revoke every session a user owns (global logout).
+     *
+     * @param userId - The user id.
+     * @returns The number of sessions removed.
+     */
+    destroyByUser(userId: string): Promise<number>;
+    /**
+     * List a user's live sessions (e.g. an "active devices" view).
+     *
+     * @param userId - The user id.
+     * @returns The user's sessions, oldest first.
+     */
+    listByUser(userId: string): Promise<Session[]>;
+}
+
+/**
+ * Session middleware, mirroring `sessions.middleware`.
+ *
+ * Reads the session cookie, resolves it to a live {@link Session} via the
+ * {@link SessionService}, and attaches it to `req.session` (or `null` when
+ * absent/expired). Pairs with {@link makeJwtAuthMiddleware} for JWT auth; use
+ * whichever model fits the surface.
+ */
+
+declare global {
+    namespace Express {
+        /** The live session for this request, populated by the middleware. */
+        interface Request {
+            session?: Session | null;
+        }
+    }
+}
+/** Parse the `Cookie` header into a name → value map. */
+declare function parseCookies(header: string | undefined): Record<string, string>;
+/** Read the session cookie value from a request, or `null`. */
+declare function sessionCookie(req: Request, cookieName: string): string | null;
+/** Options for {@link makeSessionMiddleware}. */
+interface SessionMiddlewareOptions {
+    /** Cookie name carrying the opaque session id. Default `sid`. */
+    cookieName?: string;
+}
+/**
+ * Build middleware that resolves the session cookie into `req.session`.
+ *
+ * @param service - The session service used to resolve cookies.
+ * @param options - Cookie name.
+ * @returns An Express middleware.
+ */
+declare function makeSessionMiddleware(service: SessionService, options?: SessionMiddlewareOptions): RequestHandler;
+
+/**
+ * Server-Sent Events primitives, mirroring `sse.event_stream`.
+ *
+ * {@link ServerSentEvent} encodes the SSE wire format; {@link EventStream} is a
+ * per-subscriber push queue exposed as an async iterator with an optional
+ * heartbeat; {@link sseResponse} wires a stream to an Express response.
+ */
+
+/** A single Server-Sent Event. */
+interface ServerSentEventInit {
+    /** The event payload (serialized to one or more `data:` lines). */
+    data: string;
+    /** Optional event name (`event:` line). */
+    event?: string;
+    /** Optional event id (`id:` line). */
+    id?: string;
+    /** Optional reconnection hint in ms (`retry:` line). */
+    retry?: number;
+}
+/** An SSE event that can encode itself to the wire format. */
+declare class ServerSentEvent {
+    private readonly init;
+    constructor(init: ServerSentEventInit);
+    /**
+     * Encode to the SSE wire format (terminated by a blank line).
+     *
+     * @returns The encoded event block.
+     */
+    encode(): string;
+}
+/** Options for {@link EventStream}. */
+interface EventStreamOptions {
+    /** Heartbeat interval in seconds (comment ping). `null` disables. Default 15. */
+    heartbeatSeconds?: number | null;
+}
+/** A single subscriber's event queue, consumable as an async iterator. */
+declare class EventStream {
+    private readonly queue;
+    private waiter;
+    private closed;
+    private readonly heartbeatSeconds;
+    /**
+     * @param options - Heartbeat configuration.
+     */
+    constructor(options?: EventStreamOptions);
+    /** Enqueue raw SSE-encoded text and wake the iterator. */
+    private push;
+    /**
+     * Publish a data payload as an SSE event.
+     *
+     * @param data - The payload; objects are JSON-encoded.
+     * @param event - Optional event name.
+     */
+    publish(data: unknown, event?: string): void;
+    /** Publish a pre-built {@link ServerSentEvent}. */
+    publishEvent(event: ServerSentEvent): void;
+    /** Close the stream; the iterator finishes after draining. */
+    close(): void;
+    /**
+     * Async iterator yielding encoded SSE chunks, with periodic heartbeats.
+     *
+     * @returns An async iterator of encoded event strings.
+     */
+    stream(): AsyncIterator<string> & AsyncIterable<string>;
+}
+/**
+ * Stream an {@link EventStream} to an Express response as `text/event-stream`.
+ *
+ * Sets the SSE headers, writes each encoded chunk, and closes the stream when
+ * the client disconnects.
+ *
+ * @param req - The Express request (used to detect disconnect).
+ * @param res - The Express response to stream into.
+ * @param stream - The event stream to drain.
+ */
+declare function sseResponse(req: Request, res: Response, stream: EventStream): Promise<void>;
+
+/**
+ * In-process SSE broker, mirroring `sse.broker.SSEBroker`.
+ *
+ * Tracks subscribers per channel and fans published events out to every live
+ * {@link EventStream} on that channel. Single-process (no cross-replica
+ * transport yet — a Redis pub/sub backend is a planned follow-up).
+ */
+
+/** Fan-out hub mapping channels to subscriber streams. */
+declare class SSEBroker {
+    private readonly streamOptions;
+    private readonly channels;
+    /**
+     * @param streamOptions - Options applied to every {@link EventStream} created
+     *   by {@link register} (e.g. heartbeat interval).
+     */
+    constructor(streamOptions?: EventStreamOptions);
+    /**
+     * Register a new subscriber stream on `channel`.
+     *
+     * @param channel - The channel name.
+     * @returns A fresh {@link EventStream} to serve to the subscriber.
+     */
+    register(channel: string): EventStream;
+    /**
+     * Remove a subscriber stream from `channel` and close it.
+     *
+     * @param channel - The channel name.
+     * @param stream - The stream to remove.
+     */
+    unregister(channel: string, stream: EventStream): void;
+    /**
+     * Number of live subscribers on `channel`.
+     *
+     * @param channel - The channel name.
+     * @returns The subscriber count.
+     */
+    localSubscribers(channel: string): number;
+    /**
+     * Publish an event to every subscriber on `channel`.
+     *
+     * @param channel - The channel name.
+     * @param data - The payload (objects are JSON-encoded).
+     * @param event - Optional event name.
+     * @returns The number of subscribers the event was delivered to.
+     */
+    publish(channel: string, data: unknown, event?: string): number;
+}
+
+/** WebSocket message envelope, mirroring `websockets.schemas`. */
+
+/** The canonical message envelope exchanged over a socket. */
+declare const wsEnvelopeSchema: z.ZodObject<{
+    type: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    data?: unknown;
+}, {
+    type: string;
+    data?: unknown;
+}>;
+/** A typed message envelope. */
+type WSEnvelope = z.infer<typeof wsEnvelopeSchema>;
+
+/**
+ * In-process connection hub, mirroring `websockets.hub.WebSocketHub`.
+ *
+ * Transport-agnostic: it tracks {@link WebSocketLike} connections (anything with
+ * `send`/`close`) so it works with the `ws` package or any compatible socket.
+ * Supports per-user delivery, topic subscriptions, broadcast and a per-user
+ * connection cap with oldest-eviction.
+ */
+
+/** The minimal socket surface the hub needs. */
+interface WebSocketLike {
+    /** Send a text frame. */
+    send(data: string): void;
+    /** Close the socket, optionally with a status code. */
+    close(code?: number): void;
+}
+/** A registered live connection. */
+interface WebSocketConnection {
+    /** Unique connection id. */
+    id: string;
+    /** The owning user id. */
+    userId: string;
+    /** The underlying socket. */
+    ws: WebSocketLike;
+    /** Topics this connection is subscribed to. */
+    topics: Set<string>;
+}
+/** Options for {@link WebSocketHub}. */
+interface WebSocketHubOptions {
+    /** Max simultaneous connections per user (oldest evicted). Default 5. */
+    maxPerUser?: number;
+}
+declare class WebSocketHub {
+    private readonly byId;
+    private readonly byUser;
+    private readonly maxPerUser;
+    /**
+     * @param options - Per-user connection cap.
+     */
+    constructor(options?: WebSocketHubOptions);
+    /**
+     * Register a new connection for `userId`, evicting the oldest if over cap.
+     *
+     * @param userId - The owning user id.
+     * @param ws - The socket to register.
+     * @returns The created connection record.
+     */
+    register(userId: string, ws: WebSocketLike): WebSocketConnection;
+    /**
+     * Remove a connection and close its socket.
+     *
+     * @param connectionId - The connection id.
+     * @param code - Optional WebSocket close code.
+     */
+    unregister(connectionId: string, code?: number): void;
+    /** Subscribe a connection to a topic. */
+    subscribe(connectionId: string, topic: string): void;
+    /** Unsubscribe a connection from a topic. */
+    unsubscribe(connectionId: string, topic: string): void;
+    /** Serialize and send an envelope to a single connection. */
+    private deliver;
+    /**
+     * Send an envelope to every connection of `userId`.
+     *
+     * @param userId - The target user.
+     * @param envelope - The message envelope.
+     * @returns The number of connections delivered to.
+     */
+    sendTo(userId: string, envelope: WSEnvelope): number;
+    /**
+     * Broadcast an envelope to all connections, or only a topic's subscribers.
+     *
+     * @param envelope - The message envelope.
+     * @param topic - Optional topic to scope the broadcast.
+     * @returns The number of connections delivered to.
+     */
+    broadcast(envelope: WSEnvelope, topic?: string): number;
+    /** The set of users with at least one live connection. */
+    onlineUsers(): Set<string>;
+    /** Total live connection count. */
+    connectionCount(): number;
+    /** Number of connections subscribed to `topic`. */
+    topicCount(topic: string): number;
+}
+
+/** Handshake info passed to the authenticator. */
+interface HandshakeInfo {
+    /** The request URL (includes the query string, e.g. `/ws?token=…`). */
+    url: string;
+    /** The raw request headers. */
+    headers: Record<string, string | string[] | undefined>;
+}
+/** Options for {@link attachWebSocketHub}. */
+interface AttachWebSocketOptions {
+    /** Path the WebSocket server listens on. Default `/ws`. */
+    path?: string;
+    /**
+     * Resolve a user id from the handshake, or `null` to reject (closes 1008).
+     * Default accepts every connection as `"anonymous"`.
+     */
+    authenticate?: (info: HandshakeInfo) => Promise<string | null> | string | null;
+    /** Heartbeat interval in seconds (`0` disables). Default 30. */
+    heartbeatSeconds?: number;
+    /** Handler invoked for each inbound text message. */
+    onMessage?: (connection: WebSocketConnection, message: string) => void;
+}
+/** Read a `token` query param from a handshake URL, or `null`. */
+declare function tokenFromUrl(url: string): string | null;
+/**
+ * Attach a hub to an HTTP server over the `ws` package.
+ *
+ * @param server - The Node HTTP server (e.g. from `runServer`).
+ * @param hub - The hub to register connections into.
+ * @param options - Path, authenticator, heartbeat and message handler.
+ * @returns The created `ws` `WebSocketServer` instance.
+ * @throws {Error} When the optional `ws` peer is not installed.
+ */
+declare function attachWebSocketHub(server: Server, hub: WebSocketHub, options?: AttachWebSocketOptions): Promise<ws.WebSocketServer>;
+
+/**
+ * Message broker, mirroring `queue.manager.AsyncBrokerManager`.
+ *
+ * A narrow async pub/sub surface ({@link BrokerManager}) with two backends: an
+ * in-process {@link MemoryBroker} (dev/tests) and a {@link RabbitBroker} over the
+ * optional `amqplib` peer (lazily imported). Messages are JSON-serialized.
+ */
+/** A handler invoked for each delivered message. */
+type MessageHandler = (message: unknown) => Promise<void> | void;
+/** Narrow async pub/sub surface every backend implements. */
+interface BrokerManager {
+    /** Publish a message to a named queue. */
+    publish(queue: string, message: unknown): Promise<void>;
+    /** Subscribe to a queue; resolves to an unsubscribe function. */
+    subscribe(queue: string, handler: MessageHandler): Promise<() => Promise<void>>;
+    /** Close the broker and release resources. */
+    close(): Promise<void>;
+}
+/** In-process {@link BrokerManager} backed by handler sets. */
+declare class MemoryBroker implements BrokerManager {
+    private readonly handlers;
+    publish(queue: string, message: unknown): Promise<void>;
+    subscribe(queue: string, handler: MessageHandler): Promise<() => Promise<void>>;
+    close(): Promise<void>;
+}
+/** Options for {@link RabbitBroker}. */
+interface RabbitBrokerOptions {
+    /** AMQP connection URL, e.g. `amqp://localhost`. */
+    url: string;
+    /** Whether queues are declared durable. Default `true`. */
+    durable?: boolean;
+}
+/** RabbitMQ-backed {@link BrokerManager} over the optional `amqplib` peer. */
+declare class RabbitBroker implements BrokerManager {
+    private readonly options;
+    private connection;
+    private channel;
+    private readonly durable;
+    /**
+     * @param options - Connection URL and queue durability.
+     */
+    constructor(options: RabbitBrokerOptions);
+    /** Lazily connect and open a channel. */
+    private ready;
+    publish(queue: string, message: unknown): Promise<void>;
+    subscribe(queue: string, handler: MessageHandler): Promise<() => Promise<void>>;
+    close(): Promise<void>;
+}
+
+/**
+ * Background task manager, mirroring `tasks.manager.AsyncTaskBrokerManager`.
+ *
+ * Rides on a {@link BrokerManager}: enqueue publishes a `{ name, payload }`
+ * envelope to a task queue; a worker started with {@link TaskManager.start}
+ * consumes it and dispatches to the registered handler. Defaults to an
+ * in-process {@link MemoryBroker} so it works with zero infrastructure.
+ */
+
+/** A handler for a registered task. */
+type TaskHandler<P = unknown> = (payload: P) => Promise<void> | void;
+/** Options for {@link TaskManager}. */
+interface TaskManagerOptions {
+    /** The broker to publish/consume on. Defaults to a {@link MemoryBroker}. */
+    broker?: BrokerManager;
+    /** Queue name used for the task stream. Default `tasks`. */
+    queue?: string;
+}
+declare class TaskManager {
+    private readonly broker;
+    private readonly queue;
+    private readonly handlers;
+    private unsubscribe;
+    /**
+     * @param options - Broker and queue name.
+     */
+    constructor(options?: TaskManagerOptions);
+    /**
+     * Register a handler for a named task.
+     *
+     * @param name - The task name.
+     * @param handler - The handler invoked with the task payload.
+     */
+    register<P = unknown>(name: string, handler: TaskHandler<P>): void;
+    /**
+     * Enqueue a task by name.
+     *
+     * @param name - The registered task name.
+     * @param payload - The JSON-serializable payload.
+     */
+    enqueue(name: string, payload?: unknown): Promise<void>;
+    /**
+     * Start the worker: subscribe to the task queue and dispatch to handlers.
+     * A task with no registered handler is logged and skipped.
+     */
+    start(): Promise<void>;
+    /** Stop the worker (stops consuming; does not close the broker). */
+    stop(): Promise<void>;
+}
+
+/**
+ * Feature-flag backends, mirroring `flags.backends`.
+ *
+ * A flag resolves to a boolean given a flag name and optional context. Backends
+ * are composable — {@link CompositeFeatureFlagBackend} tries each in order and
+ * returns the first definitive answer.
+ */
+/** Arbitrary evaluation context (user id, roles, attributes). */
+type FlagContext = Record<string, unknown>;
+/** Resolves a flag to enabled/disabled, or `null` when it has no opinion. */
+interface FeatureFlagBackend {
+    /** Resolve `flag`; `null` defers to the next backend. */
+    resolve(flag: string, context?: FlagContext): Promise<boolean | null> | boolean | null;
+}
+/** Coerce a loose value (`"1"`, `"true"`, `"on"`, …) to a boolean. */
+declare function coerceFlag(value: unknown): boolean;
+/** In-memory backend backed by a `Map`, ideal for tests and overrides. */
+declare class MemoryFeatureFlagBackend implements FeatureFlagBackend {
+    private readonly flags;
+    /**
+     * @param initial - Initial flag → enabled map.
+     */
+    constructor(initial?: Record<string, boolean>);
+    /** Set or override a flag. */
+    set(flag: string, enabled: boolean): void;
+    resolve(flag: string): boolean | null;
+}
+/** Reads flags from env vars, e.g. flag `new-ui` → `FLAG_NEW_UI`. */
+declare class EnvFeatureFlagBackend implements FeatureFlagBackend {
+    private readonly env;
+    private readonly prefix;
+    /**
+     * @param env - Environment source (defaults to `process.env`).
+     * @param prefix - Env var prefix. Default `FLAG_`.
+     */
+    constructor(env?: NodeJS.ProcessEnv, prefix?: string);
+    private key;
+    resolve(flag: string): boolean | null;
+}
+/** Tries each backend in order; first non-`null` answer wins. */
+declare class CompositeFeatureFlagBackend implements FeatureFlagBackend {
+    private readonly backends;
+    /**
+     * @param backends - Backends in priority order.
+     */
+    constructor(backends: FeatureFlagBackend[]);
+    resolve(flag: string, context?: FlagContext): Promise<boolean | null>;
+}
+
+/**
+ * Feature-flag service + Express guard, mirroring `flags.service` /
+ * `flags.dependencies`.
+ */
+
+/** Evaluates flags against a backend, applying a default when undecided. */
+declare class FeatureFlags {
+    private readonly backend;
+    private readonly defaultEnabled;
+    /**
+     * @param backend - The resolving backend.
+     * @param defaultEnabled - Value used when the backend returns `null`.
+     */
+    constructor(backend: FeatureFlagBackend, defaultEnabled?: boolean);
+    /**
+     * Whether `flag` is enabled for the given context.
+     *
+     * @param flag - The flag name.
+     * @param context - Optional evaluation context.
+     * @returns `true` when enabled (or default when the backend is undecided).
+     */
+    isEnabled(flag: string, context?: FlagContext): Promise<boolean>;
+}
+/**
+ * Build middleware that rejects with 404 when `flag` is disabled (hiding the
+ * route entirely, the common kill-switch behavior).
+ *
+ * @param flags - The flag service.
+ * @param flag - The flag name to gate on.
+ * @returns An Express middleware.
+ */
+declare function makeFlagGuard(flags: FeatureFlags, flag: string): RequestHandler;
+
+/**
+ * File storage abstraction, mirroring `utils.storage_backends` / `utils.upload`.
+ *
+ * A narrow {@link UploadStorage} interface with a filesystem-backed
+ * {@link LocalUploadStorage}. For S3/MinIO, implement the same interface over
+ * your client (the interface intentionally avoids a hard cloud dependency).
+ */
+/** The result of persisting an object. */
+interface UploadResult {
+    /** The storage key (path within the backend). */
+    key: string;
+    /** A URL the object can be served from. */
+    url: string;
+    /** The stored byte size. */
+    size: number;
+    /** The declared content type, when known. */
+    contentType?: string;
+}
+/** Options for {@link UploadStorage.save}. */
+interface SaveOptions {
+    /** MIME type recorded on the result. */
+    contentType?: string;
+}
+/** Narrow object-storage surface backends implement. */
+interface UploadStorage {
+    /** Persist bytes under `key`, returning metadata. */
+    save(key: string, data: Uint8Array, options?: SaveOptions): Promise<UploadResult>;
+    /** Read bytes back by key. */
+    read(key: string): Promise<Buffer>;
+    /** Delete an object. Idempotent. */
+    delete(key: string): Promise<void>;
+    /** The URL an object is served from. */
+    url(key: string): string;
+}
+/** Options for {@link LocalUploadStorage}. */
+interface LocalUploadStorageOptions {
+    /** Filesystem root every key is written under. */
+    root: string;
+    /** Public base URL prefix for {@link LocalUploadStorage.url}. Default `""`. */
+    baseUrl?: string;
+}
+/** Filesystem-backed {@link UploadStorage} for local/dev or single-host setups. */
+declare class LocalUploadStorage implements UploadStorage {
+    private readonly root;
+    private readonly baseUrl;
+    /**
+     * @param options - Filesystem root and public base URL.
+     */
+    constructor(options: LocalUploadStorageOptions);
+    save(key: string, data: Uint8Array, options?: SaveOptions): Promise<UploadResult>;
+    read(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    url(key: string): string;
+}
+/**
+ * Build a `Content-Disposition` header value.
+ *
+ * @param filename - The download filename.
+ * @param inline - When `true`, use `inline`; otherwise `attachment`.
+ * @returns The header value (RFC 5987 `filename*` encoded).
+ */
+declare function buildContentDisposition(filename: string, inline?: boolean): string;
+
 /**
  * Auth DTOs (Zod), mirroring `auth.schemas`.
  *
@@ -1197,14 +1943,14 @@ declare const userPublicSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     id: string;
     isActive: boolean;
-    email: string;
     name: string | null;
+    email: string;
     roles: string[];
 }, {
     id: string;
     isActive: boolean;
-    email: string;
     name: string | null;
+    email: string;
     roles: string[];
 }>;
 /** Response body for `POST /auth/signup` and `POST /auth/login`. */
@@ -1218,14 +1964,14 @@ declare const authResponseSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         id: string;
         isActive: boolean;
-        email: string;
         name: string | null;
+        email: string;
         roles: string[];
     }, {
         id: string;
         isActive: boolean;
-        email: string;
         name: string | null;
+        email: string;
         roles: string[];
     }>;
     tokens: z.ZodObject<{
@@ -1248,8 +1994,8 @@ declare const authResponseSchema: z.ZodObject<{
     user: {
         id: string;
         isActive: boolean;
-        email: string;
         name: string | null;
+        email: string;
         roles: string[];
     };
     tokens: {
@@ -1262,8 +2008,8 @@ declare const authResponseSchema: z.ZodObject<{
     user: {
         id: string;
         isActive: boolean;
-        email: string;
         name: string | null;
+        email: string;
         roles: string[];
     };
     tokens: {
@@ -1721,6 +2467,6 @@ interface RunServerOptions {
 declare function runServer(app: Express, options?: RunServerOptions): Promise<Server>;
 
 /** The installed SDK version. Single source of truth for the barrel + CLI. */
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.0";
 
-export { AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CatalogData, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type Enum, type EnumHelpers, type EnumSpec, type ExceptionDetails, ExpiredTokenException, ForbiddenException, type GenerateOpenApiOptions, HTTP_500_MARKER, type HealthCheck, type HealthRouterOptions, InvalidTokenException, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, type LogExtra, type LogLevel, type LoginInput, MemoryThrottleBackend, MessageCatalog, NotFoundException, type OpenApiDocument, type OpenApiInfo, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, type RunServerOptions, type SignupInput, type StateBR, type SwaggerOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, cepField, citiesByUf, cnpjField, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAppExceptionHandler, makeAuthRouter, makeHealthRouter, makeJwtAuthMiddleware, makeUnhandledExceptionHandler, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, setRequestId, signupSchema, statesByRegion, tableNameFor, toDict, toUtc, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken };
+export { AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CacheManager, type CachedOptions, type CatalogData, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GenerateOpenApiOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, NotFoundException, type OpenApiDocument, type OpenApiInfo, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, type RunServerOptions, SSEBroker, type SaveOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type TaskHandler, TaskManager, type TaskManagerOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeUnhandledExceptionHandler, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken, wsEnvelopeSchema };