tempest-express-sdk 0.5.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,113 @@ 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`.
  *
@@ -3105,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.5.0";
+declare const VERSION = "0.6.0";
 
-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 };
+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,113 @@ 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`.
  *
@@ -3105,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.5.0";
+declare const VERSION = "0.6.0";
 
-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 };
+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.js

@@ -1,4 +1,4 @@
-export { VERSION } from './chunk-ZU6W433I.js';
+export { VERSION } from './chunk-3IDD2UXU.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV31, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
 export { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
@@ -8194,6 +8194,190 @@ function makeWhatsAppWebhookRouter(options) {
   return router;
 }
 
+// src/integrations/telegram.ts
+var MEDIA_METHOD = {
+  image: { method: "sendPhoto", field: "photo" },
+  video: { method: "sendVideo", field: "video" },
+  audio: { method: "sendAudio", field: "audio" },
+  document: { method: "sendDocument", field: "document" }
+};
+var TelegramProvider = class {
+  http;
+  pollTimeout;
+  /**
+   * @param options - Bot token and API options.
+   */
+  constructor(options) {
+    const base = `${options.apiBase ?? "https://api.telegram.org"}/bot${options.token}`;
+    this.pollTimeout = options.pollTimeoutSeconds ?? 30;
+    this.http = new HTTPClient({
+      baseUrl: base,
+      defaultHeaders: { "content-type": "application/json" },
+      // Timeout must exceed the long-poll window.
+      timeoutMs: (this.pollTimeout + 10) * 1e3
+    });
+  }
+  /** Call a Bot API method, returning the `result`, throwing on `ok: false`. */
+  async call(method, body) {
+    const res = await this.http.post(`/${method}`, { body: JSON.stringify(body) });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || !data.ok) {
+      throw new Error(`Telegram ${method} failed: ${data.description ?? res.statusText}`);
+    }
+    return data.result;
+  }
+  async sendText(to, text) {
+    const result = await this.call("sendMessage", {
+      chat_id: to,
+      text
+    });
+    return { id: String(result.message_id), status: "sent" };
+  }
+  async sendMedia(to, media) {
+    const { method, field } = MEDIA_METHOD[media.kind];
+    const body = { chat_id: to, [field]: media.media };
+    if (media.caption !== void 0) body.caption = media.caption;
+    const result = await this.call(method, body);
+    return { id: String(result.message_id), status: "sent" };
+  }
+  async status() {
+    try {
+      await this.call("getMe", {});
+      return "connected";
+    } catch {
+      return "disconnected";
+    }
+  }
+  /**
+   * 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.
+   */
+  async onMessage(handler) {
+    let running = true;
+    let offset = 0;
+    const loop = async () => {
+      while (running) {
+        let updates = [];
+        try {
+          updates = await this.call("getUpdates", {
+            offset,
+            timeout: this.pollTimeout
+          });
+        } catch {
+          if (running) await new Promise((r) => setTimeout(r, 1e3));
+          continue;
+        }
+        for (const update2 of updates) {
+          offset = update2.update_id + 1;
+          const message = update2.message;
+          if (!message) continue;
+          await handler({
+            from: String(message.chat.id),
+            messageId: String(message.message_id),
+            ...typeof message.text === "string" ? { text: message.text } : {},
+            mediaType: null,
+            timestamp: new Date(message.date * 1e3).toISOString(),
+            direction: "incoming"
+          });
+        }
+      }
+    };
+    void loop();
+    return async () => {
+      running = false;
+    };
+  }
+};
+var TwilioSmsProvider = class {
+  http;
+  from;
+  messagesPath;
+  accountPath;
+  /**
+   * @param options - Account SID, auth token and default sender.
+   */
+  constructor(options) {
+    this.from = options.from;
+    this.messagesPath = `/2010-04-01/Accounts/${options.accountSid}/Messages.json`;
+    this.accountPath = `/2010-04-01/Accounts/${options.accountSid}.json`;
+    const basic = Buffer.from(`${options.accountSid}:${options.authToken}`).toString(
+      "base64"
+    );
+    this.http = new HTTPClient({
+      baseUrl: options.apiBase ?? "https://api.twilio.com",
+      defaultHeaders: {
+        Authorization: `Basic ${basic}`,
+        "content-type": "application/x-www-form-urlencoded"
+      }
+    });
+  }
+  /** POST a form body to Twilio and parse the JSON, throwing on non-2xx. */
+  async postForm(params) {
+    const res = await this.http.post(this.messagesPath, {
+      body: new URLSearchParams(params).toString()
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(
+        `Twilio send failed (${res.status}): ${data.message ?? res.statusText}`
+      );
+    }
+    return {
+      status: data.status ?? "queued",
+      ...data.sid ? { id: data.sid } : {}
+    };
+  }
+  async sendText(to, text) {
+    return this.postForm({ To: to, From: this.from, Body: text });
+  }
+  async sendMedia(to, media) {
+    return this.postForm({
+      To: to,
+      From: this.from,
+      MediaUrl: media.media,
+      ...media.caption !== void 0 ? { Body: media.caption } : {}
+    });
+  }
+  async status() {
+    const res = await this.http.get(this.accountPath);
+    const data = await res.json().catch(() => ({}));
+    return data.status ?? (res.ok ? "connected" : "disconnected");
+  }
+};
+function validateTwilioSignature(authToken, url, params, signature) {
+  const data = url + Object.keys(params).sort().map((key) => key + params[key]).join("");
+  const expected = createHmac("sha1", authToken).update(data, "utf8").digest("base64");
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signature);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function makeTwilioWebhookRouter(options) {
+  const path = options.path ?? "/sms/inbound";
+  const router = Router();
+  router.post(path, async (req, res) => {
+    const body = req.body ?? {};
+    if (options.authToken) {
+      const url = options.publicUrl ?? `${req.protocol}://${req.get("host")}${req.originalUrl}`;
+      const signature = req.header("x-twilio-signature") ?? "";
+      if (!validateTwilioSignature(options.authToken, url, body, signature)) {
+        throw new UnauthorizedException({ message: "Invalid Twilio signature" });
+      }
+    }
+    await options.onMessage({
+      from: String(body.From ?? ""),
+      messageId: String(body.MessageSid ?? ""),
+      ...body.Body ? { text: body.Body } : {},
+      mediaType: null,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      direction: "incoming"
+    });
+    res.type("text/xml").send("<Response></Response>");
+  });
+  return router;
+}
+
 // src/admin/site.ts
 var AdminSite = class {
   /**
@@ -8809,6 +8993,6 @@ function runServer(app, options = {}) {
   });
 }
 
-export { AdminSite, AppException, AttemptThrottle, BaseController, BaseModel, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, CircuitOpenError, CompositeFeatureFlagBackend, ConflictException, DEFAULT_LOCALE, EmailUtils, EnvFeatureFlagBackend, EventStream, ExpiredTokenException, FeatureFlags, ForbiddenException, HTTPClient, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, LocalUploadStorage, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, MetricsUtils, 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, 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 };
+export { AdminSite, AppException, AttemptThrottle, BaseController, BaseModel, BaseService, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, CircuitOpenError, CompositeFeatureFlagBackend, ConflictException, DEFAULT_LOCALE, EmailUtils, EnvFeatureFlagBackend, EventStream, ExpiredTokenException, FeatureFlags, ForbiddenException, HTTPClient, HTTP_500_MARKER, InvalidTokenException, JSONLogger, JWTUtils, LocalUploadStorage, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, MetricsUtils, NotFoundException, PHONE_BR_PATTERN, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, RedisCacheManager, Region, RetryPolicy, SSEBroker, ServerSentEvent, SessionService, TOTPHelper, TaskManager, TelegramProvider, TooManyRequestsException, TwilioSmsProvider, 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, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map