tempest-express-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1726 @@
+import { z } from 'zod';
+export { z } from 'zod';
+import * as tempest_db_js from 'tempest-db-js';
+import { Model, ModelClass, BaseRepository, InferModel, WhereInput, InferInsert, PaginationFilter as PaginationFilter$1, PaginationResult } from 'tempest-db-js';
+export { AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseRepository, BelongsTo, ColType, Column, ColumnFlags, CompiledQuery, CondNode, Condition, DeleteBuilder, DeleteNode, Dialect, EngineOptions, Executable, HasMany, InferInsert, InferModel, InsertBuilder, InsertNode, Model, ModelClass, NoResultError, NodeSqliteDriver, Operator, OrderTerm, PaginationResult, ParsedDatabaseUrl, PostgresDialect, QueryNode, RecordNotFound, Relation, RelationValue, PaginationFilter as RepositoryPaginationFilter, Returning, RowOf, SelectBuilder, SelectNode, SortDirection, SqliteDialect, SyncEngine, SyncSession, UpdateBuilder, UpdateNode, WhereArg, WhereInput, WithRelations, and, belongsTo, column, columnsOf, createEngine, createSyncEngine, del, detectDialect, getDialect, hasMany, insert, join, loadRelations, not, or, parseDatabaseUrl, select, sql, update } from 'tempest-db-js';
+import { Request, RequestHandler, Router, ErrorRequestHandler, Express } from 'express';
+import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
+export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
+import { Server } from 'node:http';
+
+/**
+ * Request-scoped context propagation via `AsyncLocalStorage`.
+ *
+ * Mirrors `tempest_fastapi_sdk.core.context`: a per-request id that any layer
+ * (logger, exception handler, service) can read without threading it through
+ * every call. The store is populated by the request-id middleware and survives
+ * across `await` boundaries within the same request.
+ */
+/** The shape of the per-request store. */
+interface RequestContext {
+    /** Stable id correlating every log line of a single request. */
+    requestId: string;
+}
+/**
+ * Run `fn` with `context` bound as the active request context.
+ *
+ * @param context - The context to bind for the duration of `fn`.
+ * @param fn - The function to run within the bound context.
+ * @returns Whatever `fn` returns.
+ */
+declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
+/**
+ * Read the current request id, or `null` when called outside a request.
+ *
+ * @returns The active request id, or `null`.
+ */
+declare function getRequestId(): string | null;
+/**
+ * Overwrite the request id on the active context (no-op outside a request).
+ *
+ * @param requestId - The id to set.
+ */
+declare function setRequestId(requestId: string): void;
+
+/**
+ * Structured JSON logging, mirroring `tempest_fastapi_sdk.core.logging`.
+ *
+ * Emits one JSON object per line to stdout (or stderr for `error`), enriched
+ * with the active request id. Server errors (`500`) carry the
+ * {@link HTTP_500_MARKER} flag so an external log router can split them into a
+ * dedicated `500.log` sink.
+ */
+/** Flag key marking a record as a captured HTTP 500 for sink routing. */
+declare const HTTP_500_MARKER = "http_500";
+/** Severity levels, ordered from least to most severe. */
+type LogLevel = "debug" | "info" | "warning" | "error";
+/** Free-form structured context merged into the emitted record. */
+type LogExtra = Record<string, unknown>;
+/** A minimal structured logger writing one JSON line per record. */
+declare class JSONLogger {
+    private readonly name;
+    private readonly level;
+    /**
+     * @param name - Logger name embedded in every record.
+     * @param level - Minimum level to emit; quieter records are dropped.
+     */
+    constructor(name: string, level?: LogLevel);
+    /** Log a debug-level message. */
+    debug(message: string, extra?: LogExtra): void;
+    /** Log an info-level message. */
+    info(message: string, extra?: LogExtra): void;
+    /** Log a warning-level message. */
+    warning(message: string, extra?: LogExtra): void;
+    /** Log an error-level message. */
+    error(message: string, extra?: LogExtra): void;
+    /**
+     * Emit a record at `level` when it clears the configured threshold.
+     *
+     * @param level - The record severity.
+     * @param message - The human-readable message.
+     * @param extra - Structured context merged into the record.
+     */
+    log(level: LogLevel, message: string, extra?: LogExtra): void;
+}
+/**
+ * Build a {@link JSONLogger}.
+ *
+ * @param name - Logger name.
+ * @param level - Minimum level to emit (defaults to `info`).
+ * @returns A configured logger.
+ */
+declare function configureLogging(name: string, level?: LogLevel): JSONLogger;
+
+/**
+ * Enum helpers mirroring `BaseStrEnum` / `BaseIntEnum`.
+ *
+ * TypeScript has no Python-style `Enum`, so this module offers a factory that
+ * turns a plain literal map into a frozen object carrying the same
+ * introspection helpers (`values`/`keys`/`choices`/`has`/`from`) the FastAPI
+ * SDK exposes. The inferred type is the literal union of the member values, so
+ * it stays as strongly typed as a hand-written `as const` map.
+ */
+/** A member-name → member-value map (string- or number-valued). */
+type EnumSpec = Record<string, string | number>;
+/** Introspection helpers attached to every built enum. */
+interface EnumHelpers<S extends EnumSpec> {
+    /** Every member value, in declaration order. */
+    values(): Array<S[keyof S]>;
+    /** Every member name, in declaration order. */
+    keys(): Array<keyof S & string>;
+    /** `[value, name]` pairs, e.g. for building `<select>` options. */
+    choices(): Array<[S[keyof S], keyof S & string]>;
+    /** Whether `value` is the value of some member. */
+    hasValue(value: unknown): value is S[keyof S];
+    /** Whether `key` is the name of some member. */
+    hasKey(key: string): key is keyof S & string;
+    /** Resolve a member value from a raw value or member name, else `fallback`. */
+    from(value: unknown, fallback?: S[keyof S]): S[keyof S] | undefined;
+}
+/** A built enum: the literal member map plus {@link EnumHelpers}. */
+type Enum<S extends EnumSpec> = Readonly<S> & EnumHelpers<S>;
+/**
+ * Build a frozen enum object with introspection helpers from a literal spec.
+ *
+ * @param spec - The member-name → value map. Pass it inline so TypeScript
+ *   infers the precise literal union (e.g. `defineEnum({ RED: "red" })`).
+ * @returns The frozen members merged with {@link EnumHelpers}.
+ */
+declare function defineEnum<const S extends EnumSpec>(spec: S): Enum<S>;
+
+/**
+ * Base application exception.
+ *
+ * Mirrors `tempest_fastapi_sdk.exceptions.base.AppException`: a single base any
+ * layer can throw, carrying an HTTP status, a stable machine-readable `code`,
+ * free-form `details`, optional response `headers`, and localization hooks
+ * (`messageKey` / `messageParams`). The exception handler
+ * ({@link registerExceptionHandlers}) serializes it to the canonical envelope:
+ *
+ * ```json
+ * { "detail": "<message>", "code": "<code>", "details": { } }
+ * ```
+ *
+ * Concrete projects either throw a domain subclass (for `instanceof` matching)
+ * or the base directly, overriding fields via the constructor options.
+ */
+/** Free-form structured context attached to the response payload. */
+type ExceptionDetails = Record<string, unknown>;
+/** Constructor options for {@link AppException} and subclasses. */
+interface AppExceptionOptions {
+    /** Override the default message; used verbatim as `detail` absent a catalog. */
+    message?: string;
+    /** Override the default machine-readable code on this instance only. */
+    code?: string;
+    /** Override the default HTTP status code on this instance only. */
+    statusCode?: number;
+    /** Structured context merged into the JSON response `details`. */
+    details?: ExceptionDetails;
+    /** Extra HTTP response headers. */
+    headers?: Record<string, string>;
+    /** Catalog key used to localize `detail`; falls back to `code`. */
+    messageKey?: string;
+    /** Values interpolated into the localized message template. */
+    messageParams?: Record<string, unknown>;
+}
+declare class AppException extends Error {
+    /** Default HTTP status code for the class. */
+    static statusCode: number;
+    /** Default human-readable message for the class. */
+    static message: string;
+    /** Default machine-readable code for the class. */
+    static code: string;
+    /** Default catalog key for the class (falls back to `code`). */
+    static messageKey: string | null;
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details: ExceptionDetails;
+    readonly headers: Record<string, string>;
+    readonly messageKey: string | null;
+    readonly messageParams: Record<string, unknown>;
+    /**
+     * @param options - Per-instance overrides; omitted fields fall back to the
+     *   static class defaults.
+     */
+    constructor(options?: AppExceptionOptions);
+}
+
+/**
+ * Concrete HTTP exception subclasses, mirroring the FastAPI SDK hierarchy.
+ *
+ * Each exists primarily for `instanceof` matching and to carry a sane default
+ * status/code/message. Throw them directly or subclass further for domain
+ * errors (e.g. `class UserNotFound extends NotFoundException {}`).
+ */
+
+/** 409 — a write would violate a uniqueness/integrity rule. */
+declare class ConflictException extends AppException {
+    static statusCode: number;
+    static message: string;
+    static code: string;
+}
+/** 404 — a single resource could not be located. Never for collections. */
+declare class NotFoundException extends AppException {
+    static statusCode: number;
+    static message: string;
+    static code: string;
+}
+/** 401 — the caller is not authenticated. */
+declare class UnauthorizedException extends AppException {
+    static statusCode: number;
+    static message: string;
+    static code: string;
+}
+/** 403 — the caller is authenticated but lacks permission. */
+declare class ForbiddenException extends AppException {
+    static statusCode: number;
+    static message: string;
+    static code: string;
+}
+/** 422 — input failed a business rule beyond schema validation. */
+declare class ValidationException extends AppException {
+    static statusCode: number;
+    static message: string;
+    static code: string;
+}
+/** 401 — a JWT failed signature or claim validation. */
+declare class InvalidTokenException extends UnauthorizedException {
+    static message: string;
+    static code: string;
+}
+/** 401 — a JWT's `exp` claim is in the past. */
+declare class ExpiredTokenException extends UnauthorizedException {
+    static message: string;
+    static code: string;
+}
+/** Options for {@link TooManyRequestsException}, adding a cooldown. */
+interface TooManyRequestsOptions extends AppExceptionOptions {
+    /** Cooldown in seconds; sets `Retry-After` and `details.retryAfterSeconds`. */
+    retryAfterSeconds?: number;
+}
+/** 429 — the client exceeded a rate limit or attempt budget. */
+declare class TooManyRequestsException extends AppException {
+    static statusCode: number;
+    static message: string;
+    static code: string;
+    /**
+     * @param options - Standard options plus an optional `retryAfterSeconds`
+     *   that populates both the `Retry-After` header and `details`.
+     */
+    constructor(options?: TooManyRequestsOptions);
+}
+
+/**
+ * Lightweight message localization, mirroring `exceptions.i18n`.
+ *
+ * A {@link MessageCatalog} maps `code` → `{ locale: template }`. The exception
+ * handler negotiates a locale from the request `Accept-Language` header and
+ * resolves the exception's `messageKey` (or `code`) into a localized `detail`,
+ * interpolating `messageParams` via `{name}` placeholders. A missing
+ * translation falls back to the literal message, so partial catalogs are safe.
+ */
+/** Default locale used when negotiation finds no match. */
+declare const DEFAULT_LOCALE = "en";
+/** A `code` → (`locale` → template) translation table. */
+type CatalogData = Record<string, Record<string, string>>;
+/**
+ * Parse an `Accept-Language` header into locales ordered by descending `q`.
+ *
+ * @param header - The raw header value, or `null`/`undefined`.
+ * @returns Lower-cased language tags, highest quality first.
+ */
+declare function parseAcceptLanguage(header: string | null | undefined): string[];
+/** A localized message catalog keyed by error `code`. */
+declare class MessageCatalog {
+    private readonly data;
+    private readonly defaultLocale;
+    /**
+     * @param data - The translation table.
+     * @param defaultLocale - Locale used when negotiation matches nothing.
+     */
+    constructor(data?: CatalogData, defaultLocale?: string);
+    /**
+     * Pick the best locale for an `Accept-Language` header.
+     *
+     * Matches exact tags first, then the primary subtag (`pt-br` → `pt`),
+     * falling back to `defaultLocale`.
+     *
+     * @param header - The raw `Accept-Language` value.
+     * @param defaultLocale - Override the catalog's default for this call.
+     * @returns The negotiated locale tag.
+     */
+    negotiate(header: string | null | undefined, defaultLocale?: string): string;
+    /**
+     * Resolve a localized message for `code` in `locale`.
+     *
+     * @param code - The catalog key (an exception's `messageKey` or `code`).
+     * @param locale - The negotiated locale.
+     * @param params - Values interpolated into the template.
+     * @returns The localized string, or `null` when no template exists.
+     */
+    resolve(code: string, locale: string, params?: Record<string, unknown>): string | null;
+}
+/** Build an empty default catalog. */
+declare function defaultMessageCatalog(): MessageCatalog;
+
+/**
+ * Zod foundation shared by every DTO, mirroring `schemas.base.BaseSchema`.
+ *
+ * Pydantic uses class inheritance for shared config; Zod composes instead. This
+ * module re-exports a `z` already augmented with `.openapi()` (so every schema
+ * can carry OpenAPI metadata) and a {@link toDict} helper matching
+ * `BaseSchema.to_dict` (drop nullish, exclude keys, merge extras).
+ */
+
+/** Options for {@link toDict}. */
+interface ToDictOptions {
+    /** Field names to drop from the output. */
+    exclude?: string[];
+    /** Extra entries merged on top (override existing keys). */
+    include?: Record<string, unknown>;
+}
+/**
+ * Serialize a validated object to a plain record, dropping `null`/`undefined`,
+ * removing `exclude`d keys and merging `include` on top.
+ *
+ * @param data - The source object (typically a parsed schema).
+ * @param options - Keys to exclude and entries to merge in.
+ * @returns The cleaned record.
+ */
+declare function toDict(data: Record<string, unknown>, options?: ToDictOptions): Record<string, unknown>;
+/**
+ * Response schema fields every ORM record carries (`id`, `isActive`,
+ * `createdAt`, `updatedAt`). Mirrors `BaseResponseSchema`. Extend it with
+ * `baseResponseSchema.extend({ ... })` to build concrete `*ResponseSchema`s.
+ */
+declare const baseResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    isActive: z.ZodBoolean;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}, {
+    id: string;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/** The inferred TS type of a {@link baseResponseSchema} payload. */
+type BaseResponse = z.infer<typeof baseResponseSchema>;
+
+/**
+ * Pagination request/response primitives, mirroring `schemas.pagination`.
+ *
+ * Offset pagination ({@link paginationFilterSchema} / {@link paginationSchema})
+ * and cursor pagination ({@link cursorPaginationFilterSchema} /
+ * {@link cursorPaginationSchema}). Field names match the `tempest-db-js`
+ * `BaseRepository.paginate` arguments so a parsed filter forwards through with
+ * no renaming.
+ */
+
+/**
+ * Filter schema for offset-paginated list endpoints. Subclass via `.extend`
+ * to add domain filters; {@link getConditions} strips the pagination keys.
+ */
+declare const paginationFilterSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    ascending: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    pageSize: number;
+    ascending: boolean;
+    orderBy?: string | undefined;
+}, {
+    page?: number | undefined;
+    pageSize?: number | undefined;
+    orderBy?: string | undefined;
+    ascending?: boolean | undefined;
+}>;
+/** The parsed shape of {@link paginationFilterSchema}. */
+type PaginationFilter = z.infer<typeof paginationFilterSchema>;
+/**
+ * Strip pagination/sort keys from a parsed filter, leaving only domain filters.
+ *
+ * @param filter - The parsed filter object (may carry extra domain fields).
+ * @param options - Extra exclude/include passed through to {@link toDict}.
+ * @returns The domain-level filter conditions.
+ */
+declare function getConditions(filter: Record<string, unknown>, options?: ToDictOptions): Record<string, unknown>;
+/**
+ * The pagination/sort keyword arguments to forward to `BaseRepository.paginate`.
+ *
+ * @param filter - The parsed pagination filter.
+ * @returns `{ page, pageSize, orderBy, ascending }`.
+ */
+declare function getPaginationConditions(filter: PaginationFilter): {
+    page: number;
+    pageSize: number;
+    orderBy?: string;
+    ascending: boolean;
+};
+/**
+ * Build the offset-pagination response envelope for a given item schema.
+ *
+ * @param item - The zod schema for a single item.
+ * @returns A zod object schema `{ items, total, page, pageSize, pages }`.
+ */
+declare function paginationSchema<T extends z.ZodTypeAny>(item: T): z.ZodObject<{
+    items: z.ZodArray<T, "many">;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    pages: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    items: T["_output"][];
+    page: number;
+    pageSize: number;
+    total: number;
+    pages: number;
+}, {
+    items: T["_input"][];
+    page: number;
+    pageSize: number;
+    total: number;
+    pages: number;
+}>;
+/** Filter schema for cursor-paginated endpoints. */
+declare const cursorPaginationFilterSchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    orderBy: z.ZodDefault<z.ZodString>;
+    ascending: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    orderBy: string;
+    ascending: boolean;
+    limit: number;
+    cursor?: string | undefined;
+}, {
+    orderBy?: string | undefined;
+    ascending?: boolean | undefined;
+    cursor?: string | undefined;
+    limit?: number | undefined;
+}>;
+/** The parsed shape of {@link cursorPaginationFilterSchema}. */
+type CursorPaginationFilter = z.infer<typeof cursorPaginationFilterSchema>;
+/**
+ * Build the cursor-pagination response envelope for a given item schema.
+ *
+ * @param item - The zod schema for a single item.
+ * @returns A zod object schema `{ items, nextCursor, hasMore, limit }`.
+ */
+declare function cursorPaginationSchema<T extends z.ZodTypeAny>(item: T): z.ZodObject<{
+    items: z.ZodArray<T, "many">;
+    nextCursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+    limit: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    items: T["_output"][];
+    limit: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+}, {
+    items: T["_input"][];
+    limit: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+}>;
+/**
+ * Serialize a cursor payload to an opaque URL-safe base64 string (no padding).
+ *
+ * @param payload - The cursor state, e.g. `{ id, value }`.
+ * @returns The encoded cursor.
+ */
+declare function encodeCursor(payload: Record<string, unknown>): string;
+/**
+ * Decode a cursor produced by {@link encodeCursor}.
+ *
+ * @param cursor - The opaque cursor string.
+ * @returns The decoded payload.
+ * @throws {Error} When the cursor is not valid base64 or not a JSON object.
+ */
+declare function decodeCursor(cursor: string): Record<string, unknown>;
+
+/**
+ * Environment-driven settings, mirroring `settings.base.BaseAppSettings`.
+ *
+ * Pydantic-settings reads env vars into a frozen, validated model. Here a zod
+ * schema plays the same role: {@link loadSettings} parses `process.env` (env
+ * names are matched case-sensitively, like the FastAPI SDK) and returns a
+ * frozen, fully-typed object. Composable fragments ({@link serverSettingsShape}
+ * etc.) cover the common server/database/CORS knobs.
+ */
+
+/** Server bind/runtime settings. Defaults bind to localhost. */
+declare const serverSettingsShape: {
+    readonly HOST: z.ZodDefault<z.ZodString>;
+    readonly PORT: z.ZodDefault<z.ZodNumber>;
+    readonly DEBUG: z.ZodDefault<z.ZodBoolean>;
+};
+/** Database connection settings. */
+declare const databaseSettingsShape: {
+    readonly DATABASE_URL: z.ZodDefault<z.ZodString>;
+};
+/** CORS settings. `CORS_ORIGINS` is a comma-separated list. */
+declare const corsSettingsShape: {
+    readonly CORS_ORIGINS: z.ZodEffects<z.ZodDefault<z.ZodString>, string[], string | undefined>;
+};
+/** The combined base settings shape (server + database + CORS). */
+declare const baseAppSettingsShape: {
+    readonly CORS_ORIGINS: z.ZodEffects<z.ZodDefault<z.ZodString>, string[], string | undefined>;
+    readonly DATABASE_URL: z.ZodDefault<z.ZodString>;
+    readonly HOST: z.ZodDefault<z.ZodString>;
+    readonly PORT: z.ZodDefault<z.ZodNumber>;
+    readonly DEBUG: z.ZodDefault<z.ZodBoolean>;
+};
+/** A zod object built from {@link baseAppSettingsShape}. */
+declare const baseAppSettingsSchema: z.ZodObject<{
+    readonly CORS_ORIGINS: z.ZodEffects<z.ZodDefault<z.ZodString>, string[], string | undefined>;
+    readonly DATABASE_URL: z.ZodDefault<z.ZodString>;
+    readonly HOST: z.ZodDefault<z.ZodString>;
+    readonly PORT: z.ZodDefault<z.ZodNumber>;
+    readonly DEBUG: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    CORS_ORIGINS: string[];
+    DATABASE_URL: string;
+    HOST: string;
+    PORT: number;
+    DEBUG: boolean;
+}, {
+    CORS_ORIGINS?: string | undefined;
+    DATABASE_URL?: string | undefined;
+    HOST?: string | undefined;
+    PORT?: number | undefined;
+    DEBUG?: boolean | undefined;
+}>;
+/** The parsed shape of {@link baseAppSettingsSchema}. */
+type BaseAppSettings = z.infer<typeof baseAppSettingsSchema>;
+/**
+ * Parse and freeze settings from an environment source.
+ *
+ * Extend the base shape with project fields:
+ *
+ * ```ts
+ * const settings = loadSettings(
+ *   z.object({ ...baseAppSettingsShape, JWT_SECRET: z.string() }),
+ * );
+ * ```
+ *
+ * @param schema - The settings zod schema.
+ * @param env - The environment source (defaults to `process.env`).
+ * @returns The validated, frozen settings object.
+ * @throws {z.ZodError} When required env vars are missing or malformed.
+ */
+declare function loadSettings<S extends z.ZodTypeAny>(schema: S, env?: NodeJS.ProcessEnv): Readonly<z.infer<S>>;
+
+/**
+ * Derive a conventional table name from a model class name: the trailing
+ * `Model` suffix is stripped and the rest snake-cased (`UserModel` → `user`).
+ *
+ * @param className - The model class name.
+ * @returns The derived table name.
+ */
+declare function tableNameFor(className: string): string;
+/**
+ * Abstract base for every model. Concrete models extend it, set a static
+ * `tablename`, and declare their own columns:
+ *
+ * ```ts
+ * class UserModel extends BaseModel {
+ *   static tablename = tableNameFor("UserModel"); // "user"
+ *   email = column.varchar(320).notNull();
+ *   name = column.text().notNull();
+ * }
+ * ```
+ */
+declare abstract class BaseModel extends Model {
+    /** Primary key — a UUID v4 generated on insert. */
+    id: tempest_db_js.Column<string, tempest_db_js.ColumnFlags & {
+        primaryKey: true;
+        hasDefault: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** Soft-delete flag; `true` means the record is active. */
+    isActive: tempest_db_js.Column<boolean, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** Creation timestamp, set by the database on insert. */
+    createdAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+    /** Last-update timestamp, refreshed by the database on every update. */
+    updatedAt: tempest_db_js.Column<Date, tempest_db_js.ColumnFlags & {
+        notNull: true;
+    } & {
+        hasDefault: true;
+    }>;
+}
+/**
+ * Soft-delete timestamp column (`deleted_at`). `null` while the row is alive;
+ * set when soft-deleted. Pairs with {@link BaseModel.isActive}.
+ *
+ * @returns A nullable datetime column builder, defaulting to `null`.
+ */
+declare function deletedAtColumn(): tempest_db_js.Column<Date, tempest_db_js.ColumnFlags>;
+/**
+ * `created_by` audit column: UUID of the user that created the row.
+ *
+ * @returns A nullable UUID column builder.
+ */
+declare function createdByColumn(): tempest_db_js.Column<string, tempest_db_js.ColumnFlags>;
+/**
+ * `updated_by` audit column: UUID of the user that last updated the row.
+ *
+ * @returns A nullable UUID column builder.
+ */
+declare function updatedByColumn(): tempest_db_js.Column<string, tempest_db_js.ColumnFlags>;
+
+/**
+ * Generic async service over a `tempest-db-js` repository.
+ *
+ * Mirrors `services.base.BaseService`: a thin business-logic layer wrapping a
+ * `BaseRepository`. Unlike a pure pass-through, every read method maps the raw
+ * ORM row through {@link ResponseMapper} into the response shape routers and
+ * controllers consume — that mapping is the layer's reason to exist. Override
+ * methods that need orchestration (multi-repository writes, side effects,
+ * domain rules); leave the rest.
+ */
+
+/** Maps a raw ORM row to the response shape (sync or async). */
+type ResponseMapper<C extends ModelClass, Resp> = (row: InferModel<C>) => Resp | Promise<Resp>;
+declare class BaseService<C extends ModelClass, Resp> {
+    protected readonly repository: BaseRepository<C>;
+    protected readonly mapToResponse: ResponseMapper<C, Resp>;
+    /**
+     * @param repository - The repository to delegate persistence to.
+     * @param mapToResponse - Maps a raw row to the response shape.
+     */
+    constructor(repository: BaseRepository<C>, mapToResponse: ResponseMapper<C, Resp>);
+    /** Map a batch of rows to responses, preserving order. */
+    protected mapMany(rows: InferModel<C>[]): Promise<Resp[]>;
+    /**
+     * Fetch a single record by primary key and map it.
+     *
+     * @param id - The primary-key value.
+     * @returns The mapped response.
+     * @throws {RecordNotFound} When no row matches (404 convention).
+     */
+    getById(id: unknown): Promise<Resp>;
+    /**
+     * List records matching `filters` (or all), mapped to responses.
+     *
+     * @param filters - Optional filter conditions.
+     * @returns The mapped responses; `[]` when nothing matches.
+     */
+    list(filters?: WhereInput<InferModel<C>>): Promise<Resp[]>;
+    /**
+     * Count records matching `filters` (or the whole table).
+     *
+     * @param filters - Optional filter conditions.
+     * @returns The matching row count.
+     */
+    count(filters?: WhereInput<InferModel<C>>): Promise<number>;
+    /**
+     * Insert one record and map the created row.
+     *
+     * @param data - The insert payload.
+     * @returns The mapped, created response.
+     */
+    create(data: InferInsert<C>): Promise<Resp>;
+    /**
+     * Update records matching `filters`.
+     *
+     * @param filters - Which rows to update.
+     * @param set - The partial column values to write.
+     * @returns The number of rows affected.
+     */
+    update(filters: WhereInput<InferModel<C>>, set: Partial<InferModel<C>>): Promise<number>;
+    /**
+     * Delete records matching `filters`.
+     *
+     * @param filters - Which rows to delete.
+     * @returns The number of rows affected.
+     */
+    delete(filters: WhereInput<InferModel<C>>): Promise<number>;
+    /**
+     * Fetch a page of records with the items mapped to responses.
+     *
+     * @param filter - Page, size, ordering and filters.
+     * @returns The page envelope with mapped items.
+     */
+    paginate(filter?: PaginationFilter$1<InferModel<C>>): Promise<PaginationResult<Resp>>;
+}
+
+/**
+ * Generic controller bridging routers and services.
+ *
+ * Mirrors `controllers.base.BaseController`. Per the SDK layering
+ * (router → controller → service → repository), controllers are an intentional
+ * abstraction boundary kept present even when no orchestration is required, so
+ * the import graph stays uniform across services. Override a method when one
+ * endpoint must call several services or apply cross-cutting policy; otherwise
+ * the thin delegations stand in for the boundary.
+ */
+
+declare class BaseController<C extends ModelClass, Resp> {
+    protected readonly service: BaseService<C, Resp>;
+    /**
+     * @param service - The service the controller delegates to.
+     */
+    constructor(service: BaseService<C, Resp>);
+    /**
+     * Fetch one record by primary key.
+     *
+     * @param id - The primary-key value.
+     * @returns The mapped response.
+     */
+    getById(id: unknown): Promise<Resp>;
+    /**
+     * List records matching `filters`.
+     *
+     * @param filters - Optional filter conditions.
+     * @returns The mapped responses.
+     */
+    list(filters?: WhereInput<InferModel<C>>): Promise<Resp[]>;
+    /**
+     * Count records matching `filters`.
+     *
+     * @param filters - Optional filter conditions.
+     * @returns The matching row count.
+     */
+    count(filters?: WhereInput<InferModel<C>>): Promise<number>;
+    /**
+     * Create a record.
+     *
+     * @param data - The insert payload.
+     * @returns The mapped, created response.
+     */
+    create(data: InferInsert<C>): Promise<Resp>;
+    /**
+     * Update records matching `filters`.
+     *
+     * @param filters - Which rows to update.
+     * @param set - The partial column values to write.
+     * @returns The number of rows affected.
+     */
+    update(filters: WhereInput<InferModel<C>>, set: Partial<InferModel<C>>): Promise<number>;
+    /**
+     * Delete records matching `filters`.
+     *
+     * @param filters - Which rows to delete.
+     * @returns The number of rows affected.
+     */
+    delete(filters: WhereInput<InferModel<C>>): Promise<number>;
+    /**
+     * Fetch a page of records.
+     *
+     * @param filter - Page, size, ordering and filters.
+     * @returns The page envelope with mapped items.
+     */
+    paginate(filter?: PaginationFilter$1<InferModel<C>>): Promise<PaginationResult<Resp>>;
+}
+
+/**
+ * Brazilian identity/contact helpers, mirroring `utils.regex`.
+ *
+ * Patterns, validators (format + check digits), normalizers, and ready-to-use
+ * Zod field schemas for the fields that show up in almost every BR API: CPF,
+ * CNPJ, CEP and phone. Validators accept masked or unmasked input; normalizers
+ * strip masks to a canonical digits-only form (and throw on invalid input).
+ */
+
+/** Match a CPF in masked (`000.000.000-00`) or raw form. */
+declare const CPF_PATTERN: RegExp;
+/** Match a CNPJ in masked (`00.000.000/0000-00`) or raw form. */
+declare const CNPJ_PATTERN: RegExp;
+/** Match a BR phone with optional `+55`, DDD, mask or 9th digit. */
+declare const PHONE_BR_PATTERN: RegExp;
+/** Match a CEP in masked (`00000-000`) or raw form. */
+declare const CEP_PATTERN: RegExp;
+/**
+ * Strip every non-digit character from `value`.
+ *
+ * @param value - The raw input (masked CPF, phone, etc.).
+ * @returns A string of only the digits in `value`.
+ */
+declare function onlyDigits(value: string): string;
+/** Whether `value` is a syntactically valid CPF (format + check digits). */
+declare function isValidCpf(value: string): boolean;
+/** Whether `value` is a syntactically valid CNPJ (format + check digits). */
+declare function isValidCnpj(value: string): boolean;
+/** Whether `value` is a valid CPF or CNPJ. */
+declare function isValidCpfCnpj(value: string): boolean;
+/** Whether `value` looks like a CEP (eight-digit shape; no check digits). */
+declare function isValidCep(value: string): boolean;
+/** Whether `value` looks like a BR phone (10 or 11 digits, optional `+55`). */
+declare function isValidPhoneBr(value: string): boolean;
+/** Normalize a CPF to 11 digits, throwing when invalid. */
+declare function normalizeCpf(value: string): string;
+/** Normalize a CNPJ to 14 digits, throwing when invalid. */
+declare function normalizeCnpj(value: string): string;
+/** Normalize a CPF/CNPJ to digits only, throwing when invalid. */
+declare function normalizeCpfCnpj(value: string): string;
+/** Normalize a CEP to 8 digits, throwing when invalid. */
+declare function normalizeCep(value: string): string;
+/** Normalize a BR phone to digits only, throwing when invalid. */
+declare function normalizePhoneBr(value: string): string;
+/** Zod field: validates a CPF and normalizes it to 11 digits. */
+declare const cpfField: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/** Zod field: validates a CNPJ and normalizes it to 14 digits. */
+declare const cnpjField: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/** Zod field: accepts either a CPF or a CNPJ, normalized to digits. */
+declare const cpfOrCnpjField: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/** Zod field: validates a CEP and normalizes it to 8 digits. */
+declare const cepField: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/** Zod field: validates a BR phone and normalizes it to digits. */
+declare const phoneBrField: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+
+/** The 27 Brazilian federative-unit acronyms. */
+declare const UF: Enum<{
+    readonly AC: "AC";
+    readonly AL: "AL";
+    readonly AP: "AP";
+    readonly AM: "AM";
+    readonly BA: "BA";
+    readonly CE: "CE";
+    readonly DF: "DF";
+    readonly ES: "ES";
+    readonly GO: "GO";
+    readonly MA: "MA";
+    readonly MT: "MT";
+    readonly MS: "MS";
+    readonly MG: "MG";
+    readonly PA: "PA";
+    readonly PB: "PB";
+    readonly PR: "PR";
+    readonly PE: "PE";
+    readonly PI: "PI";
+    readonly RJ: "RJ";
+    readonly RN: "RN";
+    readonly RS: "RS";
+    readonly RO: "RO";
+    readonly RR: "RR";
+    readonly SC: "SC";
+    readonly SP: "SP";
+    readonly SE: "SE";
+    readonly TO: "TO";
+}>;
+/** A federative-unit acronym. */
+type UFValue = ReturnType<typeof UF.values>[number];
+/** The five official IBGE macro-regions. */
+declare const Region: Enum<{
+    readonly NORTH: "Norte";
+    readonly NORTHEAST: "Nordeste";
+    readonly CENTRAL_WEST: "Centro-Oeste";
+    readonly SOUTHEAST: "Sudeste";
+    readonly SOUTH: "Sul";
+}>;
+/** A macro-region value. */
+type RegionValue = ReturnType<typeof Region.values>[number];
+/** A Brazilian federative unit and its municipalities. */
+interface StateBR {
+    /** Federative-unit acronym (e.g. `"SP"`). */
+    uf: string;
+    /** Full state name (e.g. `"São Paulo"`). */
+    name: string;
+    /** The IBGE macro-region the state belongs to. */
+    region: RegionValue;
+    /** Alphabetically sorted municipality names. */
+    cities: string[];
+}
+/** All states, ordered by acronym. */
+declare function listStates(): StateBR[];
+/** The state for a UF acronym (case-insensitive), or `null`. */
+declare function getState(uf: string): StateBR | null;
+/** The municipalities of a UF, or `[]` for an unknown UF. */
+declare function citiesByUf(uf: string): string[];
+/** All states in a macro-region. */
+declare function statesByRegion(region: RegionValue): StateBR[];
+/** Whether `value` is a known UF acronym (case-insensitive). */
+declare function isValidUf(value: string): boolean;
+/** Normalize a UF to its uppercase acronym, throwing when unknown. */
+declare function normalizeUf(value: string): string;
+/** Whether `name` is a municipality of `uf` (accent/case-insensitive). */
+declare function isValidCity(name: string, uf: string): boolean;
+/** Zod field: validates a UF and normalizes it to its uppercase acronym. */
+declare const ufField: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+
+/** Datetime helpers, mirroring `utils.datetime`. */
+/**
+ * Return the current instant. JavaScript `Date` is always UTC-based internally;
+ * serialize with `.toISOString()` for a UTC wire format.
+ *
+ * @returns The current `Date`.
+ */
+declare function utcnow(): Date;
+/**
+ * Coerce a value to a `Date`. Accepts a `Date`, an ISO string or an epoch
+ * milliseconds number.
+ *
+ * @param value - The value to normalize.
+ * @returns The corresponding `Date`.
+ * @throws {Error} When the value cannot be parsed to a valid date.
+ */
+declare function toUtc(value: Date | string | number): Date;
+
+/** Dictionary helpers, mirroring `utils.dict`. */
+/**
+ * Filter and extend a record in a single pass: drop `exclude`d keys and merge
+ * `include` on top (merged entries win).
+ *
+ * @param data - The source record.
+ * @param exclude - Keys to drop from the output.
+ * @param include - Extra entries to merge in.
+ * @returns A new record with the requested mutations.
+ */
+declare function modifyDict(data: Record<string, unknown>, exclude?: string[], include?: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Single-use opaque tokens hashed at rest, mirroring `utils.opaque_token`.
+ *
+ * For flows where a secret is emailed/SMS'd and later presented back (password
+ * reset, email verification, magic links, API keys). The plaintext is shown
+ * once; only its SHA-256 digest is stored, so a DB leak exposes no usable
+ * tokens. Verification hashes the incoming plaintext and compares in constant
+ * time. Pure standard library (`node:crypto`).
+ */
+/**
+ * Return the SHA-256 hex digest of a token's plaintext.
+ *
+ * @param plaintext - The token value to hash.
+ * @returns A 64-character lowercase hex digest.
+ */
+declare function hashOpaqueToken(plaintext: string): string;
+/**
+ * Generate a cryptographically random token and its digest.
+ *
+ * @param nbytes - Entropy in bytes for the URL-safe token (default 32).
+ * @returns `{ plaintext, tokenHash }` — show `plaintext` once, store `tokenHash`.
+ */
+declare function generateOpaqueToken(nbytes?: number): {
+    plaintext: string;
+    tokenHash: string;
+};
+/**
+ * Constant-time check that `plaintext` hashes to `tokenHash`.
+ *
+ * @param plaintext - The token submitted by the caller.
+ * @param tokenHash - The stored SHA-256 hex digest.
+ * @returns `true` when the hashes match.
+ */
+declare function verifyOpaqueToken(plaintext: string, tokenHash: string): boolean;
+
+/**
+ * Password hashing backed by bcrypt, mirroring `utils.password.PasswordUtils`.
+ *
+ * `bcryptjs` is an optional peer dependency, imported lazily so that
+ * `import "tempest-express-sdk"` keeps working when it is not installed — the
+ * clear error is deferred to first use. Methods are async (the idiomatic Node
+ * bcrypt surface).
+ */
+/** Hash and verify passwords using bcrypt. Stateless — construct once, reuse. */
+declare class PasswordUtils {
+    private readonly rounds;
+    /**
+     * @param rounds - The bcrypt cost factor. Higher is slower and harder to
+     *   brute-force. Defaults to 12.
+     */
+    constructor(rounds?: number);
+    /**
+     * Hash a plaintext password.
+     *
+     * @param plain - The plaintext password.
+     * @returns The bcrypt hash, ready to persist.
+     */
+    hash(plain: string): Promise<string>;
+    /**
+     * Verify a plaintext password against a stored hash. Returns `false` for
+     * malformed hashes rather than throwing.
+     *
+     * @param plain - The plaintext password to verify.
+     * @param hashed - The previously stored bcrypt hash.
+     * @returns `true` when the password matches.
+     */
+    verify(plain: string, hashed: string): Promise<boolean>;
+}
+
+/**
+ * JWT encode/decode backed by `jsonwebtoken`, mirroring `utils.jwt.JWTUtils`.
+ *
+ * `jsonwebtoken` is an optional peer dependency, imported lazily so the SDK
+ * imports without it; the clear error is deferred to first use. Every token
+ * gets `iat`/`exp` automatically; pass `issuer` to add and verify `iss`.
+ * Expired/invalid tokens raise the SDK's {@link ExpiredTokenException} /
+ * {@link InvalidTokenException}.
+ */
+/** JWT claims — a free-form payload. */
+type JwtClaims = Record<string, unknown>;
+/** Options for {@link JWTUtils}. */
+interface JWTUtilsOptions {
+    /** Signing algorithm. Defaults to `HS256`. */
+    algorithm?: "HS256" | "HS384" | "HS512" | "RS256" | "ES256";
+    /** Default token lifetime in seconds. Defaults to 3600 (1 hour). */
+    defaultTtlSeconds?: number;
+    /** Value for the `iss` claim; when set, `decode` verifies it. */
+    issuer?: string;
+}
+/** Encode and decode JWTs using a shared secret (or asymmetric key). */
+declare class JWTUtils {
+    private readonly secret;
+    private readonly algorithm;
+    private readonly defaultTtlSeconds;
+    private readonly issuer;
+    /**
+     * @param secret - The signing key (HMAC secret or private key).
+     * @param options - Algorithm, default TTL and optional issuer.
+     */
+    constructor(secret: string, options?: JWTUtilsOptions);
+    /**
+     * Encode `payload` as a signed JWT.
+     *
+     * @param payload - Claims to include (typically `{ sub: "<user-id>" }`).
+     * @param options - Override the default TTL for this call.
+     * @returns The compact-serialized JWT.
+     */
+    encode(payload: JwtClaims, options?: {
+        ttlSeconds?: number;
+    }): Promise<string>;
+    /**
+     * Decode and verify a JWT.
+     *
+     * @param token - The token to decode.
+     * @returns The decoded claims.
+     * @throws {ExpiredTokenException} When `exp` is in the past.
+     * @throws {InvalidTokenException} For any other validation failure.
+     */
+    decode(token: string): Promise<JwtClaims>;
+    /**
+     * Decode and verify a JWT, returning `null` on failure (soft auth).
+     *
+     * @param token - The token to decode.
+     * @returns The decoded claims, or `null` when invalid/expired.
+     */
+    decodeOrNull(token: string): Promise<JwtClaims | null>;
+}
+
+/**
+ * Attempt throttling, mirroring `utils.throttle`.
+ *
+ * Sliding-window attempt counter for flows that must resist brute force
+ * (login, OTP, code verification). The default {@link MemoryThrottleBackend} is
+ * process-local; swap in a shared backend (e.g. Redis) for multi-instance
+ * deployments by implementing {@link ThrottleBackend}.
+ */
+/** The outcome of recording or inspecting an attempt. */
+interface ThrottleStatus {
+    /** Whether the attempt is allowed (budget not yet exhausted). */
+    allowed: boolean;
+    /** Remaining attempts in the current window (never negative). */
+    remaining: number;
+    /** Seconds until the window resets (`0` when allowed). */
+    retryAfterSeconds: number;
+}
+/** Pluggable storage of attempt timestamps per key. */
+interface ThrottleBackend {
+    /** Record an attempt at `now` (epoch ms) and return timestamps in-window. */
+    hit(key: string, windowMs: number, now: number): Promise<number[]>;
+    /** Read the in-window attempt timestamps without recording a new one. */
+    peek(key: string, windowMs: number, now: number): Promise<number[]>;
+    /** Clear all recorded attempts for `key`. */
+    reset(key: string): Promise<void>;
+}
+/** Process-local {@link ThrottleBackend} backed by a `Map`. */
+declare class MemoryThrottleBackend implements ThrottleBackend {
+    private readonly store;
+    private window;
+    hit(key: string, windowMs: number, now: number): Promise<number[]>;
+    peek(key: string, windowMs: number, now: number): Promise<number[]>;
+    reset(key: string): Promise<void>;
+}
+/** Options for {@link AttemptThrottle}. */
+interface AttemptThrottleOptions {
+    /** Maximum attempts allowed within the window. */
+    maxAttempts: number;
+    /** Sliding-window length in seconds. */
+    windowSeconds: number;
+    /** Storage backend. Defaults to a {@link MemoryThrottleBackend}. */
+    backend?: ThrottleBackend;
+}
+/** A sliding-window attempt limiter keyed by an arbitrary string. */
+declare class AttemptThrottle {
+    private readonly maxAttempts;
+    private readonly windowMs;
+    private readonly backend;
+    /**
+     * @param options - Budget, window and optional backend.
+     */
+    constructor(options: AttemptThrottleOptions);
+    /** Build a status from a set of in-window attempt timestamps. */
+    private status;
+    /**
+     * Inspect the current budget for `key` without recording an attempt.
+     *
+     * @param key - The throttle key (e.g. `login:<ip>`).
+     * @returns The current status.
+     */
+    check(key: string): Promise<ThrottleStatus>;
+    /**
+     * Record an attempt for `key` and return the resulting status.
+     *
+     * @param key - The throttle key.
+     * @returns The status after recording the attempt.
+     */
+    hit(key: string): Promise<ThrottleStatus>;
+    /**
+     * Clear all recorded attempts for `key` (e.g. after a successful login).
+     *
+     * @param key - The throttle key.
+     */
+    reset(key: string): Promise<void>;
+}
+
+/**
+ * Auth DTOs (Zod), mirroring `auth.schemas`.
+ *
+ * Request/response schemas for the bundled signup/login/refresh flows. All are
+ * OpenAPI-registered shapes so they render in Swagger/Redoc when the auth
+ * router's paths are registered.
+ */
+
+/** Request body for `POST /auth/signup`. */
+declare const signupSchema: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    password: string;
+    email: string;
+    name?: string | undefined;
+}, {
+    password: string;
+    email: string;
+    name?: string | undefined;
+}>;
+/** Request body for `POST /auth/login`. */
+declare const loginSchema: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    password: string;
+    email: string;
+}, {
+    password: string;
+    email: string;
+}>;
+/** Request body for `POST /auth/refresh`. */
+declare const refreshSchema: z.ZodObject<{
+    refreshToken: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    refreshToken: string;
+}, {
+    refreshToken: string;
+}>;
+/** A signed access/refresh token pair. */
+declare const tokenPairSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    refreshToken: z.ZodString;
+    tokenType: z.ZodLiteral<"bearer">;
+    expiresIn: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    refreshToken: string;
+    accessToken: string;
+    tokenType: "bearer";
+    expiresIn: number;
+}, {
+    refreshToken: string;
+    accessToken: string;
+    tokenType: "bearer";
+    expiresIn: number;
+}>;
+/** Public user projection returned by `GET /auth/me` and signup/login. */
+declare const userPublicSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    isActive: z.ZodBoolean;
+    roles: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    isActive: boolean;
+    email: string;
+    name: string | null;
+    roles: string[];
+}, {
+    id: string;
+    isActive: boolean;
+    email: string;
+    name: string | null;
+    roles: string[];
+}>;
+/** Response body for `POST /auth/signup` and `POST /auth/login`. */
+declare const authResponseSchema: z.ZodObject<{
+    user: z.ZodObject<{
+        id: z.ZodString;
+        email: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        isActive: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        isActive: boolean;
+        email: string;
+        name: string | null;
+        roles: string[];
+    }, {
+        id: string;
+        isActive: boolean;
+        email: string;
+        name: string | null;
+        roles: string[];
+    }>;
+    tokens: z.ZodObject<{
+        accessToken: z.ZodString;
+        refreshToken: z.ZodString;
+        tokenType: z.ZodLiteral<"bearer">;
+        expiresIn: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        refreshToken: string;
+        accessToken: string;
+        tokenType: "bearer";
+        expiresIn: number;
+    }, {
+        refreshToken: string;
+        accessToken: string;
+        tokenType: "bearer";
+        expiresIn: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    user: {
+        id: string;
+        isActive: boolean;
+        email: string;
+        name: string | null;
+        roles: string[];
+    };
+    tokens: {
+        refreshToken: string;
+        accessToken: string;
+        tokenType: "bearer";
+        expiresIn: number;
+    };
+}, {
+    user: {
+        id: string;
+        isActive: boolean;
+        email: string;
+        name: string | null;
+        roles: string[];
+    };
+    tokens: {
+        refreshToken: string;
+        accessToken: string;
+        tokenType: "bearer";
+        expiresIn: number;
+    };
+}>;
+type SignupInput = z.infer<typeof signupSchema>;
+type LoginInput = z.infer<typeof loginSchema>;
+type RefreshInput = z.infer<typeof refreshSchema>;
+type TokenPair = z.infer<typeof tokenPairSchema>;
+type UserPublic = z.infer<typeof userPublicSchema>;
+type AuthResponse = z.infer<typeof authResponseSchema>;
+
+/**
+ * User authentication service, mirroring `auth.service.UserAuthService`.
+ *
+ * Orchestrates signup / login / refresh over a pluggable {@link UserStore},
+ * {@link PasswordUtils} and {@link JWTUtils}. It is ORM-agnostic — back the
+ * store with a `tempest-db-js` repository (or anything else). MFA, email
+ * activation and password-reset flows from the FastAPI SDK are not yet ported.
+ */
+
+/** A persisted user as the auth layer needs to see it. */
+interface AuthUser {
+    /** Stable user id (string form). */
+    id: string;
+    /** Login email (lowercased by the service before lookup/create). */
+    email: string;
+    /** The stored bcrypt password hash. */
+    passwordHash: string;
+    /** Display name, or `null`. */
+    name: string | null;
+    /** Whether the account may log in. */
+    isActive: boolean;
+    /** Assigned role names. */
+    roles: string[];
+}
+/** Persistence port the service depends on. Implement over any store. */
+interface UserStore {
+    /** Find a user by (lowercased) email, or `null`. */
+    findByEmail(email: string): Promise<AuthUser | null>;
+    /** Find a user by id, or `null`. */
+    findById(id: string): Promise<AuthUser | null>;
+    /** Create a user from validated signup data + a password hash. */
+    create(data: {
+        email: string;
+        passwordHash: string;
+        name: string | null;
+    }): Promise<AuthUser>;
+}
+/** Options for {@link UserAuthService}. */
+interface UserAuthServiceOptions {
+    /** The user persistence port. */
+    store: UserStore;
+    /** Password hasher/verifier. */
+    password: PasswordUtils;
+    /** JWT encoder/decoder used to mint access + refresh tokens. */
+    jwt: JWTUtils;
+    /** Minimum password length enforced server-side. Default 12. */
+    passwordMinLength?: number;
+    /** Access-token lifetime in seconds. Default 3600. */
+    accessTtlSeconds?: number;
+    /** Refresh-token lifetime in seconds. Default 1209600 (14 days). */
+    refreshTtlSeconds?: number;
+}
+declare class UserAuthService {
+    private readonly store;
+    private readonly password;
+    private readonly jwt;
+    private readonly passwordMinLength;
+    private readonly accessTtlSeconds;
+    private readonly refreshTtlSeconds;
+    /**
+     * @param options - Store, password/JWT helpers and token policy.
+     */
+    constructor(options: UserAuthServiceOptions);
+    /** Mint a signed access + refresh token pair for `user`. */
+    private issueTokens;
+    /**
+     * Register a new user and issue tokens.
+     *
+     * @param data - Validated signup payload.
+     * @returns The public user and a fresh token pair.
+     * @throws {ValidationException} When the password is too short.
+     * @throws {ConflictException} When the email is already registered.
+     */
+    signup(data: SignupInput): Promise<AuthResponse>;
+    /**
+     * Authenticate a user by email + password.
+     *
+     * @param data - Validated login payload.
+     * @returns The public user and a fresh token pair.
+     * @throws {UnauthorizedException} On bad credentials or inactive account.
+     */
+    login(data: LoginInput): Promise<AuthResponse>;
+    /**
+     * Exchange a valid refresh token for a new token pair.
+     *
+     * @param refreshToken - The refresh token from a prior login.
+     * @returns The public user and a fresh token pair.
+     * @throws {UnauthorizedException} When the token is invalid or not a refresh
+     *   token, or the user no longer exists / is inactive.
+     */
+    refresh(refreshToken: string): Promise<AuthResponse>;
+}
+
+/**
+ * JWT auth middleware + role guards, mirroring `api.dependencies.auth`.
+ *
+ * {@link makeJwtAuthMiddleware} decodes a `Bearer` token and attaches the
+ * claims to `req.auth`; {@link requireRoles} gates a route on role membership.
+ * Failures raise the SDK's {@link UnauthorizedException} / {@link ForbiddenException}
+ * so they render as the canonical error envelope.
+ */
+
+declare global {
+    namespace Express {
+        /** Decoded JWT claims, populated by {@link makeJwtAuthMiddleware}. */
+        interface Request {
+            auth?: JwtClaims;
+        }
+    }
+}
+/** Extract a `Bearer` token from the `Authorization` header, or `null`. */
+declare function bearerToken(req: Request): string | null;
+/** Read the decoded claims attached by the auth middleware, or `null`. */
+declare function getAuth(req: Request): JwtClaims | null;
+/** Options for {@link makeJwtAuthMiddleware}. */
+interface JwtAuthOptions {
+    /** When `true` (default), a missing/invalid token rejects with 401. */
+    required?: boolean;
+}
+/**
+ * Build middleware that decodes the bearer token and sets `req.auth`.
+ *
+ * @param jwt - The JWT helper used to verify tokens.
+ * @param options - Whether authentication is required.
+ * @returns An Express middleware.
+ */
+declare function makeJwtAuthMiddleware(jwt: JWTUtils, options?: JwtAuthOptions): RequestHandler;
+/**
+ * Build middleware that requires the authenticated user to hold at least one
+ * of `roles` (read from the `roles` claim). Must run after the auth middleware.
+ *
+ * @param roles - Acceptable role names.
+ * @returns An Express middleware.
+ */
+declare function requireRoles(...roles: string[]): RequestHandler;
+
+/**
+ * OpenAPI document generation from Zod schemas.
+ *
+ * Thin wrapper over `@asteasolutions/zod-to-openapi`. Register schemas and
+ * paths on a {@link OpenAPIRegistry}, then call {@link generateOpenApiDocument}
+ * to produce a spec that drives both Swagger UI and Redoc. Because every SDK
+ * schema is built from the `.openapi()`-augmented `z`, descriptions, examples
+ * and component names flow straight into the document.
+ */
+
+/** Minimal `info` block for the generated document. */
+interface OpenApiInfo {
+    /** API title shown in the docs header. */
+    title: string;
+    /** API version string. */
+    version: string;
+    /** Optional long description (Markdown supported by the renderers). */
+    description?: string;
+}
+/** Options for {@link generateOpenApiDocument}. */
+interface GenerateOpenApiOptions {
+    /** The document `info` block. */
+    info: OpenApiInfo;
+    /** Server entries (`{ url, description }`). */
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    /** Emit OpenAPI 3.1 instead of 3.0. Default `false` (3.0). */
+    v31?: boolean;
+}
+/**
+ * Create a fresh, empty {@link OpenAPIRegistry}.
+ *
+ * @returns A registry to register schemas and paths on.
+ */
+declare function createOpenApiRegistry(): OpenAPIRegistry;
+/**
+ * Generate an OpenAPI document from a populated registry.
+ *
+ * @param registry - The registry holding registered schemas and paths.
+ * @param options - The `info` block, optional servers and version flag.
+ * @returns The generated OpenAPI document (plain object, JSON-serializable).
+ */
+declare function generateOpenApiDocument(registry: OpenAPIRegistry, options: GenerateOpenApiOptions): Record<string, unknown>;
+
+/**
+ * Auth router, mirroring `auth.router.make_auth_router`.
+ *
+ * Wires `POST /auth/signup`, `POST /auth/login`, `POST /auth/refresh` and a
+ * guarded `GET /auth/me` to a {@link UserAuthService}. Pass an
+ * {@link OpenAPIRegistry} to register the paths so they appear in Swagger/Redoc.
+ */
+
+/** Options for {@link makeAuthRouter}. */
+interface AuthRouterOptions {
+    /** The authentication service handling the flows. */
+    service: UserAuthService;
+    /** The JWT helper used to guard `GET /auth/me`. */
+    jwt: JWTUtils;
+    /** Route prefix. Default `/auth`. */
+    prefix?: string;
+    /** When provided, OpenAPI paths are registered for Swagger/Redoc. */
+    registry?: OpenAPIRegistry;
+}
+/**
+ * Build the auth router.
+ *
+ * @param options - Service, JWT helper, prefix and optional OpenAPI registry.
+ * @returns An Express router exposing the auth endpoints.
+ */
+declare function makeAuthRouter(options: AuthRouterOptions): Router;
+
+/**
+ * Express error handling, mirroring `api.handlers`.
+ *
+ * Produces the canonical SDK envelope `{ detail, code, details }` for every
+ * failure path: {@link AppException} subclasses, Zod validation errors (→ 422),
+ * unmatched routes (→ 404) and uncaught errors (→ 500). A {@link MessageCatalog}
+ * localizes `detail` from the request `Accept-Language` header. Server errors
+ * are logged with the {@link HTTP_500_MARKER} flag for sink routing.
+ */
+
+/** Header carrying the per-request correlation id. */
+declare const REQUEST_ID_HEADER = "X-Request-ID";
+/**
+ * Middleware that establishes a request id and binds the request context.
+ *
+ * Reuses an inbound `X-Request-ID` when present, otherwise generates one, sets
+ * it on the response, and runs the rest of the chain inside
+ * {@link runWithRequestContext} so loggers and handlers can read it.
+ *
+ * @returns The configured middleware.
+ */
+declare function requestIdMiddleware(): RequestHandler;
+/** Options for {@link makeAppExceptionHandler}. */
+interface AppExceptionHandlerOptions {
+    /** Catalog used to localize `detail`; `null` keeps the literal message. */
+    catalog?: MessageCatalog | null;
+    /** Locale used when `Accept-Language` is absent or unmatched. */
+    defaultLocale?: string;
+    /** Level used for 5xx `AppException` records (4xx always logs at `info`). */
+    serverErrorLevel?: LogLevel;
+}
+/**
+ * Build the error middleware for {@link AppException} subclasses.
+ *
+ * Zod errors are coerced into a 422 envelope (`code: "VALIDATION_ERROR"`) with
+ * the field issues under `details.issues`. Anything else is passed to `next`.
+ *
+ * @param options - Localization and logging options.
+ * @returns An Express error middleware.
+ */
+declare function makeAppExceptionHandler(options?: AppExceptionHandlerOptions): ErrorRequestHandler;
+/** Options for {@link makeUnhandledExceptionHandler}. */
+interface UnhandledExceptionHandlerOptions {
+    /** Surface the stack under `details.stack` (development only). */
+    includeStack?: boolean;
+    /** Level used to log the failure. */
+    logLevel?: LogLevel;
+}
+/**
+ * Build the catch-all error middleware for non-{@link AppException} errors.
+ *
+ * Logs the failure (flagged with {@link HTTP_500_MARKER}) and returns the
+ * canonical 500 envelope. With `includeStack` the stack is added to the body —
+ * never enable in production.
+ *
+ * @param options - Stack-exposure and logging options.
+ * @returns An Express error middleware.
+ */
+declare function makeUnhandledExceptionHandler(options?: UnhandledExceptionHandlerOptions): ErrorRequestHandler;
+/**
+ * Build the fallback 404 handler for unmatched routes.
+ *
+ * @returns A request handler emitting the canonical 404 envelope.
+ */
+declare function notFoundHandler(): RequestHandler;
+/** Options for {@link registerExceptionHandlers}. */
+interface RegisterExceptionHandlersOptions extends AppExceptionHandlerOptions, UnhandledExceptionHandlerOptions {
+    /** Register the {@link notFoundHandler} for unmatched routes. Default `true`. */
+    notFound?: boolean;
+}
+/**
+ * Register the full error-handling stack on an Express app.
+ *
+ * Call this AFTER all routers are mounted. Order: 404 fallback (optional) →
+ * {@link AppException}/Zod handler → catch-all 500 handler.
+ *
+ * @param app - The Express application.
+ * @param options - Localization, logging and 404 options.
+ */
+declare function registerExceptionHandlers(app: Express, options?: RegisterExceptionHandlersOptions): void;
+
+/**
+ * Native Swagger UI and Redoc mounting from a generated OpenAPI document.
+ *
+ * Swagger UI is served fully self-contained: its static assets ship with the
+ * `swagger-ui-dist` dependency and are mounted locally (no CDN), with a small
+ * inline initializer pointing at the spec endpoint. Redoc is served as a single
+ * HTML page that loads the Redoc standalone bundle from a CDN (the renderer is
+ * ~1 MB and intentionally not vendored); override {@link RedocOptions.scriptUrl}
+ * to self-host it.
+ */
+
+/** A JSON-serializable OpenAPI document. */
+type OpenApiDocument = Record<string, unknown>;
+/**
+ * Mount the OpenAPI document as JSON at `path`.
+ *
+ * @param app - The Express application.
+ * @param path - Route to serve the document at (e.g. `/openapi.json`).
+ * @param document - The generated OpenAPI document.
+ */
+declare function mountOpenApiJson(app: Express, path: string, document: OpenApiDocument): void;
+/** Options for {@link mountSwaggerUi}. */
+interface SwaggerOptions {
+    /** Page title. Default `"API docs"`. */
+    title?: string;
+}
+/**
+ * Mount Swagger UI at `path`, reading the spec from `specUrl`.
+ *
+ * Static assets are served from `${path}/assets` so the page is fully offline.
+ *
+ * @param app - The Express application.
+ * @param path - Mount path for the UI (e.g. `/docs`).
+ * @param specUrl - URL the UI fetches the OpenAPI document from.
+ * @param options - Page options.
+ */
+declare function mountSwaggerUi(app: Express, path: string, specUrl: string, options?: SwaggerOptions): void;
+/** Options for {@link mountRedoc}. */
+interface RedocOptions {
+    /** Page title. Default `"API reference"`. */
+    title?: string;
+    /** URL of the Redoc standalone bundle. Defaults to the jsDelivr CDN. */
+    scriptUrl?: string;
+}
+/**
+ * Mount Redoc at `path`, reading the spec from `specUrl`.
+ *
+ * @param app - The Express application.
+ * @param path - Mount path for Redoc (e.g. `/redoc`).
+ * @param specUrl - URL Redoc fetches the OpenAPI document from.
+ * @param options - Page and bundle options.
+ */
+declare function mountRedoc(app: Express, path: string, specUrl: string, options?: RedocOptions): void;
+
+/**
+ * Health-check router, mirroring `api.routers.health`.
+ *
+ * A meta endpoint mounted at the root prefix (not under `/api`). Returns a
+ * small JSON status payload and runs any registered async checks, surfacing
+ * their pass/fail under `checks` and degrading the HTTP status to 503 when any
+ * check fails.
+ */
+
+/** A named async health probe returning `true` when healthy. */
+interface HealthCheck {
+    /** Probe name, surfaced under `checks`. */
+    name: string;
+    /** The probe; resolves `true` when the dependency is healthy. */
+    check: () => Promise<boolean> | boolean;
+}
+/** Options for {@link makeHealthRouter}. */
+interface HealthRouterOptions {
+    /** Route path within the router. Default `/health`. */
+    path?: string;
+    /** Optional dependency probes (e.g. database, cache). */
+    checks?: HealthCheck[];
+}
+/**
+ * Build a health-check router.
+ *
+ * @param options - Path and dependency probes.
+ * @returns An Express router exposing the health endpoint.
+ */
+declare function makeHealthRouter(options?: HealthRouterOptions): Router;
+
+/**
+ * Application factory and server runner, mirroring `api.app` + `api.server`.
+ *
+ * {@link createApp} wires the conventional middleware stack (JSON body parsing,
+ * request-id propagation, optional CORS), mounts the health endpoint, lets the
+ * caller register routers and OpenAPI paths via a `configure` hook, mounts
+ * native Swagger UI + Redoc, then registers the error-handling stack last.
+ * {@link runServer} starts listening and logs the bound address.
+ */
+
+/** OpenAPI documentation configuration for {@link createApp}. */
+interface CreateAppOpenApi extends GenerateOpenApiOptions {
+    /** Registry holding the registered schemas and paths. */
+    registry: OpenAPIRegistry;
+    /** Route serving the spec JSON. Default `/openapi.json`. */
+    jsonPath?: string;
+    /** Swagger UI mount path, or `false` to disable. Default `/docs`. */
+    swaggerPath?: string | false;
+    /** Redoc mount path, or `false` to disable. Default `/redoc`. */
+    redocPath?: string | false;
+    /** Extra Swagger UI options. */
+    swagger?: SwaggerOptions;
+    /** Extra Redoc options. */
+    redoc?: RedocOptions;
+}
+/** Options for {@link createApp}. */
+interface CreateAppOptions {
+    /** Allowed CORS origins. `"*"` or a list; omit/`false` to disable CORS. */
+    corsOrigins?: string | string[] | false;
+    /** Health endpoint options, or `false` to omit it. Default mounts `/health`. */
+    health?: HealthRouterOptions | false;
+    /** Hook to mount routers and register OpenAPI paths before the error stack. */
+    configure?: (app: Express) => void | Promise<void>;
+    /** OpenAPI docs configuration; omit to skip Swagger/Redoc. */
+    openapi?: CreateAppOpenApi;
+    /** Message catalog for localized error responses. */
+    catalog?: MessageCatalog;
+    /** Error-handling options forwarded to {@link registerExceptionHandlers}. */
+    errorHandling?: Omit<RegisterExceptionHandlersOptions, "catalog">;
+    /** JSON body size limit (e.g. `"1mb"`). Default `"100kb"`. */
+    jsonLimit?: string;
+}
+/**
+ * Build a fully wired Express application.
+ *
+ * @param options - Middleware, health, OpenAPI docs and error options.
+ * @returns The configured Express app, ready to {@link runServer}.
+ */
+declare function createApp(options?: CreateAppOptions): Promise<Express>;
+/** Options for {@link runServer}. */
+interface RunServerOptions {
+    /** Bind host. Default `127.0.0.1`. */
+    host?: string;
+    /** Bind port. Default `8000`. */
+    port?: number;
+}
+/**
+ * Start listening and log the bound address.
+ *
+ * @param app - The Express application from {@link createApp}.
+ * @param options - Host and port.
+ * @returns A promise resolving to the live HTTP server once listening.
+ */
+declare function runServer(app: Express, options?: RunServerOptions): Promise<Server>;
+
+/** The installed SDK version. Single source of truth for the barrel + CLI. */
+declare const VERSION = "0.1.0";
+
+export { AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CatalogData, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type Enum, type EnumHelpers, type EnumSpec, type ExceptionDetails, ExpiredTokenException, ForbiddenException, type GenerateOpenApiOptions, HTTP_500_MARKER, type HealthCheck, type HealthRouterOptions, InvalidTokenException, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, type LogExtra, type LogLevel, type LoginInput, MemoryThrottleBackend, MessageCatalog, NotFoundException, type OpenApiDocument, type OpenApiInfo, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, type RunServerOptions, type SignupInput, type StateBR, type SwaggerOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, cepField, citiesByUf, cnpjField, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAppExceptionHandler, makeAuthRouter, makeHealthRouter, makeJwtAuthMiddleware, makeUnhandledExceptionHandler, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, setRequestId, signupSchema, statesByRegion, tableNameFor, toDict, toUtc, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken };