tempest-express-sdk 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -2641,6 +2641,132 @@ interface TwilioWebhookOptions {
  */
 declare function makeTwilioWebhookRouter(options: TwilioWebhookOptions): Router;
 
+/**
+ * Email channel — a {@link MessagingProvider} over {@link EmailUtils}.
+ *
+ * Lets transactional email participate in the same swappable messaging contract
+ * as WhatsApp/Telegram/SMS: `sendText` sends a plain email, `sendMedia` sends
+ * the media as a link in the body. Inbound (`onMessage`) is absent — email
+ * ingestion is out of scope. Requires the optional `nodemailer` peer via
+ * {@link EmailUtils}.
+ */
+
+/** Options for {@link EmailProvider}. */
+interface EmailProviderOptions {
+    /** The configured SMTP sender. */
+    email: EmailUtils;
+    /** Default subject line for `sendText`/`sendMedia`. Default `"Notification"`. */
+    subject?: string;
+}
+/** An email-backed {@link MessagingProvider}. */
+declare class EmailProvider implements MessagingProvider {
+    private readonly email;
+    private readonly subject;
+    /**
+     * @param options - The email sender and default subject.
+     */
+    constructor(options: EmailProviderOptions);
+    /**
+     * Send a plain-text email.
+     *
+     * @param to - Recipient address.
+     * @param text - Body text (also used as HTML).
+     * @returns A sent result.
+     */
+    sendText(to: string, text: string): Promise<OutboundResult>;
+    /**
+     * Send an email linking to the media (caption becomes the lead text).
+     *
+     * @param to - Recipient address.
+     * @param media - The media reference (URL) + optional caption.
+     * @returns A sent result.
+     */
+    sendMedia(to: string, media: OutboundMedia): Promise<OutboundResult>;
+    /** Always `"connected"` — SMTP reachability is verified on first send. */
+    status(): Promise<string>;
+}
+
+/**
+ * Broadcast + multi-channel helpers over {@link MessagingProvider}.
+ *
+ * {@link broadcastText} fans one message out to many recipients through a single
+ * provider, with bounded concurrency and a per-recipient result (one failure
+ * never aborts the rest). {@link MessagingHub} keeps named providers so app code
+ * sends by channel name and can broadcast across all of them.
+ */
+
+/** The outcome of a single recipient's send within a broadcast. */
+interface BroadcastResult {
+    /** The recipient address/handle. */
+    to: string;
+    /** Whether the send succeeded. */
+    ok: boolean;
+    /** The provider result, when successful. */
+    result?: OutboundResult;
+    /** The error message, when failed. */
+    error?: string;
+}
+/** Options for {@link broadcastText}. */
+interface BroadcastOptions extends SendOptions {
+    /** Maximum concurrent sends. Default 10. */
+    concurrency?: number;
+}
+/**
+ * Send `text` to every recipient through `provider`, bounded by concurrency.
+ *
+ * A failed recipient is captured in its {@link BroadcastResult} (`ok: false`)
+ * rather than aborting the batch.
+ *
+ * @param provider - The channel to send through.
+ * @param recipients - Recipient addresses/handles.
+ * @param text - The message body.
+ * @param options - Concurrency + send options.
+ * @returns One result per recipient, in input order.
+ */
+declare function broadcastText(provider: MessagingProvider, recipients: string[], text: string, options?: BroadcastOptions): Promise<BroadcastResult[]>;
+/** A registry of named messaging channels. */
+declare class MessagingHub {
+    private readonly channels;
+    /**
+     * Register a provider under a channel name.
+     *
+     * @param name - The channel name (e.g. `"whatsapp"`, `"sms"`).
+     * @param provider - The provider implementation.
+     * @returns The hub (chainable).
+     */
+    register(name: string, provider: MessagingProvider): this;
+    /**
+     * Get a registered provider, throwing when the channel is unknown.
+     *
+     * @param name - The channel name.
+     * @returns The provider.
+     * @throws {Error} When no provider is registered under `name`.
+     */
+    get(name: string): MessagingProvider;
+    /** The registered channel names. */
+    channelNames(): string[];
+    /**
+     * Send text through a named channel.
+     *
+     * @param channel - The channel name.
+     * @param to - The recipient.
+     * @param text - The message body.
+     * @param options - Send options.
+     * @returns The provider result.
+     */
+    send(channel: string, to: string, text: string, options?: SendOptions): Promise<OutboundResult>;
+    /**
+     * Broadcast text to many recipients on a named channel.
+     *
+     * @param channel - The channel name.
+     * @param recipients - Recipient addresses/handles.
+     * @param text - The message body.
+     * @param options - Broadcast + send options.
+     * @returns One result per recipient.
+     */
+    broadcast(channel: string, recipients: string[], text: string, options?: BroadcastOptions): Promise<BroadcastResult[]>;
+}
+
 /**
  * Admin site + resource registry, mirroring `admin.site` / `admin.config`.
  *
@@ -2919,6 +3045,17 @@ declare const mfaCodeSchema: z.ZodObject<{
 }, {
     code: string;
 }>;
+/** MFA login-challenge body (`POST /auth/mfa/challenge`). */
+declare const mfaChallengeSchema: z.ZodObject<{
+    mfaToken: z.ZodString;
+    code: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    mfaToken: string;
+}, {
+    code: string;
+    mfaToken: string;
+}>;
 /** Activation body (`POST /auth/activate`). */
 declare const activationSchema: z.ZodObject<{
     token: z.ZodString;
@@ -2953,17 +3090,100 @@ type TokenPair = z.infer<typeof tokenPairSchema>;
 type UserPublic = z.infer<typeof userPublicSchema>;
 type AuthResponse = z.infer<typeof authResponseSchema>;
 type MfaCodeInput = z.infer<typeof mfaCodeSchema>;
+type MfaChallengeInput = z.infer<typeof mfaChallengeSchema>;
 type ActivationInput = z.infer<typeof activationSchema>;
 type PasswordResetRequestInput = z.infer<typeof passwordResetRequestSchema>;
 type PasswordResetConfirmInput = z.infer<typeof passwordResetConfirmSchema>;
 
+/**
+ * TOTP MFA enrollment/verification, mirroring the FastAPI SDK MFA flow.
+ *
+ * Orchestrates {@link TOTPHelper} over a pluggable {@link MfaStore}: enroll
+ * (generate + persist a secret, return the provisioning URI), confirm (verify a
+ * code and flip MFA on), verify (login step) and disable.
+ */
+
+/** Persistence port for MFA secrets/state. */
+interface MfaStore {
+    /** Persist a user's TOTP secret (pending until confirmed). */
+    setSecret(userId: string, secret: string): Promise<void>;
+    /** Read a user's TOTP secret, or `null`. */
+    getSecret(userId: string): Promise<string | null>;
+    /** Flip the MFA-enabled flag. */
+    setEnabled(userId: string, enabled: boolean): Promise<void>;
+    /** Whether MFA is enabled for the user. */
+    isEnabled(userId: string): Promise<boolean>;
+}
+/** The result of starting enrollment. */
+interface MfaEnrollment {
+    /** The base32 secret (persist server-side; also shown once for manual entry). */
+    secret: string;
+    /** The `otpauth://` URI to render as a QR code. */
+    otpauthUri: string;
+}
+/** Options for {@link MfaService}. */
+interface MfaServiceOptions {
+    /** The MFA persistence port. */
+    store: MfaStore;
+    /** The TOTP helper (issuer preconfigured). */
+    totp: TOTPHelper;
+}
+declare class MfaService {
+    private readonly store;
+    private readonly totp;
+    /**
+     * @param options - Store and TOTP helper.
+     */
+    constructor(options: MfaServiceOptions);
+    /**
+     * Begin enrollment: generate and persist a secret, return the QR URI.
+     *
+     * @param userId - The enrolling user.
+     * @param accountName - Label shown in the authenticator (usually the email).
+     * @returns The secret and provisioning URI.
+     */
+    enroll(userId: string, accountName: string): Promise<MfaEnrollment>;
+    /**
+     * Confirm enrollment by verifying a code, enabling MFA on success.
+     *
+     * @param userId - The user.
+     * @param code - The 6-digit code from the authenticator.
+     * @throws {ValidationException} When no secret is pending or the code is wrong.
+     */
+    confirm(userId: string, code: string): Promise<void>;
+    /**
+     * Verify a code (login step). Returns `false` without throwing.
+     *
+     * @param userId - The user.
+     * @param code - The submitted code.
+     * @returns `true` when the code is valid.
+     */
+    verify(userId: string, code: string): Promise<boolean>;
+    /**
+     * Whether MFA is enabled for a user (used to gate the login challenge).
+     *
+     * @param userId - The user.
+     * @returns `true` when MFA is enabled.
+     */
+    isEnabled(userId: string): Promise<boolean>;
+    /**
+     * Disable MFA after verifying a code.
+     *
+     * @param userId - The user.
+     * @param code - The submitted code.
+     * @throws {ValidationException} When the code is invalid.
+     */
+    disable(userId: string, code: string): Promise<void>;
+}
+
 /**
  * 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.
+ * store with a `tempest-db-js` repository (or anything else). With an
+ * {@link MfaService} wired in, `login` returns an MFA challenge for enrolled
+ * users (complete it via {@link UserAuthService.verifyMfaChallenge}).
  */
 
 /** A persisted user as the auth layer needs to see it. */
@@ -3008,7 +3228,23 @@ interface UserAuthServiceOptions {
     accessTtlSeconds?: number;
     /** Refresh-token lifetime in seconds. Default 1209600 (14 days). */
     refreshTtlSeconds?: number;
-}
+    /**
+     * When provided, `login` returns an MFA challenge instead of tokens for users
+     * with MFA enabled; complete it with {@link UserAuthService.verifyMfaChallenge}.
+     */
+    mfa?: MfaService;
+    /** MFA challenge-token lifetime in seconds. Default 300 (5 min). */
+    mfaChallengeTtlSeconds?: number;
+}
+/** Returned by `login` when the user must complete an MFA challenge. */
+interface MfaChallenge {
+    /** Discriminator: an MFA step is required before tokens are issued. */
+    mfaRequired: true;
+    /** Short-lived token to submit alongside the code to `verifyMfaChallenge`. */
+    mfaToken: string;
+}
+/** `login` result: either full auth, or an MFA challenge to complete. */
+type LoginResult = AuthResponse | MfaChallenge;
 declare class UserAuthService {
     private readonly store;
     private readonly password;
@@ -3016,6 +3252,8 @@ declare class UserAuthService {
     private readonly passwordMinLength;
     private readonly accessTtlSeconds;
     private readonly refreshTtlSeconds;
+    private readonly mfa;
+    private readonly mfaChallengeTtlSeconds;
     /**
      * @param options - Store, password/JWT helpers and token policy.
      */
@@ -3035,10 +3273,20 @@ declare class UserAuthService {
      * Authenticate a user by email + password.
      *
      * @param data - Validated login payload.
-     * @returns The public user and a fresh token pair.
+     * @returns Full auth, or an {@link MfaChallenge} when MFA is enabled.
      * @throws {UnauthorizedException} On bad credentials or inactive account.
      */
-    login(data: LoginInput): Promise<AuthResponse>;
+    login(data: LoginInput): Promise<LoginResult>;
+    /**
+     * Complete an MFA login challenge: verify the code and issue tokens.
+     *
+     * @param mfaToken - The challenge token from {@link login}.
+     * @param code - The authenticator code.
+     * @returns The public user and a fresh token pair.
+     * @throws {UnauthorizedException} When the challenge/code is invalid, MFA is
+     *   not configured, or the account no longer exists / is inactive.
+     */
+    verifyMfaChallenge(mfaToken: string, code: string): Promise<AuthResponse>;
     /**
      * Exchange a valid refresh token for a new token pair.
      *
@@ -3050,80 +3298,6 @@ declare class UserAuthService {
     refresh(refreshToken: string): Promise<AuthResponse>;
 }
 
-/**
- * TOTP MFA enrollment/verification, mirroring the FastAPI SDK MFA flow.
- *
- * Orchestrates {@link TOTPHelper} over a pluggable {@link MfaStore}: enroll
- * (generate + persist a secret, return the provisioning URI), confirm (verify a
- * code and flip MFA on), verify (login step) and disable.
- */
-
-/** Persistence port for MFA secrets/state. */
-interface MfaStore {
-    /** Persist a user's TOTP secret (pending until confirmed). */
-    setSecret(userId: string, secret: string): Promise<void>;
-    /** Read a user's TOTP secret, or `null`. */
-    getSecret(userId: string): Promise<string | null>;
-    /** Flip the MFA-enabled flag. */
-    setEnabled(userId: string, enabled: boolean): Promise<void>;
-    /** Whether MFA is enabled for the user. */
-    isEnabled(userId: string): Promise<boolean>;
-}
-/** The result of starting enrollment. */
-interface MfaEnrollment {
-    /** The base32 secret (persist server-side; also shown once for manual entry). */
-    secret: string;
-    /** The `otpauth://` URI to render as a QR code. */
-    otpauthUri: string;
-}
-/** Options for {@link MfaService}. */
-interface MfaServiceOptions {
-    /** The MFA persistence port. */
-    store: MfaStore;
-    /** The TOTP helper (issuer preconfigured). */
-    totp: TOTPHelper;
-}
-declare class MfaService {
-    private readonly store;
-    private readonly totp;
-    /**
-     * @param options - Store and TOTP helper.
-     */
-    constructor(options: MfaServiceOptions);
-    /**
-     * Begin enrollment: generate and persist a secret, return the QR URI.
-     *
-     * @param userId - The enrolling user.
-     * @param accountName - Label shown in the authenticator (usually the email).
-     * @returns The secret and provisioning URI.
-     */
-    enroll(userId: string, accountName: string): Promise<MfaEnrollment>;
-    /**
-     * Confirm enrollment by verifying a code, enabling MFA on success.
-     *
-     * @param userId - The user.
-     * @param code - The 6-digit code from the authenticator.
-     * @throws {ValidationException} When no secret is pending or the code is wrong.
-     */
-    confirm(userId: string, code: string): Promise<void>;
-    /**
-     * Verify a code (login step). Returns `false` without throwing.
-     *
-     * @param userId - The user.
-     * @param code - The submitted code.
-     * @returns `true` when the code is valid.
-     */
-    verify(userId: string, code: string): Promise<boolean>;
-    /**
-     * Disable MFA after verifying a code.
-     *
-     * @param userId - The user.
-     * @param code - The submitted code.
-     * @throws {ValidationException} When the code is invalid.
-     */
-    disable(userId: string, code: string): Promise<void>;
-}
-
 /**
  * Email-activation flow, mirroring the FastAPI SDK activation flow.
  *
@@ -3623,6 +3797,6 @@ interface RunServerOptions {
 declare function runServer(app: Express, options?: RunServerOptions): Promise<Server>;
 
 /** The installed SDK version. Single source of truth for the barrel + CLI. */
-declare const VERSION = "0.9.0";
+declare const VERSION = "0.11.0";
 
-export { type ActivationInput, ActivationService, type ActivationServiceOptions, type ActivationStore, type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, type CacheManager, type CachedOptions, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type EmailMessage, type EmailOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GPUMetrics, type GenerateOpenApiOptions, HTTPClient, type HTTPClientOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, type MessagingProvider, type MetricsRouterOptions, MetricsUtils, type MfaCodeInput, type MfaEnrollment, MfaService, type MfaServiceOptions, type MfaStore, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, type PasswordResetConfirmInput, type PasswordResetRequestInput, PasswordResetService, type PasswordResetServiceOptions, type PasswordResetStore, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedisPublisherLike, RedisSSEBroker, type RedisSSEBrokerOptions, RedisSessionStore, type RedisSubscriberLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, RetryPolicy, type RunServerOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, type SessionRedisLike, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, activationSchema, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeMetricsRouter, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaCodeSchema, mfaEnrollResponseSchema, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { type ActivationInput, ActivationService, type ActivationServiceOptions, type ActivationStore, type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BroadcastOptions, type BroadcastResult, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, type CacheManager, type CachedOptions, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type EmailMessage, type EmailOptions, EmailProvider, type EmailProviderOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GPUMetrics, type GenerateOpenApiOptions, HTTPClient, type HTTPClientOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, type LoginResult, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, MessagingHub, type MessagingProvider, type MetricsRouterOptions, MetricsUtils, type MfaChallenge, type MfaChallengeInput, type MfaCodeInput, type MfaEnrollment, MfaService, type MfaServiceOptions, type MfaStore, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, type PasswordResetConfirmInput, type PasswordResetRequestInput, PasswordResetService, type PasswordResetServiceOptions, type PasswordResetStore, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedisPublisherLike, RedisSSEBroker, type RedisSSEBrokerOptions, RedisSessionStore, type RedisSubscriberLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, RetryPolicy, type RunServerOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, type SessionRedisLike, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, activationSchema, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, broadcastText, buildContentDisposition, 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, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeMetricsRouter, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaChallengeSchema, mfaCodeSchema, mfaEnrollResponseSchema, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { VERSION } from './chunk-4QZZGHGV.js';
+export { VERSION } from './chunk-IHO6X75J.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV31, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
 export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
@@ -8581,6 +8581,133 @@ function makeTwilioWebhookRouter(options) {
   return router;
 }
 
+// src/integrations/email.ts
+var EmailProvider = class {
+  email;
+  subject;
+  /**
+   * @param options - The email sender and default subject.
+   */
+  constructor(options) {
+    this.email = options.email;
+    this.subject = options.subject ?? "Notification";
+  }
+  /**
+   * Send a plain-text email.
+   *
+   * @param to - Recipient address.
+   * @param text - Body text (also used as HTML).
+   * @returns A sent result.
+   */
+  async sendText(to, text) {
+    await this.email.send({ to, subject: this.subject, text });
+    return { status: "sent" };
+  }
+  /**
+   * Send an email linking to the media (caption becomes the lead text).
+   *
+   * @param to - Recipient address.
+   * @param media - The media reference (URL) + optional caption.
+   * @returns A sent result.
+   */
+  async sendMedia(to, media) {
+    const caption = media.caption ?? "";
+    await this.email.send({
+      to,
+      subject: this.subject,
+      html: `${caption ? `<p>${caption}</p>` : ""}<p><a href="${media.media}">${media.media}</a></p>`
+    });
+    return { status: "sent" };
+  }
+  /** Always `"connected"` — SMTP reachability is verified on first send. */
+  async status() {
+    return "connected";
+  }
+};
+
+// src/integrations/broadcast.ts
+async function pool(items, limit, worker) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      results[index] = await worker(items[index], index);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+function broadcastText(provider, recipients, text, options = {}) {
+  const { concurrency = 10, ...sendOptions } = options;
+  return pool(recipients, concurrency, async (to) => {
+    try {
+      const result = await provider.sendText(to, text, sendOptions);
+      return { to, ok: true, result };
+    } catch (error) {
+      return {
+        to,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  });
+}
+var MessagingHub = class {
+  channels = /* @__PURE__ */ new Map();
+  /**
+   * Register a provider under a channel name.
+   *
+   * @param name - The channel name (e.g. `"whatsapp"`, `"sms"`).
+   * @param provider - The provider implementation.
+   * @returns The hub (chainable).
+   */
+  register(name, provider) {
+    this.channels.set(name, provider);
+    return this;
+  }
+  /**
+   * Get a registered provider, throwing when the channel is unknown.
+   *
+   * @param name - The channel name.
+   * @returns The provider.
+   * @throws {Error} When no provider is registered under `name`.
+   */
+  get(name) {
+    const provider = this.channels.get(name);
+    if (!provider) throw new Error(`Unknown messaging channel: ${name}`);
+    return provider;
+  }
+  /** The registered channel names. */
+  channelNames() {
+    return [...this.channels.keys()];
+  }
+  /**
+   * Send text through a named channel.
+   *
+   * @param channel - The channel name.
+   * @param to - The recipient.
+   * @param text - The message body.
+   * @param options - Send options.
+   * @returns The provider result.
+   */
+  send(channel, to, text, options) {
+    return this.get(channel).sendText(to, text, options);
+  }
+  /**
+   * Broadcast text to many recipients on a named channel.
+   *
+   * @param channel - The channel name.
+   * @param recipients - Recipient addresses/handles.
+   * @param text - The message body.
+   * @param options - Broadcast + send options.
+   * @returns One result per recipient.
+   */
+  broadcast(channel, recipients, text, options) {
+    return broadcastText(this.get(channel), recipients, text, options);
+  }
+};
+
 // src/admin/site.ts
 var AdminSite = class {
   /**
@@ -8720,6 +8847,10 @@ var mfaEnrollResponseSchema = z.object({
   otpauthUri: z.string().openapi({ description: "otpauth:// URI to render as QR." })
 }).openapi("MfaEnrollResponse");
 var mfaCodeSchema = z.object({ code: z.string().min(1).openapi({ description: "Authenticator code." }) }).openapi("MfaCode");
+var mfaChallengeSchema = z.object({
+  mfaToken: z.string().min(1).openapi({ description: "Challenge token from login." }),
+  code: z.string().min(1).openapi({ description: "Authenticator code." })
+}).openapi("MfaChallenge");
 var activationSchema = z.object({ token: z.string().min(1).openapi({ description: "Activation token." }) }).openapi("Activation");
 var passwordResetRequestSchema = z.object({ email: z.string().email().openapi({ description: "Account email." }) }).openapi("PasswordResetRequest");
 var passwordResetConfirmSchema = z.object({
@@ -8744,6 +8875,8 @@ var UserAuthService = class {
   passwordMinLength;
   accessTtlSeconds;
   refreshTtlSeconds;
+  mfa;
+  mfaChallengeTtlSeconds;
   /**
    * @param options - Store, password/JWT helpers and token policy.
    */
@@ -8754,6 +8887,8 @@ var UserAuthService = class {
     this.passwordMinLength = options.passwordMinLength ?? 12;
     this.accessTtlSeconds = options.accessTtlSeconds ?? 3600;
     this.refreshTtlSeconds = options.refreshTtlSeconds ?? 60 * 60 * 24 * 14;
+    this.mfa = options.mfa;
+    this.mfaChallengeTtlSeconds = options.mfaChallengeTtlSeconds ?? 300;
   }
   /** Mint a signed access + refresh token pair for `user`. */
   async issueTokens(user) {
@@ -8803,7 +8938,7 @@ var UserAuthService = class {
    * Authenticate a user by email + password.
    *
    * @param data - Validated login payload.
-   * @returns The public user and a fresh token pair.
+   * @returns Full auth, or an {@link MfaChallenge} when MFA is enabled.
    * @throws {UnauthorizedException} On bad credentials or inactive account.
    */
   async login(data) {
@@ -8815,6 +8950,37 @@ var UserAuthService = class {
     if (!user.isActive) {
       throw new UnauthorizedException({ message: "Account is inactive" });
     }
+    if (this.mfa && await this.mfa.isEnabled(user.id)) {
+      const mfaToken = await this.jwt.encode(
+        { sub: user.id, type: "mfa" },
+        { ttlSeconds: this.mfaChallengeTtlSeconds }
+      );
+      return { mfaRequired: true, mfaToken };
+    }
+    return { user: toPublic(user), tokens: await this.issueTokens(user) };
+  }
+  /**
+   * Complete an MFA login challenge: verify the code and issue tokens.
+   *
+   * @param mfaToken - The challenge token from {@link login}.
+   * @param code - The authenticator code.
+   * @returns The public user and a fresh token pair.
+   * @throws {UnauthorizedException} When the challenge/code is invalid, MFA is
+   *   not configured, or the account no longer exists / is inactive.
+   */
+  async verifyMfaChallenge(mfaToken, code) {
+    if (!this.mfa) throw new UnauthorizedException({ message: "MFA not configured" });
+    const claims = await this.jwt.decodeOrNull(mfaToken);
+    if (!claims || claims.type !== "mfa" || typeof claims.sub !== "string") {
+      throw new UnauthorizedException({ message: "Invalid MFA challenge" });
+    }
+    if (!await this.mfa.verify(claims.sub, code)) {
+      throw new UnauthorizedException({ message: "Invalid MFA code" });
+    }
+    const user = await this.store.findById(claims.sub);
+    if (!user || !user.isActive) {
+      throw new UnauthorizedException({ message: "Account is inactive" });
+    }
     return { user: toPublic(user), tokens: await this.issueTokens(user) };
   }
   /**
@@ -8888,6 +9054,15 @@ var MfaService = class {
     const secret = await this.store.getSecret(userId);
     return secret ? this.totp.verify(secret, code) : false;
   }
+  /**
+   * Whether MFA is enabled for a user (used to gate the login challenge).
+   *
+   * @param userId - The user.
+   * @returns `true` when MFA is enabled.
+   */
+  async isEnabled(userId) {
+    return this.store.isEnabled(userId);
+  }
   /**
    * Disable MFA after verifying a code.
    *
@@ -9135,6 +9310,10 @@ function makeAuthRouter(options) {
   }
   if (options.mfa) {
     const mfa = options.mfa;
+    router.post(`${prefix}/mfa/challenge`, async (req, res) => {
+      const { mfaToken, code } = mfaChallengeSchema.parse(req.body);
+      res.json(await service.verifyMfaChallenge(mfaToken, code));
+    });
     const requireUser = (req) => {
       const claims = getAuth(req);
       if (!claims || typeof claims.sub !== "string") {
@@ -9436,6 +9615,6 @@ function runServer(app, options = {}) {
   });
 }
 
-export { ActivationService, AdminSite, 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, MfaService, NotFoundException, PHONE_BR_PATTERN, PasswordResetService, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, RedisCacheManager, RedisSSEBroker, RedisSessionStore, Region, RetryPolicy, SSEBroker, ServerSentEvent, SessionService, TOTPHelper, TaskManager, TelegramProvider, TooManyRequestsException, TwilioSmsProvider, UF, UnauthorizedException, UserAuthService, ValidationException, WebPushDispatcher, WebPushError, WebPushGoneError, WebSocketHub, WhatsAppProvider, activationSchema, 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, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeMetricsRouter, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaCodeSchema, mfaEnrollResponseSchema, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { ActivationService, AdminSite, AppException, AttemptThrottle, BaseController, BaseModel, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, CircuitOpenError, CompositeFeatureFlagBackend, ConflictException, DEFAULT_LOCALE, EmailProvider, EmailUtils, EnvFeatureFlagBackend, EventStream, ExpiredTokenException, FeatureFlags, ForbiddenException, HTTPClient, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, LocalUploadStorage, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, MessagingHub, MetricsUtils, MfaService, NotFoundException, PHONE_BR_PATTERN, PasswordResetService, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, RedisCacheManager, RedisSSEBroker, RedisSessionStore, Region, RetryPolicy, SSEBroker, ServerSentEvent, SessionService, TOTPHelper, TaskManager, TelegramProvider, TooManyRequestsException, TwilioSmsProvider, UF, UnauthorizedException, UserAuthService, ValidationException, WebPushDispatcher, WebPushError, WebPushGoneError, WebSocketHub, WhatsAppProvider, activationSchema, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, broadcastText, 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, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeMetricsRouter, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaChallengeSchema, mfaCodeSchema, mfaEnrollResponseSchema, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map