tempest-express-sdk 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -5,6 +5,8 @@ var zodToOpenapi = require('@asteasolutions/zod-to-openapi');
 var zod = require('zod');
 var tempestDbJs = require('tempest-db-js');
 var crypto = require('crypto');
+var promises = require('fs/promises');
+var path = require('path');
 var express2 = require('express');
 var swaggerUiDist = require('swagger-ui-dist');
 
@@ -6753,6 +6755,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 = zod.z.object({
+  type: zod.z.string().openapi({ description: "Message type discriminator." }),
+  data: zod.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: crypto.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 = path.join(this.root, key);
+    await promises.mkdir(path.dirname(target), { recursive: true });
+    await promises.writeFile(target, data);
+    return {
+      key,
+      url: this.url(key),
+      size: data.byteLength,
+      ...options.contentType !== void 0 ? { contentType: options.contentType } : {}
+    };
+  }
+  async read(key) {
+    return promises.readFile(path.join(this.root, key));
+  }
+  async delete(key) {
+    await promises.rm(path.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 = zod.z.object({
   email: zod.z.string().email().openapi({ description: "Login identifier (email)." }),
@@ -6999,7 +7841,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) => {
@@ -7040,7 +7882,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,
@@ -7064,7 +7906,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,
@@ -7199,7 +8041,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]);
@@ -7258,14 +8100,14 @@ 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);
     });
   });
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 
 Object.defineProperty(exports, "OpenAPIRegistry", {
   enumerable: true,
@@ -7427,35 +8269,55 @@ exports.BaseService = BaseService;
 exports.CEP_PATTERN = CEP_PATTERN;
 exports.CNPJ_PATTERN = CNPJ_PATTERN;
 exports.CPF_PATTERN = CPF_PATTERN;
+exports.CompositeFeatureFlagBackend = CompositeFeatureFlagBackend;
 exports.ConflictException = ConflictException;
 exports.DEFAULT_LOCALE = DEFAULT_LOCALE;
+exports.EnvFeatureFlagBackend = EnvFeatureFlagBackend;
+exports.EventStream = EventStream;
 exports.ExpiredTokenException = ExpiredTokenException;
+exports.FeatureFlags = FeatureFlags;
 exports.ForbiddenException = ForbiddenException;
 exports.HTTP_500_MARKER = HTTP_500_MARKER;
 exports.InvalidTokenException = InvalidTokenException;
 exports.JSONLogger = JSONLogger;
 exports.JWTUtils = JWTUtils;
+exports.LocalUploadStorage = LocalUploadStorage;
+exports.MemoryBroker = MemoryBroker;
+exports.MemoryCacheManager = MemoryCacheManager;
+exports.MemoryFeatureFlagBackend = MemoryFeatureFlagBackend;
+exports.MemorySessionStore = MemorySessionStore;
 exports.MemoryThrottleBackend = MemoryThrottleBackend;
 exports.MessageCatalog = MessageCatalog;
 exports.NotFoundException = NotFoundException;
 exports.PHONE_BR_PATTERN = PHONE_BR_PATTERN;
 exports.PasswordUtils = PasswordUtils;
 exports.REQUEST_ID_HEADER = REQUEST_ID_HEADER;
+exports.RabbitBroker = RabbitBroker;
+exports.RedisCacheManager = RedisCacheManager;
 exports.Region = Region;
+exports.SSEBroker = SSEBroker;
+exports.ServerSentEvent = ServerSentEvent;
+exports.SessionService = SessionService;
+exports.TaskManager = TaskManager;
 exports.TooManyRequestsException = TooManyRequestsException;
 exports.UF = UF;
 exports.UnauthorizedException = UnauthorizedException;
 exports.UserAuthService = UserAuthService;
 exports.VERSION = VERSION;
 exports.ValidationException = ValidationException;
+exports.WebSocketHub = WebSocketHub;
+exports.attachWebSocketHub = attachWebSocketHub;
 exports.authResponseSchema = authResponseSchema;
 exports.baseAppSettingsSchema = baseAppSettingsSchema;
 exports.baseAppSettingsShape = baseAppSettingsShape;
 exports.baseResponseSchema = baseResponseSchema;
 exports.bearerToken = bearerToken;
+exports.buildContentDisposition = buildContentDisposition;
+exports.cached = cached3;
 exports.cepField = cepField;
 exports.citiesByUf = citiesByUf;
 exports.cnpjField = cnpjField;
+exports.coerceFlag = coerceFlag;
 exports.configureLogging = configureLogging;
 exports.corsSettingsShape = corsSettingsShape;
 exports.cpfField = cpfField;
@@ -7491,8 +8353,10 @@ exports.loadSettings = loadSettings;
 exports.loginSchema = loginSchema;
 exports.makeAppExceptionHandler = makeAppExceptionHandler;
 exports.makeAuthRouter = makeAuthRouter;
+exports.makeFlagGuard = makeFlagGuard;
 exports.makeHealthRouter = makeHealthRouter;
 exports.makeJwtAuthMiddleware = makeJwtAuthMiddleware;
+exports.makeSessionMiddleware = makeSessionMiddleware;
 exports.makeUnhandledExceptionHandler = makeUnhandledExceptionHandler;
 exports.modifyDict = modifyDict;
 exports.mountOpenApiJson = mountOpenApiJson;
@@ -7509,6 +8373,7 @@ exports.onlyDigits = onlyDigits;
 exports.paginationFilterSchema = paginationFilterSchema;
 exports.paginationSchema = paginationSchema;
 exports.parseAcceptLanguage = parseAcceptLanguage;
+exports.parseCookies = parseCookies;
 exports.phoneBrField = phoneBrField;
 exports.refreshSchema = refreshSchema;
 exports.registerExceptionHandlers = registerExceptionHandlers;
@@ -7517,17 +8382,21 @@ exports.requireRoles = requireRoles;
 exports.runServer = runServer;
 exports.runWithRequestContext = runWithRequestContext;
 exports.serverSettingsShape = serverSettingsShape;
+exports.sessionCookie = sessionCookie;
 exports.setRequestId = setRequestId;
 exports.signupSchema = signupSchema;
+exports.sseResponse = sseResponse;
 exports.statesByRegion = statesByRegion;
 exports.tableNameFor = tableNameFor;
 exports.toDict = toDict;
 exports.toUtc = toUtc;
+exports.tokenFromUrl = tokenFromUrl;
 exports.tokenPairSchema = tokenPairSchema;
 exports.ufField = ufField;
 exports.updatedByColumn = updatedByColumn;
 exports.userPublicSchema = userPublicSchema;
 exports.utcnow = utcnow;
 exports.verifyOpaqueToken = verifyOpaqueToken;
+exports.wsEnvelopeSchema = wsEnvelopeSchema;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map