tempest-express-sdk 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,4 +1,4 @@
-export { VERSION } from './chunk-2NB7ZA7G.js';
+export { VERSION } from './chunk-6ZKN2ELQ.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV31, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
 export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
@@ -6,7 +6,10 @@ import { z, ZodError } from 'zod';
 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 { createHash, randomBytes, timingSafeEqual, randomUUID, createHmac } from 'crypto';
+import { cpus, loadavg, totalmem, freemem } from 'os';
+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 +6753,1279 @@ var AttemptThrottle = class {
   }
 };
 
+// src/utils/clientIp.ts
+var UNKNOWN = "unknown";
+function getClientIp(req, options = {}) {
+  if (options.trustedHeader) {
+    const value = req.header(options.trustedHeader);
+    if (value) return value.trim();
+  }
+  return req.socket?.remoteAddress ?? req.ip ?? UNKNOWN;
+}
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function base32Encode(bytes) {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (const byte of bytes) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += BASE32_ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += BASE32_ALPHABET[value << 5 - bits & 31];
+  return out;
+}
+function base32Decode(secret) {
+  const clean = secret.toUpperCase().replace(/=+$/, "").replace(/\s/g, "");
+  let bits = 0;
+  let value = 0;
+  const out = [];
+  for (const char of clean) {
+    const index = BASE32_ALPHABET.indexOf(char);
+    if (index === -1) continue;
+    value = value << 5 | index;
+    bits += 5;
+    if (bits >= 8) {
+      out.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(out);
+}
+function hotp(secret, counter, digits) {
+  const buffer = Buffer.alloc(8);
+  buffer.writeUInt32BE(Math.floor(counter / 2 ** 32), 0);
+  buffer.writeUInt32BE(counter >>> 0, 4);
+  const digest = createHmac("sha1", secret).update(buffer).digest();
+  const offset = digest[digest.length - 1] & 15;
+  const binary = (digest[offset] & 127) << 24 | (digest[offset + 1] & 255) << 16 | (digest[offset + 2] & 255) << 8 | digest[offset + 3] & 255;
+  return (binary % 10 ** digits).toString().padStart(digits, "0");
+}
+var TOTPHelper = class {
+  issuer;
+  step;
+  digits;
+  /**
+   * @param options - Issuer label, time step and digit count.
+   */
+  constructor(options) {
+    this.issuer = options.issuer;
+    this.step = options.step ?? 30;
+    this.digits = options.digits ?? 6;
+  }
+  /**
+   * Generate a fresh base32 secret (80 bits).
+   *
+   * @returns A base32-encoded TOTP secret to persist on the user row.
+   */
+  generateSecret() {
+    return base32Encode(randomBytes(10));
+  }
+  /**
+   * Build the `otpauth://` provisioning URI (render as a QR code).
+   *
+   * @param secret - The base32 secret.
+   * @param accountName - Identifier shown next to the issuer (e.g. the email).
+   * @returns The `otpauth://totp/...` URI.
+   */
+  provisioningUri(secret, accountName) {
+    const label = encodeURIComponent(`${this.issuer}:${accountName}`);
+    const params = new URLSearchParams({
+      secret,
+      issuer: this.issuer,
+      algorithm: "SHA1",
+      digits: String(this.digits),
+      period: String(this.step)
+    });
+    return `otpauth://totp/${label}?${params.toString()}`;
+  }
+  /**
+   * Verify a code against the secret for the current time window.
+   *
+   * @param secret - The base32 secret.
+   * @param code - The submitted code.
+   * @param window - Tolerance in steps (±). Default 1 (previous/current/next).
+   * @returns `true` when the code matches within the window.
+   */
+  verify(secret, code, window = 1) {
+    const cleaned = code.trim().replace(/[\s-]/g, "");
+    if (!/^\d+$/.test(cleaned) || cleaned.length !== this.digits) return false;
+    const key = base32Decode(secret);
+    const counter = Math.floor(Date.now() / 1e3 / this.step);
+    for (let offset = -window; offset <= window; offset++) {
+      if (hotp(key, counter + offset, this.digits) === cleaned) return true;
+    }
+    return false;
+  }
+};
+
+// src/utils/httpClient.ts
+var CircuitOpenError = class extends Error {
+  constructor(host) {
+    super(`Circuit breaker is open for host ${host}`);
+    this.host = host;
+    this.name = "CircuitOpenError";
+  }
+  host;
+};
+var RetryPolicy = class {
+  /**
+   * @param maxRetries - Additional attempts after the first. Default 2.
+   * @param baseDelayMs - Base backoff in ms (doubles each attempt). Default 100.
+   * @param retryOn - HTTP status codes that trigger a retry. Default 5xx + 429.
+   */
+  constructor(maxRetries = 2, baseDelayMs = 100, retryOn = [429, 500, 502, 503, 504]) {
+    this.maxRetries = maxRetries;
+    this.baseDelayMs = baseDelayMs;
+    this.retryOn = retryOn;
+  }
+  maxRetries;
+  baseDelayMs;
+  retryOn;
+  /** Backoff delay in ms before `attempt` (0-indexed). */
+  sleepFor(attempt) {
+    return this.baseDelayMs * 2 ** attempt;
+  }
+};
+var HTTPClient = class {
+  baseUrl;
+  defaultHeaders;
+  timeoutMs;
+  retryPolicy;
+  breakerThreshold;
+  breakerCooldownMs;
+  breakers = /* @__PURE__ */ new Map();
+  /**
+   * @param options - Base URL, headers, timeout, retry and breaker settings.
+   */
+  constructor(options = {}) {
+    this.baseUrl = options.baseUrl ?? "";
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.retryPolicy = options.retryPolicy ?? new RetryPolicy();
+    this.breakerThreshold = options.breakerThreshold ?? 5;
+    this.breakerCooldownMs = options.breakerCooldownMs ?? 3e4;
+  }
+  resolve(url) {
+    return this.baseUrl && !/^https?:\/\//.test(url) ? `${this.baseUrl}${url}` : url;
+  }
+  hostOf(url) {
+    try {
+      return new URL(url).host;
+    } catch {
+      return url;
+    }
+  }
+  breakerCheck(host) {
+    const state = this.breakers.get(host);
+    if (state && state.openUntil > Date.now()) throw new CircuitOpenError(host);
+  }
+  breakerRecord(host, failed) {
+    const state = this.breakers.get(host) ?? { failures: 0, openUntil: 0 };
+    if (failed) {
+      state.failures += 1;
+      if (state.failures >= this.breakerThreshold) {
+        state.openUntil = Date.now() + this.breakerCooldownMs;
+        state.failures = 0;
+      }
+    } else {
+      state.failures = 0;
+      state.openUntil = 0;
+    }
+    this.breakers.set(host, state);
+  }
+  /**
+   * Perform a request with retries and breaker protection.
+   *
+   * @param method - HTTP method.
+   * @param url - Absolute URL or a path resolved against `baseUrl`.
+   * @param init - Extra `fetch` init (headers, body, …).
+   * @returns The `Response`.
+   * @throws {CircuitOpenError} When the per-host breaker is open.
+   */
+  async request(method, url, init = {}) {
+    const target = this.resolve(url);
+    const host = this.hostOf(target);
+    this.breakerCheck(host);
+    let lastError;
+    for (let attempt = 0; attempt <= this.retryPolicy.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      try {
+        const response = await fetch(target, {
+          ...init,
+          method,
+          headers: { ...this.defaultHeaders, ...init.headers ?? {} },
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (this.retryPolicy.retryOn.includes(response.status)) {
+          this.breakerRecord(host, true);
+          if (attempt < this.retryPolicy.maxRetries) {
+            await this.sleep(this.retryPolicy.sleepFor(attempt));
+            continue;
+          }
+          return response;
+        }
+        this.breakerRecord(host, false);
+        return response;
+      } catch (error) {
+        clearTimeout(timer);
+        lastError = error;
+        this.breakerRecord(host, true);
+        if (attempt < this.retryPolicy.maxRetries) {
+          await this.sleep(this.retryPolicy.sleepFor(attempt));
+          continue;
+        }
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Request failed");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /** GET request. */
+  get(url, init) {
+    return this.request("GET", url, init);
+  }
+  /** POST request. */
+  post(url, init) {
+    return this.request("POST", url, init);
+  }
+  /** PUT request. */
+  put(url, init) {
+    return this.request("PUT", url, init);
+  }
+  /** PATCH request. */
+  patch(url, init) {
+    return this.request("PATCH", url, init);
+  }
+  /** DELETE request. */
+  delete(url, init) {
+    return this.request("DELETE", url, init);
+  }
+};
+function readCpu() {
+  const cores = cpus().length;
+  const load1 = loadavg()[0] ?? 0;
+  return {
+    cores,
+    load1,
+    loadPercent: cores > 0 ? load1 / cores * 100 : 0
+  };
+}
+function readMemory() {
+  const total = totalmem();
+  const free = freemem();
+  const used = total - free;
+  return {
+    total,
+    free,
+    used,
+    usedPercent: total > 0 ? used / total * 100 : 0,
+    processRss: process.memoryUsage().rss
+  };
+}
+function readSystem() {
+  return {
+    cpu: readCpu(),
+    memory: readMemory(),
+    uptimeSeconds: process.uptime()
+  };
+}
+function toPrometheus(snapshot = readSystem()) {
+  const lines = [
+    "# HELP process_cpu_load_percent 1-minute load average as percent of cores",
+    "# TYPE process_cpu_load_percent gauge",
+    `process_cpu_load_percent ${snapshot.cpu.loadPercent}`,
+    "# HELP process_memory_used_percent System memory used percent",
+    "# TYPE process_memory_used_percent gauge",
+    `process_memory_used_percent ${snapshot.memory.usedPercent}`,
+    "# HELP process_memory_rss_bytes Resident set size of the process",
+    "# TYPE process_memory_rss_bytes gauge",
+    `process_memory_rss_bytes ${snapshot.memory.processRss}`,
+    "# HELP process_uptime_seconds Process uptime in seconds",
+    "# TYPE process_uptime_seconds counter",
+    `process_uptime_seconds ${snapshot.uptimeSeconds}`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+var MetricsUtils = {
+  cpu: readCpu,
+  memory: readMemory,
+  system: readSystem,
+  toPrometheus
+};
+
+// src/utils/email.ts
+var EmailUtils = class {
+  /**
+   * @param options - SMTP connection and default sender.
+   */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  transport = null;
+  async ready() {
+    if (this.transport) return this.transport;
+    let nodemailer;
+    try {
+      const mod = await import('nodemailer');
+      nodemailer = mod.default ?? mod;
+    } catch (cause) {
+      throw new Error(
+        "EmailUtils requires the 'nodemailer' peer dependency. Install with `npm i nodemailer`.",
+        { cause }
+      );
+    }
+    this.transport = nodemailer.createTransport({
+      host: this.options.host,
+      port: this.options.port ?? 587,
+      secure: this.options.secure ?? false,
+      ...this.options.user ? { auth: { user: this.options.user, pass: this.options.password ?? "" } } : {}
+    });
+    return this.transport;
+  }
+  /**
+   * Send an email message.
+   *
+   * @param message - The message (recipients, subject, body).
+   */
+  async send(message) {
+    const transport = await this.ready();
+    await transport.sendMail({
+      from: message.from ?? this.options.from,
+      to: message.to,
+      subject: message.subject,
+      ...message.text !== void 0 ? { text: message.text } : {},
+      ...message.html !== void 0 ? { html: message.html } : {}
+    });
+  }
+};
+
+// 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/webpush/schemas.ts
+var webPushKeysSchema = z.object({
+  p256dh: z.string().openapi({ description: "Client public key (base64url)." }),
+  auth: z.string().openapi({ description: "Client auth secret (base64url)." })
+}).openapi("WebPushKeys");
+var webPushSubscriptionSchema = z.object({
+  endpoint: z.string().url().openapi({ description: "Push service endpoint URL." }),
+  keys: webPushKeysSchema
+}).openapi("WebPushSubscription");
+var webPushPayloadSchema = z.object({
+  title: z.string().openapi({ description: "Notification title." }),
+  body: z.string().optional().openapi({ description: "Notification body." }),
+  url: z.string().optional().openapi({ description: "URL opened on click." }),
+  data: z.record(z.unknown()).optional().openapi({ description: "Extra data." })
+}).openapi("WebPushPayload");
+
+// src/webpush/dispatcher.ts
+var WebPushError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "WebPushError";
+  }
+  statusCode;
+};
+var WebPushGoneError = class extends WebPushError {
+  constructor(statusCode) {
+    super("Push subscription is gone", statusCode);
+    this.name = "WebPushGoneError";
+  }
+};
+var cached4 = null;
+async function loadWebPush() {
+  if (cached4) return cached4;
+  try {
+    const mod = await import('web-push');
+    cached4 = mod.default ?? mod;
+  } catch (cause) {
+    throw new Error(
+      "WebPushDispatcher requires the 'web-push' peer dependency. Install with `npm i web-push`.",
+      { cause }
+    );
+  }
+  return cached4;
+}
+var WebPushDispatcher = class {
+  /**
+   * @param options - VAPID keys and subject.
+   */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  /**
+   * Send a payload to a single subscription.
+   *
+   * @param subscription - The browser push subscription.
+   * @param payload - The notification payload.
+   * @throws {WebPushGoneError} When the subscription is expired (410/404).
+   * @throws {WebPushError} On any other delivery failure.
+   */
+  async send(subscription, payload) {
+    const webpush = await loadWebPush();
+    webpush.setVapidDetails(
+      this.options.subject,
+      this.options.publicKey,
+      this.options.privateKey
+    );
+    try {
+      await webpush.sendNotification(subscription, JSON.stringify(payload));
+    } catch (error) {
+      const status = error.statusCode;
+      if (status === 404 || status === 410) throw new WebPushGoneError(status);
+      throw new WebPushError(error.message, status);
+    }
+  }
+};
+
 // src/auth/schemas.ts
 var signupSchema = z.object({
   email: z.string().email().openapi({ description: "Login identifier (email)." }),
@@ -6996,7 +8272,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 +8313,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 +8337,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 +8472,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 +8531,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, CircuitOpenError, CompositeFeatureFlagBackend, ConflictException, DEFAULT_LOCALE, EmailUtils, EnvFeatureFlagBackend, EventStream, ExpiredTokenException, FeatureFlags, ForbiddenException, HTTPClient, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, LocalUploadStorage, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, MetricsUtils, NotFoundException, PHONE_BR_PATTERN, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, RedisCacheManager, Region, RetryPolicy, SSEBroker, ServerSentEvent, SessionService, TOTPHelper, TaskManager, TooManyRequestsException, UF, UnauthorizedException, UserAuthService, ValidationException, WebPushDispatcher, WebPushError, WebPushGoneError, 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, getClientIp, 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, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map