tempest-express-sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,4 +1,4 @@
-export { VERSION } from './chunk-2NB7ZA7G.js';
+export { VERSION } from './chunk-6QNSLBL3.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV31, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
 export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
@@ -7,6 +7,8 @@ export { z } from 'zod';
 import { Model, column, sql } from 'tempest-db-js';
 export { AsyncEngine, AsyncResult, AsyncSession, BaseRepository, Column, DeleteBuilder, InsertBuilder, Model, NoResultError, NodeSqliteDriver, PostgresDialect, RecordNotFound, SelectBuilder, SqliteDialect, SyncEngine, SyncSession, UpdateBuilder, and, belongsTo, column, columnsOf, createEngine, createSyncEngine, del, detectDialect, getDialect, hasMany, insert, join, loadRelations, not, or, parseDatabaseUrl, select, sql, update } from 'tempest-db-js';
 import { createHash, randomBytes, timingSafeEqual, randomUUID } from 'crypto';
+import { mkdir, writeFile, readFile, rm } from 'fs/promises';
+import { join, dirname } from 'path';
 import express2, { Router } from 'express';
 import { getAbsoluteFSPath } from 'swagger-ui-dist';
 
@@ -6750,6 +6752,846 @@ var AttemptThrottle = class {
   }
 };
 
+// src/cache/manager.ts
+var MemoryCacheManager = class {
+  store = /* @__PURE__ */ new Map();
+  live(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry;
+  }
+  async get(key) {
+    const entry = this.live(key);
+    return entry ? JSON.parse(entry.value) : null;
+  }
+  async set(key, value, ttlSeconds) {
+    this.store.set(key, {
+      value: JSON.stringify(value),
+      expiresAt: ttlSeconds !== void 0 ? Date.now() + ttlSeconds * 1e3 : null
+    });
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  async has(key) {
+    return this.live(key) !== null;
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+var RedisCacheManager = class {
+  /**
+   * @param client - A connected `redis` (node-redis v4) client or compatible.
+   * @param prefix - Optional key prefix applied to every operation.
+   */
+  constructor(client, prefix = "") {
+    this.client = client;
+    this.prefix = prefix;
+  }
+  client;
+  prefix;
+  key(key) {
+    return this.prefix ? `${this.prefix}${key}` : key;
+  }
+  async get(key) {
+    const raw = await this.client.get(this.key(key));
+    return raw === null ? null : JSON.parse(raw);
+  }
+  async set(key, value, ttlSeconds) {
+    const payload = JSON.stringify(value);
+    await this.client.set(
+      this.key(key),
+      payload,
+      ttlSeconds !== void 0 ? { EX: ttlSeconds } : void 0
+    );
+  }
+  async delete(key) {
+    await this.client.del(this.key(key));
+  }
+  async has(key) {
+    return await this.client.exists(this.key(key)) > 0;
+  }
+  async clear() {
+    await this.client.flushDb();
+  }
+};
+
+// src/cache/cached.ts
+function cached3(fn, options) {
+  return async (...args) => {
+    const key = options.key(...args);
+    const hit = await options.manager.get(key);
+    if (hit !== null) return hit;
+    const result = await fn(...args);
+    await options.manager.set(key, result, options.ttlSeconds);
+    return result;
+  };
+}
+
+// src/sessions/store.ts
+var MemorySessionStore = class {
+  byHash = /* @__PURE__ */ new Map();
+  live(session, idHash) {
+    if (!session) return null;
+    if (session.expiresAt <= Date.now()) {
+      this.byHash.delete(idHash);
+      return null;
+    }
+    return session;
+  }
+  async get(idHash) {
+    return this.live(this.byHash.get(idHash), idHash);
+  }
+  async set(session) {
+    this.byHash.set(session.idHash, session);
+  }
+  async delete(idHash) {
+    this.byHash.delete(idHash);
+  }
+  async deleteByUser(userId) {
+    let count = 0;
+    for (const [hash, session] of this.byHash) {
+      if (session.userId === userId) {
+        this.byHash.delete(hash);
+        count += 1;
+      }
+    }
+    return count;
+  }
+  async listByUser(userId) {
+    const now = Date.now();
+    return [...this.byHash.values()].filter((s) => s.userId === userId && s.expiresAt > now).sort((a, b) => a.createdAt - b.createdAt);
+  }
+};
+
+// src/sessions/service.ts
+var SessionService = class {
+  store;
+  ttlSeconds;
+  /**
+   * @param options - Store and default TTL.
+   */
+  constructor(options) {
+    this.store = options.store;
+    this.ttlSeconds = options.ttlSeconds ?? 60 * 60 * 24 * 7;
+  }
+  /**
+   * 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.
+   */
+  async create(userId, data = {}, ttlSeconds) {
+    const { plaintext, tokenHash } = generateOpaqueToken();
+    const now = Date.now();
+    const session = {
+      idHash: tokenHash,
+      userId,
+      data,
+      createdAt: now,
+      expiresAt: now + (ttlSeconds ?? this.ttlSeconds) * 1e3
+    };
+    await this.store.set(session);
+    return { token: plaintext, session };
+  }
+  /**
+   * Resolve an opaque cookie value to its live session.
+   *
+   * @param token - The plaintext cookie value.
+   * @returns The session, or `null` when missing/expired.
+   */
+  async resolve(token) {
+    return this.store.get(hashOpaqueToken(token));
+  }
+  /**
+   * Revoke a single session by its cookie value.
+   *
+   * @param token - The plaintext cookie value.
+   */
+  async destroy(token) {
+    await this.store.delete(hashOpaqueToken(token));
+  }
+  /**
+   * Revoke every session a user owns (global logout).
+   *
+   * @param userId - The user id.
+   * @returns The number of sessions removed.
+   */
+  async destroyByUser(userId) {
+    return this.store.deleteByUser(userId);
+  }
+  /**
+   * List a user's live sessions (e.g. an "active devices" view).
+   *
+   * @param userId - The user id.
+   * @returns The user's sessions, oldest first.
+   */
+  async listByUser(userId) {
+    return this.store.listByUser(userId);
+  }
+};
+
+// src/sessions/middleware.ts
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(";")) {
+    const index = part.indexOf("=");
+    if (index < 0) continue;
+    const name = part.slice(0, index).trim();
+    const value = part.slice(index + 1).trim();
+    if (name) out[name] = decodeURIComponent(value);
+  }
+  return out;
+}
+function sessionCookie(req, cookieName) {
+  return parseCookies(req.header("cookie") ?? void 0)[cookieName] ?? null;
+}
+function makeSessionMiddleware(service, options = {}) {
+  const cookieName = options.cookieName ?? "sid";
+  return (req, _res, next) => {
+    const token = sessionCookie(req, cookieName);
+    if (!token) {
+      req.session = null;
+      next();
+      return;
+    }
+    service.resolve(token).then((session) => {
+      req.session = session;
+      next();
+    }).catch(next);
+  };
+}
+
+// src/sse/eventStream.ts
+var ServerSentEvent = class {
+  constructor(init) {
+    this.init = init;
+  }
+  init;
+  /**
+   * Encode to the SSE wire format (terminated by a blank line).
+   *
+   * @returns The encoded event block.
+   */
+  encode() {
+    const lines = [];
+    if (this.init.event) lines.push(`event: ${this.init.event}`);
+    if (this.init.id) lines.push(`id: ${this.init.id}`);
+    if (this.init.retry !== void 0) lines.push(`retry: ${this.init.retry}`);
+    for (const line of this.init.data.split("\n")) lines.push(`data: ${line}`);
+    return `${lines.join("\n")}
+
+`;
+  }
+};
+function deferred() {
+  let resolve;
+  const promise = new Promise((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+var EventStream = class {
+  queue = [];
+  waiter = null;
+  closed = false;
+  heartbeatSeconds;
+  /**
+   * @param options - Heartbeat configuration.
+   */
+  constructor(options = {}) {
+    this.heartbeatSeconds = options.heartbeatSeconds ?? 15;
+  }
+  /** Enqueue raw SSE-encoded text and wake the iterator. */
+  push(raw) {
+    if (this.closed) return;
+    this.queue.push(raw);
+    this.waiter?.resolve();
+    this.waiter = null;
+  }
+  /**
+   * Publish a data payload as an SSE event.
+   *
+   * @param data - The payload; objects are JSON-encoded.
+   * @param event - Optional event name.
+   */
+  publish(data, event) {
+    const payload = typeof data === "string" ? data : JSON.stringify(data);
+    this.push(
+      new ServerSentEvent({ data: payload, ...event ? { event } : {} }).encode()
+    );
+  }
+  /** Publish a pre-built {@link ServerSentEvent}. */
+  publishEvent(event) {
+    this.push(event.encode());
+  }
+  /** Close the stream; the iterator finishes after draining. */
+  close() {
+    this.closed = true;
+    this.waiter?.resolve();
+    this.waiter = null;
+  }
+  /**
+   * Async iterator yielding encoded SSE chunks, with periodic heartbeats.
+   *
+   * @returns An async iterator of encoded event strings.
+   */
+  async *stream() {
+    const heartbeatMs = this.heartbeatSeconds !== null ? this.heartbeatSeconds * 1e3 : null;
+    while (!this.closed || this.queue.length > 0) {
+      if (this.queue.length > 0) {
+        yield this.queue.shift();
+        continue;
+      }
+      if (this.closed) break;
+      this.waiter = deferred();
+      if (heartbeatMs === null) {
+        await this.waiter.promise;
+      } else {
+        let timer;
+        const heartbeat = new Promise((resolve) => {
+          timer = setTimeout(resolve, heartbeatMs);
+        });
+        await Promise.race([this.waiter.promise, heartbeat]);
+        if (timer) clearTimeout(timer);
+        if (this.queue.length === 0 && !this.closed) yield ": ping\n\n";
+      }
+    }
+  }
+};
+async function sseResponse(req, res, stream) {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders?.();
+  req.on("close", () => stream.close());
+  for await (const chunk of stream.stream()) {
+    if (res.writableEnded) break;
+    res.write(chunk);
+  }
+  res.end();
+}
+
+// src/sse/broker.ts
+var SSEBroker = class {
+  /**
+   * @param streamOptions - Options applied to every {@link EventStream} created
+   *   by {@link register} (e.g. heartbeat interval).
+   */
+  constructor(streamOptions = {}) {
+    this.streamOptions = streamOptions;
+  }
+  streamOptions;
+  channels = /* @__PURE__ */ new Map();
+  /**
+   * Register a new subscriber stream on `channel`.
+   *
+   * @param channel - The channel name.
+   * @returns A fresh {@link EventStream} to serve to the subscriber.
+   */
+  register(channel) {
+    const stream = new EventStream(this.streamOptions);
+    const set = this.channels.get(channel) ?? /* @__PURE__ */ new Set();
+    set.add(stream);
+    this.channels.set(channel, set);
+    return stream;
+  }
+  /**
+   * Remove a subscriber stream from `channel` and close it.
+   *
+   * @param channel - The channel name.
+   * @param stream - The stream to remove.
+   */
+  unregister(channel, stream) {
+    const set = this.channels.get(channel);
+    if (!set) return;
+    set.delete(stream);
+    stream.close();
+    if (set.size === 0) this.channels.delete(channel);
+  }
+  /**
+   * Number of live subscribers on `channel`.
+   *
+   * @param channel - The channel name.
+   * @returns The subscriber count.
+   */
+  localSubscribers(channel) {
+    return this.channels.get(channel)?.size ?? 0;
+  }
+  /**
+   * 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, data, event) {
+    const set = this.channels.get(channel);
+    if (!set) return 0;
+    for (const stream of set) stream.publish(data, event);
+    return set.size;
+  }
+};
+
+// src/websockets/schemas.ts
+var wsEnvelopeSchema = z.object({
+  type: z.string().openapi({ description: "Message type discriminator." }),
+  data: z.unknown().optional().openapi({ description: "Arbitrary payload." })
+}).openapi("WSEnvelope");
+var WebSocketHub = class {
+  byId = /* @__PURE__ */ new Map();
+  byUser = /* @__PURE__ */ new Map();
+  maxPerUser;
+  /**
+   * @param options - Per-user connection cap.
+   */
+  constructor(options = {}) {
+    this.maxPerUser = options.maxPerUser ?? 5;
+  }
+  /**
+   * 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, ws) {
+    const connection = {
+      id: randomUUID(),
+      userId,
+      ws,
+      topics: /* @__PURE__ */ new Set()
+    };
+    this.byId.set(connection.id, connection);
+    const ids = this.byUser.get(userId) ?? /* @__PURE__ */ new Set();
+    ids.add(connection.id);
+    this.byUser.set(userId, ids);
+    if (ids.size > this.maxPerUser) {
+      const oldest = ids.values().next().value;
+      if (oldest) this.unregister(oldest, 1008);
+    }
+    return connection;
+  }
+  /**
+   * Remove a connection and close its socket.
+   *
+   * @param connectionId - The connection id.
+   * @param code - Optional WebSocket close code.
+   */
+  unregister(connectionId, code) {
+    const connection = this.byId.get(connectionId);
+    if (!connection) return;
+    this.byId.delete(connectionId);
+    const ids = this.byUser.get(connection.userId);
+    if (ids) {
+      ids.delete(connectionId);
+      if (ids.size === 0) this.byUser.delete(connection.userId);
+    }
+    try {
+      connection.ws.close(code);
+    } catch {
+    }
+  }
+  /** Subscribe a connection to a topic. */
+  subscribe(connectionId, topic) {
+    this.byId.get(connectionId)?.topics.add(topic);
+  }
+  /** Unsubscribe a connection from a topic. */
+  unsubscribe(connectionId, topic) {
+    this.byId.get(connectionId)?.topics.delete(topic);
+  }
+  /** Serialize and send an envelope to a single connection. */
+  deliver(connection, payload) {
+    try {
+      connection.ws.send(payload);
+      return true;
+    } catch {
+      this.unregister(connection.id);
+      return false;
+    }
+  }
+  /**
+   * 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, envelope) {
+    const ids = this.byUser.get(userId);
+    if (!ids) return 0;
+    const payload = JSON.stringify(envelope);
+    let count = 0;
+    for (const id of [...ids]) {
+      const connection = this.byId.get(id);
+      if (connection && this.deliver(connection, payload)) count += 1;
+    }
+    return count;
+  }
+  /**
+   * 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, topic) {
+    const payload = JSON.stringify(envelope);
+    let count = 0;
+    for (const connection of [...this.byId.values()]) {
+      if (topic && !connection.topics.has(topic)) continue;
+      if (this.deliver(connection, payload)) count += 1;
+    }
+    return count;
+  }
+  /** The set of users with at least one live connection. */
+  onlineUsers() {
+    return new Set(this.byUser.keys());
+  }
+  /** Total live connection count. */
+  connectionCount() {
+    return this.byId.size;
+  }
+  /** Number of connections subscribed to `topic`. */
+  topicCount(topic) {
+    let count = 0;
+    for (const connection of this.byId.values()) {
+      if (connection.topics.has(topic)) count += 1;
+    }
+    return count;
+  }
+};
+
+// src/websockets/attach.ts
+function tokenFromUrl(url) {
+  const query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : "";
+  return new URLSearchParams(query).get("token");
+}
+async function attachWebSocketHub(server, hub, options = {}) {
+  let ws;
+  try {
+    ws = await import('ws');
+  } catch (cause) {
+    throw new Error(
+      "attachWebSocketHub requires the 'ws' peer dependency. Install with `npm i ws`.",
+      { cause }
+    );
+  }
+  const path = options.path ?? "/ws";
+  const heartbeatMs = (options.heartbeatSeconds ?? 30) * 1e3;
+  const authenticate = options.authenticate ?? (() => "anonymous");
+  const wss = new ws.WebSocketServer({ server, path });
+  wss.on("connection", (socket, req) => {
+    void (async () => {
+      const userId = await authenticate({
+        url: req.url ?? "",
+        headers: req.headers
+      });
+      if (userId === null) {
+        socket.close(1008);
+        return;
+      }
+      const connection = hub.register(userId, socket);
+      let alive = true;
+      socket.on("pong", () => {
+        alive = true;
+      });
+      socket.on("message", (data) => {
+        options.onMessage?.(connection, String(data));
+      });
+      socket.on("close", () => {
+        alive = false;
+        hub.unregister(connection.id);
+      });
+      if (heartbeatMs > 0) {
+        const timer = setInterval(() => {
+          if (!alive) {
+            clearInterval(timer);
+            hub.unregister(connection.id);
+            return;
+          }
+          alive = false;
+          socket.ping();
+        }, heartbeatMs);
+        socket.on("close", () => clearInterval(timer));
+      }
+    })();
+  });
+  return wss;
+}
+
+// src/queue/broker.ts
+var MemoryBroker = class {
+  handlers = /* @__PURE__ */ new Map();
+  async publish(queue, message) {
+    const set = this.handlers.get(queue);
+    if (!set) return;
+    const payload = JSON.parse(JSON.stringify(message));
+    for (const handler of [...set]) await handler(payload);
+  }
+  async subscribe(queue, handler) {
+    const set = this.handlers.get(queue) ?? /* @__PURE__ */ new Set();
+    set.add(handler);
+    this.handlers.set(queue, set);
+    return async () => {
+      set.delete(handler);
+      if (set.size === 0) this.handlers.delete(queue);
+    };
+  }
+  async close() {
+    this.handlers.clear();
+  }
+};
+var RabbitBroker = class {
+  /**
+   * @param options - Connection URL and queue durability.
+   */
+  constructor(options) {
+    this.options = options;
+    this.durable = options.durable ?? true;
+  }
+  options;
+  connection = null;
+  channel = null;
+  durable;
+  /** Lazily connect and open a channel. */
+  async ready() {
+    if (this.channel) return this.channel;
+    let amqp;
+    try {
+      amqp = await import('amqplib');
+    } catch (cause) {
+      throw new Error(
+        "RabbitBroker requires the 'amqplib' peer dependency. Install with `npm i amqplib`.",
+        { cause }
+      );
+    }
+    this.connection = await amqp.connect(this.options.url);
+    this.channel = await this.connection.createChannel();
+    return this.channel;
+  }
+  async publish(queue, message) {
+    const channel = await this.ready();
+    await channel.assertQueue(queue, { durable: this.durable });
+    channel.sendToQueue(queue, Buffer.from(JSON.stringify(message)), {
+      persistent: this.durable
+    });
+  }
+  async subscribe(queue, handler) {
+    const channel = await this.ready();
+    await channel.assertQueue(queue, { durable: this.durable });
+    const { consumerTag } = await channel.consume(queue, (msg) => {
+      if (!msg) return;
+      void Promise.resolve(handler(JSON.parse(msg.content.toString()))).then(() => channel.ack(msg)).catch(() => channel.nack(msg, false, false));
+    });
+    return async () => {
+      await channel.cancel(consumerTag);
+    };
+  }
+  async close() {
+    await this.channel?.close();
+    await this.connection?.close();
+    this.channel = null;
+    this.connection = null;
+  }
+};
+
+// src/tasks/manager.ts
+var logger = new JSONLogger("tempest_express_sdk.tasks");
+var TaskManager = class {
+  broker;
+  queue;
+  handlers = /* @__PURE__ */ new Map();
+  unsubscribe = null;
+  /**
+   * @param options - Broker and queue name.
+   */
+  constructor(options = {}) {
+    this.broker = options.broker ?? new MemoryBroker();
+    this.queue = options.queue ?? "tasks";
+  }
+  /**
+   * Register a handler for a named task.
+   *
+   * @param name - The task name.
+   * @param handler - The handler invoked with the task payload.
+   */
+  register(name, handler) {
+    this.handlers.set(name, handler);
+  }
+  /**
+   * Enqueue a task by name.
+   *
+   * @param name - The registered task name.
+   * @param payload - The JSON-serializable payload.
+   */
+  async enqueue(name, payload = {}) {
+    const envelope = { name, payload };
+    await this.broker.publish(this.queue, envelope);
+  }
+  /**
+   * Start the worker: subscribe to the task queue and dispatch to handlers.
+   * A task with no registered handler is logged and skipped.
+   */
+  async start() {
+    if (this.unsubscribe) return;
+    this.unsubscribe = await this.broker.subscribe(this.queue, async (message) => {
+      const { name, payload } = message;
+      const handler = this.handlers.get(name);
+      if (!handler) {
+        logger.warning("No handler for task", { task: name });
+        return;
+      }
+      await handler(payload);
+    });
+  }
+  /** Stop the worker (stops consuming; does not close the broker). */
+  async stop() {
+    await this.unsubscribe?.();
+    this.unsubscribe = null;
+  }
+};
+
+// src/flags/backends.ts
+function coerceFlag(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") {
+    return ["1", "true", "on", "yes", "enabled"].includes(value.trim().toLowerCase());
+  }
+  return false;
+}
+var MemoryFeatureFlagBackend = class {
+  flags = /* @__PURE__ */ new Map();
+  /**
+   * @param initial - Initial flag → enabled map.
+   */
+  constructor(initial = {}) {
+    for (const [flag, enabled] of Object.entries(initial)) this.flags.set(flag, enabled);
+  }
+  /** Set or override a flag. */
+  set(flag, enabled) {
+    this.flags.set(flag, enabled);
+  }
+  resolve(flag) {
+    return this.flags.has(flag) ? this.flags.get(flag) : null;
+  }
+};
+var EnvFeatureFlagBackend = class {
+  /**
+   * @param env - Environment source (defaults to `process.env`).
+   * @param prefix - Env var prefix. Default `FLAG_`.
+   */
+  constructor(env = process.env, prefix = "FLAG_") {
+    this.env = env;
+    this.prefix = prefix;
+  }
+  env;
+  prefix;
+  key(flag) {
+    return this.prefix + flag.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+  }
+  resolve(flag) {
+    const raw = this.env[this.key(flag)];
+    return raw === void 0 ? null : coerceFlag(raw);
+  }
+};
+var CompositeFeatureFlagBackend = class {
+  /**
+   * @param backends - Backends in priority order.
+   */
+  constructor(backends) {
+    this.backends = backends;
+  }
+  backends;
+  async resolve(flag, context) {
+    for (const backend of this.backends) {
+      const answer = await backend.resolve(flag, context);
+      if (answer !== null) return answer;
+    }
+    return null;
+  }
+};
+
+// src/flags/service.ts
+var FeatureFlags = class {
+  /**
+   * @param backend - The resolving backend.
+   * @param defaultEnabled - Value used when the backend returns `null`.
+   */
+  constructor(backend, defaultEnabled = false) {
+    this.backend = backend;
+    this.defaultEnabled = defaultEnabled;
+  }
+  backend;
+  defaultEnabled;
+  /**
+   * 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).
+   */
+  async isEnabled(flag, context) {
+    const answer = await this.backend.resolve(flag, context);
+    return answer ?? this.defaultEnabled;
+  }
+};
+function makeFlagGuard(flags, flag) {
+  return (_req, _res, next) => {
+    flags.isEnabled(flag).then((enabled) => {
+      if (enabled) next();
+      else next(new NotFoundException({ message: "Not found", details: { flag } }));
+    }).catch(next);
+  };
+}
+var LocalUploadStorage = class {
+  root;
+  baseUrl;
+  /**
+   * @param options - Filesystem root and public base URL.
+   */
+  constructor(options) {
+    this.root = options.root;
+    this.baseUrl = options.baseUrl ?? "";
+  }
+  async save(key, data, options = {}) {
+    const target = join(this.root, key);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, data);
+    return {
+      key,
+      url: this.url(key),
+      size: data.byteLength,
+      ...options.contentType !== void 0 ? { contentType: options.contentType } : {}
+    };
+  }
+  async read(key) {
+    return readFile(join(this.root, key));
+  }
+  async delete(key) {
+    await rm(join(this.root, key), { force: true });
+  }
+  url(key) {
+    const base = this.baseUrl.replace(/\/$/, "");
+    return base ? `${base}/${key}` : `/${key}`;
+  }
+};
+function buildContentDisposition(filename, inline = false) {
+  const disposition = inline ? "inline" : "attachment";
+  const encoded = encodeURIComponent(filename);
+  return `${disposition}; filename*=UTF-8''${encoded}`;
+}
+
 // src/auth/schemas.ts
 var signupSchema = z.object({
   email: z.string().email().openapi({ description: "Login identifier (email)." }),
@@ -6996,7 +7838,7 @@ function makeAuthRouter(options) {
   });
   return router;
 }
-var logger = new JSONLogger("tempest_express_sdk.api.handlers");
+var logger2 = new JSONLogger("tempest_express_sdk.api.handlers");
 var REQUEST_ID_HEADER = "X-Request-ID";
 function requestIdMiddleware() {
   return (req, res, next) => {
@@ -7037,7 +7879,7 @@ function makeAppExceptionHandler(options = {}) {
       return;
     }
     const isServerError = exc.statusCode >= 500;
-    logger.log(isServerError ? serverErrorLevel : "info", "AppException handled", {
+    logger2.log(isServerError ? serverErrorLevel : "info", "AppException handled", {
       path: req.path,
       method: req.method,
       statusCode: exc.statusCode,
@@ -7061,7 +7903,7 @@ function makeUnhandledExceptionHandler(options = {}) {
   const { includeStack = false, logLevel = "error" } = options;
   return (err, req, res, _next) => {
     const error = err instanceof Error ? err : new Error(String(err));
-    logger.log(logLevel, "Unhandled exception", {
+    logger2.log(logLevel, "Unhandled exception", {
       path: req.path,
       method: req.method,
       [HTTP_500_MARKER]: true,
@@ -7196,7 +8038,7 @@ function makeHealthRouter(options = {}) {
   });
   return router;
 }
-var logger2 = new JSONLogger("tempest_express_sdk.api.server");
+var logger3 = new JSONLogger("tempest_express_sdk.api.server");
 function corsMiddleware(origins) {
   const allowAll = origins === "*";
   const allowList = new Set(Array.isArray(origins) ? origins : [origins]);
@@ -7255,12 +8097,12 @@ function runServer(app, options = {}) {
   const port = options.port ?? 8e3;
   return new Promise((resolve) => {
     const server = app.listen(port, host, () => {
-      logger2.info("Server listening", { host, port });
+      logger3.info("Server listening", { host, port });
       resolve(server);
     });
   });
 }
 
-export { AppException, AttemptThrottle, BaseController, BaseModel, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, ConflictException, DEFAULT_LOCALE, ExpiredTokenException, ForbiddenException, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, MemoryThrottleBackend, MessageCatalog, NotFoundException, PHONE_BR_PATTERN, PasswordUtils, REQUEST_ID_HEADER, Region, TooManyRequestsException, UF, UnauthorizedException, UserAuthService, 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, AttemptThrottle, BaseController, BaseModel, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, CompositeFeatureFlagBackend, ConflictException, DEFAULT_LOCALE, EnvFeatureFlagBackend, EventStream, ExpiredTokenException, FeatureFlags, ForbiddenException, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, LocalUploadStorage, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, NotFoundException, PHONE_BR_PATTERN, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, RedisCacheManager, Region, SSEBroker, ServerSentEvent, SessionService, TaskManager, TooManyRequestsException, UF, UnauthorizedException, UserAuthService, ValidationException, WebSocketHub, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached3 as 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map