tempest-express-sdk 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -2312,23 +2312,30 @@ declare const inboundMessageSchema: z.ZodObject<{
 type InboundMessage = z.infer<typeof inboundMessageSchema>;
 /** Handler invoked for each inbound message. */
 type InboundHandler = (message: InboundMessage) => Promise<void> | void;
-/** A channel-agnostic messaging provider. */
+/**
+ * A channel-agnostic messaging provider. `sendText`/`sendMedia`/`status` are
+ * universal; `checkNumber` and `onMessage` are optional because not every
+ * channel supports them (e.g. SMS has no persistent subscription — its inbound
+ * arrives via a webhook receiver instead).
+ */
 interface MessagingProvider {
     /** Send a text message. */
     sendText(to: string, text: string, options?: SendOptions): Promise<OutboundResult>;
     /** Send a media message. */
     sendMedia(to: string, media: OutboundMedia, options?: SendOptions): Promise<OutboundResult>;
-    /** Whether a number exists on the channel. */
-    checkNumber(number: string): Promise<boolean>;
     /** The current session/connection status. */
     status(): Promise<string>;
+    /** Whether a number/handle exists on the channel (when supported). */
+    checkNumber?(number: string): Promise<boolean>;
     /**
      * Subscribe to inbound messages; resolves to an unsubscribe function.
+     * Present only on channels with a live subscription (WhatsApp `/ws`,
+     * Telegram long-polling).
      *
      * @param handler - Invoked for each inbound message.
      * @param room - Conversation to scope to; `"*"` for all. Default `"*"`.
      */
-    onMessage(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
+    onMessage?(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
 }
 
 /**
@@ -2398,6 +2405,228 @@ interface WhatsAppWebhookOptions {
  */
 declare function makeWhatsAppWebhookRouter(options: WhatsAppWebhookOptions): Router;
 
+/**
+ * Telegram provider — a client for the Telegram Bot API.
+ *
+ * Implements {@link MessagingProvider} over the built-in {@link HTTPClient}
+ * (no external SDK). Outbound via `sendMessage`/`sendPhoto`/…; inbound via
+ * `getUpdates` long-polling exposed through {@link TelegramProvider.onMessage}.
+ */
+
+/** Options for {@link TelegramProvider}. */
+interface TelegramProviderOptions {
+    /** Bot token from @BotFather. */
+    token: string;
+    /** API base. Default `https://api.telegram.org`. */
+    apiBase?: string;
+    /** Long-poll timeout in seconds for `getUpdates`. Default 30. */
+    pollTimeoutSeconds?: number;
+}
+/** A typed Telegram Bot API client. */
+declare class TelegramProvider implements MessagingProvider {
+    private readonly http;
+    private readonly pollTimeout;
+    /**
+     * @param options - Bot token and API options.
+     */
+    constructor(options: TelegramProviderOptions);
+    /** Call a Bot API method, returning the `result`, throwing on `ok: false`. */
+    private call;
+    sendText(to: string, text: string): Promise<OutboundResult>;
+    sendMedia(to: string, media: OutboundMedia): Promise<OutboundResult>;
+    status(): Promise<string>;
+    /**
+     * Subscribe to inbound messages via `getUpdates` long-polling.
+     *
+     * @param handler - Invoked for each inbound text message.
+     * @returns A stop function that ends the polling loop.
+     */
+    onMessage(handler: InboundHandler): Promise<() => Promise<void>>;
+}
+
+/**
+ * SMS provider — a Twilio client + inbound-webhook receiver.
+ *
+ * Implements {@link MessagingProvider} over the built-in {@link HTTPClient}
+ * (no `twilio` SDK). SMS has no persistent subscription, so `onMessage` is
+ * absent — inbound arrives via {@link makeTwilioWebhookRouter}, which validates
+ * the `X-Twilio-Signature` HMAC.
+ */
+
+/** Options for {@link TwilioSmsProvider}. */
+interface TwilioSmsProviderOptions {
+    /** Twilio Account SID. */
+    accountSid: string;
+    /** Twilio Auth Token. */
+    authToken: string;
+    /** Default `From` number (E.164), e.g. `+15551234567`. */
+    from: string;
+    /** API base. Default `https://api.twilio.com`. */
+    apiBase?: string;
+}
+/** A Twilio SMS client. */
+declare class TwilioSmsProvider implements MessagingProvider {
+    private readonly http;
+    private readonly from;
+    private readonly messagesPath;
+    private readonly accountPath;
+    /**
+     * @param options - Account SID, auth token and default sender.
+     */
+    constructor(options: TwilioSmsProviderOptions);
+    /** POST a form body to Twilio and parse the JSON, throwing on non-2xx. */
+    private postForm;
+    sendText(to: string, text: string): Promise<OutboundResult>;
+    sendMedia(to: string, media: OutboundMedia): Promise<OutboundResult>;
+    status(): Promise<string>;
+}
+/**
+ * Validate a Twilio request signature (`X-Twilio-Signature`).
+ *
+ * @param authToken - The Twilio auth token.
+ * @param url - The full public URL Twilio posted to (scheme + host + path).
+ * @param params - The POST form parameters.
+ * @param signature - The `X-Twilio-Signature` header value.
+ * @returns `true` when the signature matches.
+ */
+declare function validateTwilioSignature(authToken: string, url: string, params: Record<string, string>, signature: string): boolean;
+/** Options for {@link makeTwilioWebhookRouter}. */
+interface TwilioWebhookOptions {
+    /** Handler invoked for each inbound SMS. */
+    onMessage: InboundHandler;
+    /** Route path. Default `/sms/inbound`. */
+    path?: string;
+    /** Auth token; when set, `X-Twilio-Signature` is validated. */
+    authToken?: string;
+    /** Public URL Twilio posts to (needed for signature validation behind a proxy). */
+    publicUrl?: string;
+}
+/**
+ * Build the Twilio inbound-SMS webhook router.
+ *
+ * Twilio posts `application/x-www-form-urlencoded` (`From`, `Body`,
+ * `MessageSid`, …). Mount after `express.urlencoded()` (included by `createApp`).
+ *
+ * @param options - Handler, path and signature-validation settings.
+ * @returns An Express router with the webhook endpoint mounted.
+ */
+declare function makeTwilioWebhookRouter(options: TwilioWebhookOptions): Router;
+
+/**
+ * Admin site + resource registry, mirroring `admin.site` / `admin.config`.
+ *
+ * The FastAPI SDK ships a server-rendered (jinja) admin UI. Here the admin is a
+ * typed **JSON API**: register one {@link AdminResource} per managed entity and
+ * {@link makeAdminRouter} exposes auto-derived CRUD + introspection endpoints a
+ * frontend (React, etc.) renders. Resources are callback-based, so they wire to
+ * a `BaseService` — or any store — in a few lines and stay ORM-agnostic.
+ */
+
+/** A field descriptor a frontend uses to render list columns / form inputs. */
+interface AdminField {
+    /** Field name (property key). */
+    name: string;
+    /** Loose type hint for rendering (`string`, `number`, `boolean`, `date`, …). */
+    type?: string;
+    /** Whether the field is required on create. */
+    required?: boolean;
+    /** Whether the field is read-only (shown, never submitted). */
+    readOnly?: boolean;
+}
+/** A paginated list result returned by {@link AdminResource.list}. */
+interface AdminListResult<T = unknown> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    pages: number;
+}
+/** Query parameters passed to {@link AdminResource.list}. */
+interface AdminListQuery {
+    page: number;
+    pageSize: number;
+    /** Remaining query-string entries (domain filters). */
+    filters: Record<string, string>;
+}
+/**
+ * A managed resource. Only `name`, `fields` and `list`/`get` are required;
+ * omit a write callback to make that operation unavailable (405).
+ */
+interface AdminResource<T = unknown> {
+    /** URL-safe resource slug (e.g. `users`). */
+    name: string;
+    /** Field descriptors for list/detail/form rendering. */
+    fields: AdminField[];
+    /** Return a page of records. */
+    list(query: AdminListQuery): Promise<AdminListResult<T>>;
+    /** Return one record by id, or `null` when absent. */
+    get(id: string): Promise<T | null>;
+    /** Create a record from validated input. */
+    create?(data: unknown): Promise<T>;
+    /** Update a record by id from validated input. */
+    update?(id: string, data: unknown): Promise<T>;
+    /** Delete a record by id. */
+    remove?(id: string): Promise<void>;
+    /** Zod schema validating the create body. */
+    createSchema?: z.ZodTypeAny;
+    /** Zod schema validating the update body. */
+    updateSchema?: z.ZodTypeAny;
+}
+/** A registry of admin resources. */
+declare class AdminSite {
+    readonly brand: string;
+    private readonly resources;
+    /**
+     * @param brand - Display name surfaced under `GET {prefix}/`.
+     */
+    constructor(brand?: string);
+    /**
+     * Register a resource.
+     *
+     * @param resource - The resource config.
+     * @returns The same resource (for chaining).
+     */
+    register<T>(resource: AdminResource<T>): AdminResource<T>;
+    /** Look up a resource by slug, or `null`. */
+    get(name: string): AdminResource | null;
+    /** Every registered resource. */
+    list(): AdminResource[];
+}
+
+/**
+ * Admin JSON router, mirroring `admin.router.make_admin_router`.
+ *
+ * Exposes auto-derived CRUD + introspection over an {@link AdminSite}:
+ *
+ * ```text
+ * GET    {prefix}/                    site brand + resource list
+ * GET    {prefix}/:resource/_meta     resource field descriptors
+ * GET    {prefix}/:resource           paginated list
+ * GET    {prefix}/:resource/:id       detail (404 when absent)
+ * POST   {prefix}/:resource           create (405 if unsupported)
+ * PATCH  {prefix}/:resource/:id        update (405 if unsupported)
+ * DELETE {prefix}/:resource/:id        delete (405 if unsupported)
+ * ```
+ *
+ * Pass a `guard` middleware (e.g. JWT + `requireRoles("admin")`) to protect it.
+ */
+
+/** Options for {@link makeAdminRouter}. */
+interface AdminRouterOptions {
+    /** Route prefix. Default `/admin`. */
+    prefix?: string;
+    /** Guard middleware applied to every admin route (auth). */
+    guard?: RequestHandler;
+}
+/**
+ * Build the admin router.
+ *
+ * @param site - The registered {@link AdminSite}.
+ * @param options - Prefix and guard middleware.
+ * @returns An Express router with the admin endpoints mounted.
+ */
+declare function makeAdminRouter(site: AdminSite, options?: AdminRouterOptions): Router;
+
 /**
  * Auth DTOs (Zod), mirroring `auth.schemas`.
  *
@@ -2990,6 +3219,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.4.0";
+declare const VERSION = "0.6.0";
 
-export { 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 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, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, 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, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, 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, 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, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { 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 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, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, 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, 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, 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, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };

package/dist/index.d.ts

@@ -2312,23 +2312,30 @@ declare const inboundMessageSchema: z.ZodObject<{
 type InboundMessage = z.infer<typeof inboundMessageSchema>;
 /** Handler invoked for each inbound message. */
 type InboundHandler = (message: InboundMessage) => Promise<void> | void;
-/** A channel-agnostic messaging provider. */
+/**
+ * A channel-agnostic messaging provider. `sendText`/`sendMedia`/`status` are
+ * universal; `checkNumber` and `onMessage` are optional because not every
+ * channel supports them (e.g. SMS has no persistent subscription — its inbound
+ * arrives via a webhook receiver instead).
+ */
 interface MessagingProvider {
     /** Send a text message. */
     sendText(to: string, text: string, options?: SendOptions): Promise<OutboundResult>;
     /** Send a media message. */
     sendMedia(to: string, media: OutboundMedia, options?: SendOptions): Promise<OutboundResult>;
-    /** Whether a number exists on the channel. */
-    checkNumber(number: string): Promise<boolean>;
     /** The current session/connection status. */
     status(): Promise<string>;
+    /** Whether a number/handle exists on the channel (when supported). */
+    checkNumber?(number: string): Promise<boolean>;
     /**
      * Subscribe to inbound messages; resolves to an unsubscribe function.
+     * Present only on channels with a live subscription (WhatsApp `/ws`,
+     * Telegram long-polling).
      *
      * @param handler - Invoked for each inbound message.
      * @param room - Conversation to scope to; `"*"` for all. Default `"*"`.
      */
-    onMessage(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
+    onMessage?(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
 }
 
 /**
@@ -2398,6 +2405,228 @@ interface WhatsAppWebhookOptions {
  */
 declare function makeWhatsAppWebhookRouter(options: WhatsAppWebhookOptions): Router;
 
+/**
+ * Telegram provider — a client for the Telegram Bot API.
+ *
+ * Implements {@link MessagingProvider} over the built-in {@link HTTPClient}
+ * (no external SDK). Outbound via `sendMessage`/`sendPhoto`/…; inbound via
+ * `getUpdates` long-polling exposed through {@link TelegramProvider.onMessage}.
+ */
+
+/** Options for {@link TelegramProvider}. */
+interface TelegramProviderOptions {
+    /** Bot token from @BotFather. */
+    token: string;
+    /** API base. Default `https://api.telegram.org`. */
+    apiBase?: string;
+    /** Long-poll timeout in seconds for `getUpdates`. Default 30. */
+    pollTimeoutSeconds?: number;
+}
+/** A typed Telegram Bot API client. */
+declare class TelegramProvider implements MessagingProvider {
+    private readonly http;
+    private readonly pollTimeout;
+    /**
+     * @param options - Bot token and API options.
+     */
+    constructor(options: TelegramProviderOptions);
+    /** Call a Bot API method, returning the `result`, throwing on `ok: false`. */
+    private call;
+    sendText(to: string, text: string): Promise<OutboundResult>;
+    sendMedia(to: string, media: OutboundMedia): Promise<OutboundResult>;
+    status(): Promise<string>;
+    /**
+     * Subscribe to inbound messages via `getUpdates` long-polling.
+     *
+     * @param handler - Invoked for each inbound text message.
+     * @returns A stop function that ends the polling loop.
+     */
+    onMessage(handler: InboundHandler): Promise<() => Promise<void>>;
+}
+
+/**
+ * SMS provider — a Twilio client + inbound-webhook receiver.
+ *
+ * Implements {@link MessagingProvider} over the built-in {@link HTTPClient}
+ * (no `twilio` SDK). SMS has no persistent subscription, so `onMessage` is
+ * absent — inbound arrives via {@link makeTwilioWebhookRouter}, which validates
+ * the `X-Twilio-Signature` HMAC.
+ */
+
+/** Options for {@link TwilioSmsProvider}. */
+interface TwilioSmsProviderOptions {
+    /** Twilio Account SID. */
+    accountSid: string;
+    /** Twilio Auth Token. */
+    authToken: string;
+    /** Default `From` number (E.164), e.g. `+15551234567`. */
+    from: string;
+    /** API base. Default `https://api.twilio.com`. */
+    apiBase?: string;
+}
+/** A Twilio SMS client. */
+declare class TwilioSmsProvider implements MessagingProvider {
+    private readonly http;
+    private readonly from;
+    private readonly messagesPath;
+    private readonly accountPath;
+    /**
+     * @param options - Account SID, auth token and default sender.
+     */
+    constructor(options: TwilioSmsProviderOptions);
+    /** POST a form body to Twilio and parse the JSON, throwing on non-2xx. */
+    private postForm;
+    sendText(to: string, text: string): Promise<OutboundResult>;
+    sendMedia(to: string, media: OutboundMedia): Promise<OutboundResult>;
+    status(): Promise<string>;
+}
+/**
+ * Validate a Twilio request signature (`X-Twilio-Signature`).
+ *
+ * @param authToken - The Twilio auth token.
+ * @param url - The full public URL Twilio posted to (scheme + host + path).
+ * @param params - The POST form parameters.
+ * @param signature - The `X-Twilio-Signature` header value.
+ * @returns `true` when the signature matches.
+ */
+declare function validateTwilioSignature(authToken: string, url: string, params: Record<string, string>, signature: string): boolean;
+/** Options for {@link makeTwilioWebhookRouter}. */
+interface TwilioWebhookOptions {
+    /** Handler invoked for each inbound SMS. */
+    onMessage: InboundHandler;
+    /** Route path. Default `/sms/inbound`. */
+    path?: string;
+    /** Auth token; when set, `X-Twilio-Signature` is validated. */
+    authToken?: string;
+    /** Public URL Twilio posts to (needed for signature validation behind a proxy). */
+    publicUrl?: string;
+}
+/**
+ * Build the Twilio inbound-SMS webhook router.
+ *
+ * Twilio posts `application/x-www-form-urlencoded` (`From`, `Body`,
+ * `MessageSid`, …). Mount after `express.urlencoded()` (included by `createApp`).
+ *
+ * @param options - Handler, path and signature-validation settings.
+ * @returns An Express router with the webhook endpoint mounted.
+ */
+declare function makeTwilioWebhookRouter(options: TwilioWebhookOptions): Router;
+
+/**
+ * Admin site + resource registry, mirroring `admin.site` / `admin.config`.
+ *
+ * The FastAPI SDK ships a server-rendered (jinja) admin UI. Here the admin is a
+ * typed **JSON API**: register one {@link AdminResource} per managed entity and
+ * {@link makeAdminRouter} exposes auto-derived CRUD + introspection endpoints a
+ * frontend (React, etc.) renders. Resources are callback-based, so they wire to
+ * a `BaseService` — or any store — in a few lines and stay ORM-agnostic.
+ */
+
+/** A field descriptor a frontend uses to render list columns / form inputs. */
+interface AdminField {
+    /** Field name (property key). */
+    name: string;
+    /** Loose type hint for rendering (`string`, `number`, `boolean`, `date`, …). */
+    type?: string;
+    /** Whether the field is required on create. */
+    required?: boolean;
+    /** Whether the field is read-only (shown, never submitted). */
+    readOnly?: boolean;
+}
+/** A paginated list result returned by {@link AdminResource.list}. */
+interface AdminListResult<T = unknown> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    pages: number;
+}
+/** Query parameters passed to {@link AdminResource.list}. */
+interface AdminListQuery {
+    page: number;
+    pageSize: number;
+    /** Remaining query-string entries (domain filters). */
+    filters: Record<string, string>;
+}
+/**
+ * A managed resource. Only `name`, `fields` and `list`/`get` are required;
+ * omit a write callback to make that operation unavailable (405).
+ */
+interface AdminResource<T = unknown> {
+    /** URL-safe resource slug (e.g. `users`). */
+    name: string;
+    /** Field descriptors for list/detail/form rendering. */
+    fields: AdminField[];
+    /** Return a page of records. */
+    list(query: AdminListQuery): Promise<AdminListResult<T>>;
+    /** Return one record by id, or `null` when absent. */
+    get(id: string): Promise<T | null>;
+    /** Create a record from validated input. */
+    create?(data: unknown): Promise<T>;
+    /** Update a record by id from validated input. */
+    update?(id: string, data: unknown): Promise<T>;
+    /** Delete a record by id. */
+    remove?(id: string): Promise<void>;
+    /** Zod schema validating the create body. */
+    createSchema?: z.ZodTypeAny;
+    /** Zod schema validating the update body. */
+    updateSchema?: z.ZodTypeAny;
+}
+/** A registry of admin resources. */
+declare class AdminSite {
+    readonly brand: string;
+    private readonly resources;
+    /**
+     * @param brand - Display name surfaced under `GET {prefix}/`.
+     */
+    constructor(brand?: string);
+    /**
+     * Register a resource.
+     *
+     * @param resource - The resource config.
+     * @returns The same resource (for chaining).
+     */
+    register<T>(resource: AdminResource<T>): AdminResource<T>;
+    /** Look up a resource by slug, or `null`. */
+    get(name: string): AdminResource | null;
+    /** Every registered resource. */
+    list(): AdminResource[];
+}
+
+/**
+ * Admin JSON router, mirroring `admin.router.make_admin_router`.
+ *
+ * Exposes auto-derived CRUD + introspection over an {@link AdminSite}:
+ *
+ * ```text
+ * GET    {prefix}/                    site brand + resource list
+ * GET    {prefix}/:resource/_meta     resource field descriptors
+ * GET    {prefix}/:resource           paginated list
+ * GET    {prefix}/:resource/:id       detail (404 when absent)
+ * POST   {prefix}/:resource           create (405 if unsupported)
+ * PATCH  {prefix}/:resource/:id        update (405 if unsupported)
+ * DELETE {prefix}/:resource/:id        delete (405 if unsupported)
+ * ```
+ *
+ * Pass a `guard` middleware (e.g. JWT + `requireRoles("admin")`) to protect it.
+ */
+
+/** Options for {@link makeAdminRouter}. */
+interface AdminRouterOptions {
+    /** Route prefix. Default `/admin`. */
+    prefix?: string;
+    /** Guard middleware applied to every admin route (auth). */
+    guard?: RequestHandler;
+}
+/**
+ * Build the admin router.
+ *
+ * @param site - The registered {@link AdminSite}.
+ * @param options - Prefix and guard middleware.
+ * @returns An Express router with the admin endpoints mounted.
+ */
+declare function makeAdminRouter(site: AdminSite, options?: AdminRouterOptions): Router;
+
 /**
  * Auth DTOs (Zod), mirroring `auth.schemas`.
  *
@@ -2990,6 +3219,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.4.0";
+declare const VERSION = "0.6.0";
 
-export { 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 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, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, 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, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, 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, 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, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { 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 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, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, 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, 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, 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, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };