tempest-express-sdk 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -2244,6 +2244,275 @@ declare class WebPushDispatcher {
     send(subscription: WebPushSubscription, payload: WebPushPayload): Promise<void>;
 }
 
+/**
+ * Messaging integration contracts.
+ *
+ * A channel-agnostic {@link MessagingProvider} so WhatsApp, SMS and future
+ * channels share one shape and are swappable in tests. The first implementation
+ * is {@link WhatsAppProvider} (a client for the `zap-api` service).
+ */
+
+/** Supported media kinds for {@link MessagingProvider.sendMedia}. */
+type MediaKind = "image" | "video" | "audio" | "document";
+/** A media message to send. */
+interface OutboundMedia {
+    /** The media kind (selects the underlying route). */
+    kind: MediaKind;
+    /** A public `http(s)://` URL or a `data:` URI. */
+    media: string;
+    /** Optional caption (image/video). */
+    caption?: string;
+    /** File name with extension (required for `document`). */
+    fileName?: string;
+}
+/** The result of enqueuing an outbound message. */
+interface OutboundResult {
+    /** Provider message id, when returned. */
+    id?: string;
+    /** Provider status string (e.g. `"queued"`, `"sent"`). */
+    status: string;
+    /** Whether the send was de-duplicated by an idempotency key. */
+    deduped?: boolean;
+}
+/** Options accepted by send operations. */
+interface SendOptions {
+    /** Idempotency key to de-duplicate retries on the provider side. */
+    idempotencyKey?: string;
+}
+/** A normalized inbound (or echoed outbound) message. */
+declare const inboundMessageSchema: z.ZodObject<{
+    /** Conversation JID / sender (e.g. `5511999999999@s.whatsapp.net`). */
+    from: z.ZodString;
+    /** Provider message id. */
+    messageId: z.ZodString;
+    /** Text body, when present. */
+    text: z.ZodOptional<z.ZodString>;
+    /** Media kind, or `null` for plain text. */
+    mediaType: z.ZodNullable<z.ZodEnum<["image", "video", "audio", "document", "sticker"]>>;
+    /** ISO-8601 timestamp. */
+    timestamp: z.ZodString;
+    /** Delivery direction. */
+    direction: z.ZodOptional<z.ZodEnum<["incoming", "outgoing"]>>;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    messageId: string;
+    mediaType: "image" | "video" | "audio" | "document" | "sticker" | null;
+    timestamp: string;
+    text?: string | undefined;
+    direction?: "incoming" | "outgoing" | undefined;
+}, {
+    from: string;
+    messageId: string;
+    mediaType: "image" | "video" | "audio" | "document" | "sticker" | null;
+    timestamp: string;
+    text?: string | undefined;
+    direction?: "incoming" | "outgoing" | undefined;
+}>;
+/** A normalized inbound message. */
+type InboundMessage = z.infer<typeof inboundMessageSchema>;
+/** Handler invoked for each inbound message. */
+type InboundHandler = (message: InboundMessage) => Promise<void> | void;
+/** A channel-agnostic messaging provider. */
+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>;
+    /**
+     * Subscribe to inbound messages; resolves to an unsubscribe function.
+     *
+     * @param handler - Invoked for each inbound message.
+     * @param room - Conversation to scope to; `"*"` for all. Default `"*"`.
+     */
+    onMessage(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
+}
+
+/**
+ * WhatsApp provider — a typed client for the `zap-api` service.
+ *
+ * REST for sending (`/message/send-*`, `/message/check-number`) and session
+ * control (`/session/*`); the `/ws` pub/sub for receiving inbound messages in
+ * real time. HTTP goes through the SDK's resilient {@link HTTPClient}; the
+ * WebSocket subscription uses the optional `ws` peer (lazily imported).
+ *
+ * @see https://github.com/mauriciobenjamin700 (zap-api)
+ */
+
+/** Options for {@link WhatsAppProvider}. */
+interface WhatsAppProviderOptions {
+    /** Base URL of the `zap-api` instance, e.g. `https://zap.example.com`. */
+    baseUrl: string;
+    /** Consumer API key (sent as `x-api-key`). */
+    apiKey: string;
+    /** WebSocket URL. Defaults to `baseUrl` with `http(s)`→`ws(s)` + `/ws`. */
+    wsUrl?: string;
+    /** Per-request timeout in ms. Default 15000. */
+    timeoutMs?: number;
+}
+/** A typed client for a running `zap-api` WhatsApp gateway. */
+declare class WhatsAppProvider implements MessagingProvider {
+    private readonly http;
+    private readonly apiKey;
+    private readonly wsUrl;
+    /**
+     * @param options - Base URL, API key and optional WebSocket URL.
+     */
+    constructor(options: WhatsAppProviderOptions);
+    /** POST JSON and parse the response, throwing on a non-2xx status. */
+    private postJson;
+    sendText(to: string, text: string, options?: SendOptions): Promise<OutboundResult>;
+    sendMedia(to: string, media: OutboundMedia, options?: SendOptions): Promise<OutboundResult>;
+    checkNumber(number: string): Promise<boolean>;
+    status(): Promise<string>;
+    /** Start the WhatsApp session (returns the authenticated QR URL, if any). */
+    startSession(): Promise<Record<string, unknown>>;
+    onMessage(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
+}
+
+/**
+ * WhatsApp inbound-webhook receiver.
+ *
+ * `zap-api` POSTs every received message to a configured webhook. This builds
+ * an Express router that (optionally) validates the shared `x-api-key`, parses
+ * the payload into a typed {@link InboundMessage}, and hands it to your handler.
+ */
+
+/** Options for {@link makeWhatsAppWebhookRouter}. */
+interface WhatsAppWebhookOptions {
+    /** Handler invoked for each validated inbound message. */
+    onMessage: InboundHandler;
+    /** Route path. Default `/whatsapp/inbound`. */
+    path?: string;
+    /** Shared secret expected in `x-api-key`. Omit to skip auth (dev only). */
+    apiKey?: string;
+}
+/**
+ * Build the inbound-webhook router.
+ *
+ * @param options - Handler, path and optional shared secret.
+ * @returns An Express router with the webhook endpoint mounted.
+ */
+declare function makeWhatsAppWebhookRouter(options: WhatsAppWebhookOptions): 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`.
  *
@@ -2836,6 +3105,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.3.0";
+declare const VERSION = "0.5.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, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, 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, 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, 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, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeUnhandledExceptionHandler, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+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, 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, makeAdminRouter, 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 };

package/dist/index.d.ts

@@ -2244,6 +2244,275 @@ declare class WebPushDispatcher {
     send(subscription: WebPushSubscription, payload: WebPushPayload): Promise<void>;
 }
 
+/**
+ * Messaging integration contracts.
+ *
+ * A channel-agnostic {@link MessagingProvider} so WhatsApp, SMS and future
+ * channels share one shape and are swappable in tests. The first implementation
+ * is {@link WhatsAppProvider} (a client for the `zap-api` service).
+ */
+
+/** Supported media kinds for {@link MessagingProvider.sendMedia}. */
+type MediaKind = "image" | "video" | "audio" | "document";
+/** A media message to send. */
+interface OutboundMedia {
+    /** The media kind (selects the underlying route). */
+    kind: MediaKind;
+    /** A public `http(s)://` URL or a `data:` URI. */
+    media: string;
+    /** Optional caption (image/video). */
+    caption?: string;
+    /** File name with extension (required for `document`). */
+    fileName?: string;
+}
+/** The result of enqueuing an outbound message. */
+interface OutboundResult {
+    /** Provider message id, when returned. */
+    id?: string;
+    /** Provider status string (e.g. `"queued"`, `"sent"`). */
+    status: string;
+    /** Whether the send was de-duplicated by an idempotency key. */
+    deduped?: boolean;
+}
+/** Options accepted by send operations. */
+interface SendOptions {
+    /** Idempotency key to de-duplicate retries on the provider side. */
+    idempotencyKey?: string;
+}
+/** A normalized inbound (or echoed outbound) message. */
+declare const inboundMessageSchema: z.ZodObject<{
+    /** Conversation JID / sender (e.g. `5511999999999@s.whatsapp.net`). */
+    from: z.ZodString;
+    /** Provider message id. */
+    messageId: z.ZodString;
+    /** Text body, when present. */
+    text: z.ZodOptional<z.ZodString>;
+    /** Media kind, or `null` for plain text. */
+    mediaType: z.ZodNullable<z.ZodEnum<["image", "video", "audio", "document", "sticker"]>>;
+    /** ISO-8601 timestamp. */
+    timestamp: z.ZodString;
+    /** Delivery direction. */
+    direction: z.ZodOptional<z.ZodEnum<["incoming", "outgoing"]>>;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    messageId: string;
+    mediaType: "image" | "video" | "audio" | "document" | "sticker" | null;
+    timestamp: string;
+    text?: string | undefined;
+    direction?: "incoming" | "outgoing" | undefined;
+}, {
+    from: string;
+    messageId: string;
+    mediaType: "image" | "video" | "audio" | "document" | "sticker" | null;
+    timestamp: string;
+    text?: string | undefined;
+    direction?: "incoming" | "outgoing" | undefined;
+}>;
+/** A normalized inbound message. */
+type InboundMessage = z.infer<typeof inboundMessageSchema>;
+/** Handler invoked for each inbound message. */
+type InboundHandler = (message: InboundMessage) => Promise<void> | void;
+/** A channel-agnostic messaging provider. */
+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>;
+    /**
+     * Subscribe to inbound messages; resolves to an unsubscribe function.
+     *
+     * @param handler - Invoked for each inbound message.
+     * @param room - Conversation to scope to; `"*"` for all. Default `"*"`.
+     */
+    onMessage(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
+}
+
+/**
+ * WhatsApp provider — a typed client for the `zap-api` service.
+ *
+ * REST for sending (`/message/send-*`, `/message/check-number`) and session
+ * control (`/session/*`); the `/ws` pub/sub for receiving inbound messages in
+ * real time. HTTP goes through the SDK's resilient {@link HTTPClient}; the
+ * WebSocket subscription uses the optional `ws` peer (lazily imported).
+ *
+ * @see https://github.com/mauriciobenjamin700 (zap-api)
+ */
+
+/** Options for {@link WhatsAppProvider}. */
+interface WhatsAppProviderOptions {
+    /** Base URL of the `zap-api` instance, e.g. `https://zap.example.com`. */
+    baseUrl: string;
+    /** Consumer API key (sent as `x-api-key`). */
+    apiKey: string;
+    /** WebSocket URL. Defaults to `baseUrl` with `http(s)`→`ws(s)` + `/ws`. */
+    wsUrl?: string;
+    /** Per-request timeout in ms. Default 15000. */
+    timeoutMs?: number;
+}
+/** A typed client for a running `zap-api` WhatsApp gateway. */
+declare class WhatsAppProvider implements MessagingProvider {
+    private readonly http;
+    private readonly apiKey;
+    private readonly wsUrl;
+    /**
+     * @param options - Base URL, API key and optional WebSocket URL.
+     */
+    constructor(options: WhatsAppProviderOptions);
+    /** POST JSON and parse the response, throwing on a non-2xx status. */
+    private postJson;
+    sendText(to: string, text: string, options?: SendOptions): Promise<OutboundResult>;
+    sendMedia(to: string, media: OutboundMedia, options?: SendOptions): Promise<OutboundResult>;
+    checkNumber(number: string): Promise<boolean>;
+    status(): Promise<string>;
+    /** Start the WhatsApp session (returns the authenticated QR URL, if any). */
+    startSession(): Promise<Record<string, unknown>>;
+    onMessage(handler: InboundHandler, room?: string): Promise<() => Promise<void>>;
+}
+
+/**
+ * WhatsApp inbound-webhook receiver.
+ *
+ * `zap-api` POSTs every received message to a configured webhook. This builds
+ * an Express router that (optionally) validates the shared `x-api-key`, parses
+ * the payload into a typed {@link InboundMessage}, and hands it to your handler.
+ */
+
+/** Options for {@link makeWhatsAppWebhookRouter}. */
+interface WhatsAppWebhookOptions {
+    /** Handler invoked for each validated inbound message. */
+    onMessage: InboundHandler;
+    /** Route path. Default `/whatsapp/inbound`. */
+    path?: string;
+    /** Shared secret expected in `x-api-key`. Omit to skip auth (dev only). */
+    apiKey?: string;
+}
+/**
+ * Build the inbound-webhook router.
+ *
+ * @param options - Handler, path and optional shared secret.
+ * @returns An Express router with the webhook endpoint mounted.
+ */
+declare function makeWhatsAppWebhookRouter(options: WhatsAppWebhookOptions): 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`.
  *
@@ -2836,6 +3105,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.3.0";
+declare const VERSION = "0.5.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, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, 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, 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, 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, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeUnhandledExceptionHandler, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+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, 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, makeAdminRouter, 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 };