tempest-express-sdk 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -2244,6 +2244,160 @@ 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;
+
 /**
  * Auth DTOs (Zod), mirroring `auth.schemas`.
  *
@@ -2836,6 +2990,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.4.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 { 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 };

package/dist/index.d.ts

@@ -2244,6 +2244,160 @@ 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;
+
 /**
  * Auth DTOs (Zod), mirroring `auth.schemas`.
  *
@@ -2836,6 +2990,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.4.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 { 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { VERSION } from './chunk-6ZKN2ELQ.js';
+export { VERSION } from './chunk-US2RDLUY.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV31, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
 export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
@@ -8026,6 +8026,174 @@ var WebPushDispatcher = class {
   }
 };
 
+// src/integrations/provider.ts
+var inboundMessageSchema = z.object({
+  /** Conversation JID / sender (e.g. `5511999999999@s.whatsapp.net`). */
+  from: z.string().openapi({ description: "Conversation JID / sender." }),
+  /** Provider message id. */
+  messageId: z.string().openapi({ description: "Provider message id." }),
+  /** Text body, when present. */
+  text: z.string().optional().openapi({ description: "Text body." }),
+  /** Media kind, or `null` for plain text. */
+  mediaType: z.enum(["image", "video", "audio", "document", "sticker"]).nullable().openapi({ description: "Media kind, or null for text." }),
+  /** ISO-8601 timestamp. */
+  timestamp: z.string().openapi({ description: "ISO-8601 timestamp." }),
+  /** Delivery direction. */
+  direction: z.enum(["incoming", "outgoing"]).optional()
+}).openapi("InboundMessage");
+
+// src/integrations/whatsapp.ts
+var MEDIA_ROUTE = {
+  image: "send-image",
+  video: "send-video",
+  audio: "send-audio",
+  document: "send-document"
+};
+function deriveWsUrl(baseUrl) {
+  const trimmed = baseUrl.replace(/\/$/, "");
+  return `${trimmed.replace(/^http/, "ws")}/ws`;
+}
+var WhatsAppProvider = class {
+  http;
+  apiKey;
+  wsUrl;
+  /**
+   * @param options - Base URL, API key and optional WebSocket URL.
+   */
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.wsUrl = options.wsUrl ?? deriveWsUrl(options.baseUrl);
+    this.http = new HTTPClient({
+      baseUrl: options.baseUrl.replace(/\/$/, ""),
+      defaultHeaders: { "x-api-key": options.apiKey, "content-type": "application/json" },
+      timeoutMs: options.timeoutMs ?? 15e3
+    });
+  }
+  /** POST JSON and parse the response, throwing on a non-2xx status. */
+  async postJson(path, body, options) {
+    const headers = options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : void 0;
+    const res = await this.http.post(path, {
+      body: JSON.stringify(body),
+      ...headers ? { headers } : {}
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(
+        `zap-api ${path} failed (${res.status}): ${String(data.error ?? res.statusText)}`
+      );
+    }
+    return data;
+  }
+  async sendText(to, text, options) {
+    const data = await this.postJson("/message/send-text", { to, text }, options);
+    return {
+      status: String(data.status ?? "queued"),
+      ...typeof data.id === "string" ? { id: data.id } : {},
+      ...typeof data.deduped === "boolean" ? { deduped: data.deduped } : {}
+    };
+  }
+  async sendMedia(to, media, options) {
+    const body = { to, media: media.media };
+    if (media.caption !== void 0) body.caption = media.caption;
+    if (media.fileName !== void 0) body.fileName = media.fileName;
+    const data = await this.postJson(
+      `/message/${MEDIA_ROUTE[media.kind]}`,
+      body,
+      options
+    );
+    return {
+      status: String(data.status ?? "queued"),
+      ...typeof data.id === "string" ? { id: data.id } : {},
+      ...typeof data.deduped === "boolean" ? { deduped: data.deduped } : {}
+    };
+  }
+  async checkNumber(number) {
+    const res = await this.http.get(
+      `/message/check-number/${encodeURIComponent(number)}`
+    );
+    const data = await res.json().catch(() => ({}));
+    return data.exists === true;
+  }
+  async status() {
+    const res = await this.http.get("/session/status");
+    const raw = await res.text();
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed.status ?? raw.trim();
+    } catch {
+      return raw.trim();
+    }
+  }
+  /** Start the WhatsApp session (returns the authenticated QR URL, if any). */
+  async startSession() {
+    return this.postJson("/session/start", {});
+  }
+  async onMessage(handler, room = "*") {
+    let ws;
+    try {
+      ws = await import('ws');
+    } catch (cause) {
+      throw new Error(
+        "WhatsAppProvider.onMessage requires the 'ws' peer dependency. Install with `npm i ws`.",
+        { cause }
+      );
+    }
+    const socket = new ws.WebSocket(this.wsUrl, {
+      headers: { "x-api-key": this.apiKey }
+    });
+    socket.on("open", () => {
+      socket.send(JSON.stringify({ action: "subscribe", room }));
+    });
+    socket.on("message", (raw) => {
+      let frame;
+      try {
+        frame = JSON.parse(String(raw));
+      } catch {
+        return;
+      }
+      if (frame.type === "message" && frame.payload) {
+        const p = frame.payload;
+        void handler({
+          from: String(p.remoteJid ?? ""),
+          messageId: String(p.messageId ?? ""),
+          ...typeof p.text === "string" ? { text: p.text } : {},
+          mediaType: p.mediaType ?? null,
+          timestamp: String(p.timestamp ?? ""),
+          ...p.direction === "incoming" || p.direction === "outgoing" ? { direction: p.direction } : {}
+        });
+      }
+    });
+    return async () => {
+      try {
+        socket.send(JSON.stringify({ action: "unsubscribe", room }));
+      } catch {
+      }
+      socket.close();
+    };
+  }
+};
+function safeEqual(a, b) {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  return bufA.length === bufB.length && timingSafeEqual(bufA, bufB);
+}
+function makeWhatsAppWebhookRouter(options) {
+  const path = options.path ?? "/whatsapp/inbound";
+  const router = Router();
+  router.post(path, async (req, res) => {
+    if (options.apiKey) {
+      const provided = req.header("x-api-key") ?? "";
+      if (!safeEqual(provided, options.apiKey)) {
+        throw new UnauthorizedException({ message: "Invalid webhook key" });
+      }
+    }
+    const message = inboundMessageSchema.parse(req.body);
+    await options.onMessage(message);
+    res.status(200).json({ ok: true });
+  });
+  return router;
+}
+
 // src/auth/schemas.ts
 var signupSchema = z.object({
   email: z.string().email().openapi({ description: "Login identifier (email)." }),
@@ -8537,6 +8705,6 @@ function runServer(app, options = {}) {
   });
 }
 
-export { AppException, AttemptThrottle, BaseController, BaseModel, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, CircuitOpenError, CompositeFeatureFlagBackend, ConflictException, DEFAULT_LOCALE, EmailUtils, EnvFeatureFlagBackend, EventStream, ExpiredTokenException, FeatureFlags, ForbiddenException, HTTPClient, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, LocalUploadStorage, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, MetricsUtils, NotFoundException, PHONE_BR_PATTERN, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, RedisCacheManager, Region, RetryPolicy, SSEBroker, ServerSentEvent, SessionService, TOTPHelper, TaskManager, TooManyRequestsException, UF, UnauthorizedException, UserAuthService, ValidationException, WebPushDispatcher, WebPushError, WebPushGoneError, WebSocketHub, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached3 as cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeUnhandledExceptionHandler, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { AppException, AttemptThrottle, BaseController, BaseModel, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, CircuitOpenError, CompositeFeatureFlagBackend, ConflictException, DEFAULT_LOCALE, EmailUtils, EnvFeatureFlagBackend, EventStream, ExpiredTokenException, FeatureFlags, ForbiddenException, HTTPClient, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, LocalUploadStorage, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, MetricsUtils, NotFoundException, PHONE_BR_PATTERN, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, RedisCacheManager, Region, RetryPolicy, SSEBroker, ServerSentEvent, SessionService, TOTPHelper, TaskManager, TooManyRequestsException, UF, UnauthorizedException, UserAuthService, ValidationException, WebPushDispatcher, WebPushError, WebPushGoneError, WebSocketHub, WhatsAppProvider, 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, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map