@pocketping/sdk-node 1.6.0 → 1.7.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { IncomingMessage, ServerResponse } from 'http';
+import { IncomingMessage, ServerResponse } from 'node:http';
 
 /**
  * Bridge message IDs for edit/delete sync.
@@ -31,6 +31,156 @@ interface Storage {
     cleanupOldSessions?(olderThan: Date): Promise<number>;
 }
 
+declare class PocketPing {
+    private storage;
+    private bridges;
+    private config;
+    private wss;
+    private sessionSockets;
+    private operatorOnline;
+    private eventHandlers;
+    constructor(config?: PocketPingConfig);
+    private initStorage;
+    middleware(): (req: IncomingMessage & {
+        body?: unknown;
+        query?: Record<string, string>;
+    }, res: ServerResponse, next?: () => void) => void;
+    private parseBody;
+    attachWebSocket(server: any): void;
+    private handleWebSocketMessage;
+    private handleCustomEvent;
+    private broadcastToSession;
+    handleConnect(request: ConnectRequest): Promise<ConnectResponse>;
+    handleMessage(request: SendMessageRequest): Promise<SendMessageResponse>;
+    handleGetMessages(request: GetMessagesRequest): Promise<GetMessagesResponse>;
+    handleTyping(request: TypingRequest): Promise<{
+        ok: boolean;
+    }>;
+    handlePresence(): Promise<PresenceResponse>;
+    handleRead(request: ReadRequest): Promise<ReadResponse>;
+    /**
+     * Handle user identification from widget
+     * Called when visitor calls PocketPing.identify()
+     */
+    handleIdentify(request: IdentifyRequest): Promise<IdentifyResponse>;
+    /**
+     * Get a session by ID
+     */
+    getSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Handle message edit from widget
+     * Only the message sender can edit their own messages
+     */
+    handleEditMessage(request: EditMessageRequest): Promise<EditMessageResponse>;
+    /**
+     * Handle message delete from widget
+     * Only the message sender can delete their own messages
+     */
+    handleDeleteMessage(request: DeleteMessageRequest): Promise<DeleteMessageResponse>;
+    sendOperatorMessage(sessionId: string, content: string): Promise<Message>;
+    setOperatorOnline(online: boolean): void;
+    /**
+     * Subscribe to custom events from widgets
+     * @param eventName - The name of the event to listen for, or '*' for all events
+     * @param handler - Callback function when event is received
+     * @returns Unsubscribe function
+     * @example
+     * // Listen for specific event
+     * pp.onEvent('clicked_pricing', async (event, session) => {
+     *   console.log(`User ${session.visitorId} clicked pricing: ${event.data?.plan}`)
+     * })
+     *
+     * // Listen for all events
+     * pp.onEvent('*', async (event, session) => {
+     *   console.log(`Event: ${event.name}`, event.data)
+     * })
+     */
+    onEvent(eventName: string, handler: CustomEventHandler): () => void;
+    /**
+     * Unsubscribe from a custom event
+     * @param eventName - The name of the event
+     * @param handler - The handler to remove
+     */
+    offEvent(eventName: string, handler: CustomEventHandler): void;
+    /**
+     * Send a custom event to a specific widget/session
+     * @param sessionId - The session ID to send the event to
+     * @param eventName - The name of the event
+     * @param data - Optional payload to send with the event
+     * @example
+     * // Send a promotion offer to a specific user
+     * pp.emitEvent('session-123', 'show_offer', {
+     *   discount: 20,
+     *   code: 'SAVE20',
+     *   message: 'Special offer just for you!'
+     * })
+     */
+    emitEvent(sessionId: string, eventName: string, data?: Record<string, unknown>): void;
+    /**
+     * Broadcast a custom event to all connected widgets
+     * @param eventName - The name of the event
+     * @param data - Optional payload to send with the event
+     * @example
+     * // Notify all users about maintenance
+     * pp.broadcastEvent('maintenance_warning', {
+     *   message: 'Site will be down for maintenance in 5 minutes'
+     * })
+     */
+    broadcastEvent(eventName: string, data?: Record<string, unknown>): void;
+    /**
+     * Process a custom event server-side (runs handlers, bridges, webhooks)
+     * Useful for server-side automation or triggering events programmatically
+     * @param sessionId - The session ID to associate with the event
+     * @param eventName - The name of the event
+     * @param data - Optional payload for the event
+     * @example
+     * // Trigger event from backend logic (e.g., after purchase)
+     * await pp.triggerEvent('session-123', 'purchase_completed', {
+     *   orderId: 'order-456',
+     *   amount: 99.99
+     * })
+     */
+    triggerEvent(sessionId: string, eventName: string, data?: Record<string, unknown>): Promise<void>;
+    private notifyBridges;
+    private notifyBridgesRead;
+    private notifyBridgesEvent;
+    private notifyBridgesIdentity;
+    /**
+     * Sync message edit to all bridges that support it
+     */
+    private syncEditToBridges;
+    /**
+     * Sync message delete to all bridges that support it
+     */
+    private syncDeleteToBridges;
+    /**
+     * Forward custom event to configured webhook URL (non-blocking)
+     * Used for integrations with Zapier, Make, n8n, or custom backends
+     */
+    private forwardToWebhook;
+    /**
+     * Forward identity update to webhook as a special event
+     */
+    private forwardIdentityToWebhook;
+    addBridge(bridge: Bridge): void;
+    private generateId;
+    getStorage(): Storage;
+    /**
+     * Check widget version against configured min/latest versions
+     * @param widgetVersion - Version from X-PocketPing-Version header
+     * @returns Version check result with status and headers to set
+     */
+    checkWidgetVersion(widgetVersion: string | undefined): VersionCheckResult;
+    /**
+     * Set version warning headers on HTTP response
+     */
+    private setVersionHeaders;
+    /**
+     * Send version warning via WebSocket to a session
+     */
+    sendVersionWarning(sessionId: string, versionCheck: VersionCheckResult): void;
+}
+
 /**
  * Result from sending a message to a bridge.
  * Contains the bridge-specific message ID for later edit/delete.
@@ -84,19 +234,6 @@ interface Bridge {
     destroy?(): void | Promise<void>;
 }
 
-/**
- * AI provider interface.
- * Implement this to add support for OpenAI, Gemini, Claude, or local models.
- */
-interface AIProvider {
-    /** Provider name */
-    name: string;
-    /** Generate a response to the conversation */
-    generateResponse(messages: Message[], systemPrompt?: string): Promise<string>;
-    /** Check if the provider is available */
-    isAvailable(): Promise<boolean>;
-}
-
 /**
  * IP Filtering utilities for PocketPing SDK
  * Supports CIDR notation and individual IP addresses
@@ -134,6 +271,10 @@ interface IpFilterLogEvent {
     timestamp: Date;
     sessionId?: string;
 }
+interface IpFilterResult {
+    allowed: boolean;
+    reason: 'allowlist' | 'blocklist' | 'custom' | 'not_in_allowlist' | 'default';
+}
 /**
  * Custom IP filter callback
  * Return true to allow, false to block, undefined to defer to list-based filtering
@@ -142,6 +283,95 @@ type IpFilterCallback = (ip: string, request: {
     path: string;
     sessionId?: string;
 }) => boolean | undefined | Promise<boolean | undefined>;
+/**
+ * Check if an IP matches a CIDR range or exact IP
+ */
+declare function ipMatchesCidr(ip: string, cidr: string): boolean;
+/**
+ * Check if IP matches any entry in a list of IPs/CIDRs
+ */
+declare function ipMatchesAny(ip: string, list: string[]): boolean;
+/**
+ * Check IP filter with support for custom filter callback
+ */
+declare function checkIpFilter(ip: string, config: IpFilterConfig, requestInfo: {
+    path: string;
+    sessionId?: string;
+}): Promise<IpFilterResult>;
+
+/**
+ * User-Agent Filtering utilities for PocketPing SDK
+ * Blocks bots and unwanted user agents to prevent spam sessions
+ */
+type UaFilterMode = 'allowlist' | 'blocklist' | 'both';
+type UaFilterReason = 'allowlist' | 'blocklist' | 'default_bot' | 'custom' | 'not_in_allowlist' | 'default';
+interface UaFilterConfig {
+    /** Enable/disable UA filtering (default: false) */
+    enabled?: boolean;
+    /** Filter mode (default: 'blocklist') */
+    mode?: UaFilterMode;
+    /** UA patterns to allow (case-insensitive substring match) */
+    allowlist?: string[];
+    /** UA patterns to block (case-insensitive substring match) */
+    blocklist?: string[];
+    /** Include default bot patterns in blocklist (default: true) */
+    useDefaultBots?: boolean;
+    /** Custom filter callback for advanced logic */
+    customFilter?: UaFilterCallback;
+    /** Log blocked requests for security auditing (default: true) */
+    logBlocked?: boolean;
+    /** Custom logger function */
+    logger?: (event: UaFilterLogEvent) => void;
+    /** HTTP status code for blocked requests (default: 403) */
+    blockedStatusCode?: number;
+    /** Response message for blocked requests (default: 'Forbidden') */
+    blockedMessage?: string;
+}
+interface UaFilterLogEvent {
+    type: 'blocked' | 'allowed';
+    userAgent: string;
+    reason: UaFilterReason;
+    matchedPattern?: string;
+    path: string;
+    timestamp: Date;
+    sessionId?: string;
+}
+interface UaFilterResult {
+    allowed: boolean;
+    reason: UaFilterReason;
+    matchedPattern?: string;
+}
+/**
+ * Custom UA filter callback
+ * Return true to allow, false to block, undefined to defer to list-based filtering
+ */
+type UaFilterCallback = (userAgent: string, request: {
+    path: string;
+    sessionId?: string;
+}) => boolean | undefined | Promise<boolean | undefined>;
+/**
+ * Default bot patterns to block
+ * These are known bots, crawlers, and automated tools that shouldn't create chat sessions
+ */
+declare const DEFAULT_BOT_PATTERNS: string[];
+/**
+ * Check if a user-agent matches any pattern in the list
+ * Supports both substring matching and regex patterns (e.g., /bot-\d+/)
+ * Returns the matched pattern or undefined
+ */
+declare function matchesAnyPattern(userAgent: string, patterns: string[]): string | undefined;
+/**
+ * Check UA filter with support for custom filter callback
+ */
+declare function checkUaFilter(userAgent: string | undefined, config: UaFilterConfig, requestInfo: {
+    path: string;
+    sessionId?: string;
+}): Promise<UaFilterResult>;
+/**
+ * Check if a user-agent looks like a bot based on default patterns
+ * Utility function for quick bot detection
+ */
+declare function isBot(userAgent: string): boolean;
 
 interface PocketPingConfig {
     /** Storage adapter for sessions and messages */
@@ -178,6 +408,8 @@ interface PocketPingConfig {
     versionUpgradeUrl?: string;
     /** IP filtering configuration (allowlist/blocklist) */
     ipFilter?: IpFilterConfig;
+    /** User-Agent filtering configuration (block bots/crawlers) */
+    uaFilter?: UaFilterConfig;
 }
 interface AIConfig {
     provider: AIProvider | 'openai' | 'gemini' | 'anthropic';
@@ -416,327 +648,17 @@ interface WebhookPayload {
     sentAt: string;
 }
 
-declare class PocketPing {
-    private storage;
-    private bridges;
-    private config;
-    private wss;
-    private sessionSockets;
-    private operatorOnline;
-    private eventHandlers;
-    constructor(config?: PocketPingConfig);
-    private initStorage;
-    middleware(): (req: IncomingMessage & {
-        body?: unknown;
-        query?: Record<string, string>;
-    }, res: ServerResponse, next?: () => void) => void;
-    private parseBody;
-    attachWebSocket(server: any): void;
-    private handleWebSocketMessage;
-    private handleCustomEvent;
-    private broadcastToSession;
-    handleConnect(request: ConnectRequest): Promise<ConnectResponse>;
-    handleMessage(request: SendMessageRequest): Promise<SendMessageResponse>;
-    handleGetMessages(request: GetMessagesRequest): Promise<GetMessagesResponse>;
-    handleTyping(request: TypingRequest): Promise<{
-        ok: boolean;
-    }>;
-    handlePresence(): Promise<PresenceResponse>;
-    handleRead(request: ReadRequest): Promise<ReadResponse>;
-    /**
-     * Handle user identification from widget
-     * Called when visitor calls PocketPing.identify()
-     */
-    handleIdentify(request: IdentifyRequest): Promise<IdentifyResponse>;
-    /**
-     * Get a session by ID
-     */
-    getSession(sessionId: string): Promise<Session | null>;
-    /**
-     * Handle message edit from widget
-     * Only the message sender can edit their own messages
-     */
-    handleEditMessage(request: EditMessageRequest): Promise<EditMessageResponse>;
-    /**
-     * Handle message delete from widget
-     * Only the message sender can delete their own messages
-     */
-    handleDeleteMessage(request: DeleteMessageRequest): Promise<DeleteMessageResponse>;
-    sendOperatorMessage(sessionId: string, content: string): Promise<Message>;
-    setOperatorOnline(online: boolean): void;
-    /**
-     * Subscribe to custom events from widgets
-     * @param eventName - The name of the event to listen for, or '*' for all events
-     * @param handler - Callback function when event is received
-     * @returns Unsubscribe function
-     * @example
-     * // Listen for specific event
-     * pp.onEvent('clicked_pricing', async (event, session) => {
-     *   console.log(`User ${session.visitorId} clicked pricing: ${event.data?.plan}`)
-     * })
-     *
-     * // Listen for all events
-     * pp.onEvent('*', async (event, session) => {
-     *   console.log(`Event: ${event.name}`, event.data)
-     * })
-     */
-    onEvent(eventName: string, handler: CustomEventHandler): () => void;
-    /**
-     * Unsubscribe from a custom event
-     * @param eventName - The name of the event
-     * @param handler - The handler to remove
-     */
-    offEvent(eventName: string, handler: CustomEventHandler): void;
-    /**
-     * Send a custom event to a specific widget/session
-     * @param sessionId - The session ID to send the event to
-     * @param eventName - The name of the event
-     * @param data - Optional payload to send with the event
-     * @example
-     * // Send a promotion offer to a specific user
-     * pp.emitEvent('session-123', 'show_offer', {
-     *   discount: 20,
-     *   code: 'SAVE20',
-     *   message: 'Special offer just for you!'
-     * })
-     */
-    emitEvent(sessionId: string, eventName: string, data?: Record<string, unknown>): void;
-    /**
-     * Broadcast a custom event to all connected widgets
-     * @param eventName - The name of the event
-     * @param data - Optional payload to send with the event
-     * @example
-     * // Notify all users about maintenance
-     * pp.broadcastEvent('maintenance_warning', {
-     *   message: 'Site will be down for maintenance in 5 minutes'
-     * })
-     */
-    broadcastEvent(eventName: string, data?: Record<string, unknown>): void;
-    /**
-     * Process a custom event server-side (runs handlers, bridges, webhooks)
-     * Useful for server-side automation or triggering events programmatically
-     * @param sessionId - The session ID to associate with the event
-     * @param eventName - The name of the event
-     * @param data - Optional payload for the event
-     * @example
-     * // Trigger event from backend logic (e.g., after purchase)
-     * await pp.triggerEvent('session-123', 'purchase_completed', {
-     *   orderId: 'order-456',
-     *   amount: 99.99
-     * })
-     */
-    triggerEvent(sessionId: string, eventName: string, data?: Record<string, unknown>): Promise<void>;
-    private notifyBridges;
-    private notifyBridgesRead;
-    private notifyBridgesEvent;
-    private notifyBridgesIdentity;
-    /**
-     * Sync message edit to all bridges that support it
-     */
-    private syncEditToBridges;
-    /**
-     * Sync message delete to all bridges that support it
-     */
-    private syncDeleteToBridges;
-    /**
-     * Forward custom event to configured webhook URL (non-blocking)
-     * Used for integrations with Zapier, Make, n8n, or custom backends
-     */
-    private forwardToWebhook;
-    /**
-     * Forward identity update to webhook as a special event
-     */
-    private forwardIdentityToWebhook;
-    addBridge(bridge: Bridge): void;
-    private generateId;
-    getStorage(): Storage;
-    /**
-     * Check widget version against configured min/latest versions
-     * @param widgetVersion - Version from X-PocketPing-Version header
-     * @returns Version check result with status and headers to set
-     */
-    checkWidgetVersion(widgetVersion: string | undefined): VersionCheckResult;
-    /**
-     * Set version warning headers on HTTP response
-     */
-    private setVersionHeaders;
-    /**
-     * Send version warning via WebSocket to a session
-     */
-    sendVersionWarning(sessionId: string, versionCheck: VersionCheckResult): void;
-}
-
-/**
- * In-memory storage adapter.
- * Useful for development and testing. Data is lost on restart.
- */
-declare class MemoryStorage implements Storage {
-    private sessions;
-    private messages;
-    private messageById;
-    private bridgeMessageIds;
-    createSession(session: Session): Promise<void>;
-    getSession(sessionId: string): Promise<Session | null>;
-    getSessionByVisitorId(visitorId: string): Promise<Session | null>;
-    updateSession(session: Session): Promise<void>;
-    deleteSession(sessionId: string): Promise<void>;
-    saveMessage(message: Message): Promise<void>;
-    getMessages(sessionId: string, after?: string, limit?: number): Promise<Message[]>;
-    getMessage(messageId: string): Promise<Message | null>;
-    updateMessage(message: Message): Promise<void>;
-    saveBridgeMessageIds(messageId: string, bridgeIds: BridgeMessageIds): Promise<void>;
-    getBridgeMessageIds(messageId: string): Promise<BridgeMessageIds | null>;
-    cleanupOldSessions(olderThan: Date): Promise<number>;
-}
-
-/** Attachment from an operator message */
-interface OperatorAttachment {
-    filename: string;
-    mimeType: string;
-    size: number;
-    data: Buffer;
-    bridgeFileId?: string;
-}
-/** Callback when operator sends a message from a bridge */
-type OperatorMessageCallback = (sessionId: string, content: string, operatorName: string, sourceBridge: 'telegram' | 'discord' | 'slack', attachments: OperatorAttachment[], replyToBridgeMessageId?: number | null, bridgeMessageId?: number | string | null) => void | Promise<void>;
-type OperatorMessageEditCallback = (sessionId: string, bridgeMessageId: number | string, content: string, sourceBridge: 'telegram' | 'discord' | 'slack', editedAt?: string) => void | Promise<void>;
-type OperatorMessageDeleteCallback = (sessionId: string, bridgeMessageId: number | string, sourceBridge: 'telegram' | 'discord' | 'slack', deletedAt?: string) => void | Promise<void>;
-/** Webhook handler configuration */
-interface WebhookConfig {
-    telegramBotToken?: string;
-    slackBotToken?: string;
-    discordBotToken?: string;
-    allowedBotIds?: string[];
-    onOperatorMessage: OperatorMessageCallback;
-    onOperatorMessageEdit?: OperatorMessageEditCallback;
-    onOperatorMessageDelete?: OperatorMessageDeleteCallback;
-}
-declare class WebhookHandler {
-    private config;
-    constructor(config: WebhookConfig);
-    /**
-     * Create an Express/Connect middleware for handling Telegram webhooks
-     */
-    handleTelegramWebhook(): (req: IncomingMessage & {
-        body?: unknown;
-    }, res: ServerResponse) => Promise<void>;
-    /**
-     * Create an Express/Connect middleware for handling Slack webhooks
-     */
-    handleSlackWebhook(): (req: IncomingMessage & {
-        body?: unknown;
-    }, res: ServerResponse) => Promise<void>;
-    /**
-     * Create an Express/Connect middleware for handling Discord webhooks
-     */
-    handleDiscordWebhook(): (req: IncomingMessage & {
-        body?: unknown;
-    }, res: ServerResponse) => Promise<void>;
-    private parseBody;
-    private writeOK;
-    private downloadTelegramFile;
-    private downloadSlackFile;
-    private getSlackUserName;
-}
-
 /**
- * Options for TelegramBridge
- */
-interface TelegramBridgeOptions {
-    /** Parse mode for message formatting */
-    parseMode?: 'HTML' | 'Markdown';
-    /** Disable notification sound */
-    disableNotification?: boolean;
-}
-/**
- * Telegram Bridge for PocketPing.
- * Sends visitor messages to a Telegram chat using the Bot API.
- *
- * @example
- * ```ts
- * const telegram = new TelegramBridge(
- *   'BOT_TOKEN',
- *   '-1001234567890',
- *   { parseMode: 'HTML' }
- * );
- * const pocketping = new PocketPing({ bridges: [telegram] });
- * ```
+ * AI provider interface.
+ * Implement this to add support for OpenAI, Gemini, Claude, or local models.
  */
-declare class TelegramBridge implements Bridge {
-    readonly name = "telegram";
-    private pocketping?;
-    private readonly botToken;
-    private readonly chatId;
-    private readonly parseMode;
-    private readonly disableNotification;
-    private readonly baseUrl;
-    constructor(botToken: string, chatId: string | number, options?: TelegramBridgeOptions);
-    /**
-     * Initialize the bridge (optional setup)
-     */
-    init(pocketping: PocketPing): Promise<void>;
-    /**
-     * Called when a new chat session is created
-     */
-    onNewSession(session: Session): Promise<void>;
-    /**
-     * Called when a visitor sends a message.
-     * Returns the Telegram message ID for edit/delete sync.
-     */
-    onVisitorMessage(message: Message, session: Session): Promise<BridgeMessageResult>;
-    /**
-     * Called when an operator sends a message (for cross-bridge sync)
-     */
-    onOperatorMessage(message: Message, _session: Session, sourceBridge?: string, operatorName?: string): Promise<void>;
-    /**
-     * Called when visitor starts/stops typing
-     */
-    onTyping(sessionId: string, isTyping: boolean): Promise<void>;
-    /**
-     * Called when a visitor edits their message.
-     * @returns true if edit succeeded, false otherwise
-     */
-    onMessageEdit(_messageId: string, newContent: string, bridgeMessageId: string | number): Promise<boolean>;
-    /**
-     * Called when a visitor deletes their message.
-     * @returns true if delete succeeded, false otherwise
-     */
-    onMessageDelete(_messageId: string, bridgeMessageId: string | number): Promise<boolean>;
-    /**
-     * Called when a custom event is triggered from the widget
-     */
-    onCustomEvent(event: {
-        name: string;
-        data?: Record<string, unknown>;
-    }, session: Session): Promise<void>;
-    /**
-     * Called when a user identifies themselves via PocketPing.identify()
-     */
-    onIdentityUpdate(session: Session): Promise<void>;
-    /**
-     * Send a message to the Telegram chat
-     */
-    private sendMessage;
-    /**
-     * Send a chat action (e.g., "typing")
-     */
-    private sendChatAction;
-    /**
-     * Format new session notification
-     */
-    private formatNewSession;
-    /**
-     * Format visitor message
-     */
-    private formatVisitorMessage;
-    /**
-     * Escape HTML special characters
-     */
-    private escapeHtml;
-    /**
-     * Escape Markdown special characters
-     */
-    private escapeMarkdown;
+interface AIProvider {
+    /** Provider name */
+    name: string;
+    /** Generate a response to the conversation */
+    generateResponse(messages: Message[], systemPrompt?: string): Promise<string>;
+    /** Check if the provider is available */
+    isAvailable(): Promise<boolean>;
 }
 
 /**
@@ -958,4 +880,177 @@ declare class SlackBridge implements Bridge {
     private escapeSlack;
 }
 
-export { type AIProvider, type Bridge, type BridgeMessageIds, type BridgeMessageResult, type ConnectRequest, type ConnectResponse, type CustomEvent, type CustomEventHandler, type DeleteMessageRequest, type DeleteMessageResponse, type DiscordBotOptions, DiscordBridge, type DiscordWebhookOptions, type EditMessageRequest, type EditMessageResponse, MemoryStorage, type Message, type OperatorAttachment, type OperatorMessageCallback, type OperatorMessageDeleteCallback, type OperatorMessageEditCallback, PocketPing, type PocketPingConfig, type PresenceResponse, type SendMessageRequest, type SendMessageResponse, type Session, type SlackBotOptions, SlackBridge, type SlackWebhookOptions, type Storage, TelegramBridge, type TelegramBridgeOptions, type TrackedElement, type TriggerOptions, type WebhookConfig, WebhookHandler, type WebhookPayload };
+/**
+ * Options for TelegramBridge
+ */
+interface TelegramBridgeOptions {
+    /** Parse mode for message formatting */
+    parseMode?: 'HTML' | 'Markdown';
+    /** Disable notification sound */
+    disableNotification?: boolean;
+}
+/**
+ * Telegram Bridge for PocketPing.
+ * Sends visitor messages to a Telegram chat using the Bot API.
+ *
+ * @example
+ * ```ts
+ * const telegram = new TelegramBridge(
+ *   'BOT_TOKEN',
+ *   '-1001234567890',
+ *   { parseMode: 'HTML' }
+ * );
+ * const pocketping = new PocketPing({ bridges: [telegram] });
+ * ```
+ */
+declare class TelegramBridge implements Bridge {
+    readonly name = "telegram";
+    private pocketping?;
+    private readonly botToken;
+    private readonly chatId;
+    private readonly parseMode;
+    private readonly disableNotification;
+    private readonly baseUrl;
+    constructor(botToken: string, chatId: string | number, options?: TelegramBridgeOptions);
+    /**
+     * Initialize the bridge (optional setup)
+     */
+    init(pocketping: PocketPing): Promise<void>;
+    /**
+     * Called when a new chat session is created
+     */
+    onNewSession(session: Session): Promise<void>;
+    /**
+     * Called when a visitor sends a message.
+     * Returns the Telegram message ID for edit/delete sync.
+     */
+    onVisitorMessage(message: Message, session: Session): Promise<BridgeMessageResult>;
+    /**
+     * Called when an operator sends a message (for cross-bridge sync)
+     */
+    onOperatorMessage(message: Message, _session: Session, sourceBridge?: string, operatorName?: string): Promise<void>;
+    /**
+     * Called when visitor starts/stops typing
+     */
+    onTyping(_sessionId: string, isTyping: boolean): Promise<void>;
+    /**
+     * Called when a visitor edits their message.
+     * @returns true if edit succeeded, false otherwise
+     */
+    onMessageEdit(_messageId: string, newContent: string, bridgeMessageId: string | number): Promise<boolean>;
+    /**
+     * Called when a visitor deletes their message.
+     * @returns true if delete succeeded, false otherwise
+     */
+    onMessageDelete(_messageId: string, bridgeMessageId: string | number): Promise<boolean>;
+    /**
+     * Called when a custom event is triggered from the widget
+     */
+    onCustomEvent(event: {
+        name: string;
+        data?: Record<string, unknown>;
+    }, session: Session): Promise<void>;
+    /**
+     * Called when a user identifies themselves via PocketPing.identify()
+     */
+    onIdentityUpdate(session: Session): Promise<void>;
+    /**
+     * Send a message to the Telegram chat
+     */
+    private sendMessage;
+    /**
+     * Send a chat action (e.g., "typing")
+     */
+    private sendChatAction;
+    /**
+     * Format new session notification
+     */
+    private formatNewSession;
+    /**
+     * Format visitor message
+     */
+    private formatVisitorMessage;
+    /**
+     * Escape HTML special characters
+     */
+    private escapeHtml;
+    /**
+     * Escape Markdown special characters
+     */
+    private escapeMarkdown;
+}
+
+/**
+ * In-memory storage adapter.
+ * Useful for development and testing. Data is lost on restart.
+ */
+declare class MemoryStorage implements Storage {
+    private sessions;
+    private messages;
+    private messageById;
+    private bridgeMessageIds;
+    createSession(session: Session): Promise<void>;
+    getSession(sessionId: string): Promise<Session | null>;
+    getSessionByVisitorId(visitorId: string): Promise<Session | null>;
+    updateSession(session: Session): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    saveMessage(message: Message): Promise<void>;
+    getMessages(sessionId: string, after?: string, limit?: number): Promise<Message[]>;
+    getMessage(messageId: string): Promise<Message | null>;
+    updateMessage(message: Message): Promise<void>;
+    saveBridgeMessageIds(messageId: string, bridgeIds: BridgeMessageIds): Promise<void>;
+    getBridgeMessageIds(messageId: string): Promise<BridgeMessageIds | null>;
+    cleanupOldSessions(olderThan: Date): Promise<number>;
+}
+
+/** Attachment from an operator message */
+interface OperatorAttachment {
+    filename: string;
+    mimeType: string;
+    size: number;
+    data: Buffer;
+    bridgeFileId?: string;
+}
+/** Callback when operator sends a message from a bridge */
+type OperatorMessageCallback = (sessionId: string, content: string, operatorName: string, sourceBridge: 'telegram' | 'discord' | 'slack', attachments: OperatorAttachment[], replyToBridgeMessageId?: number | null, bridgeMessageId?: number | string | null) => void | Promise<void>;
+type OperatorMessageEditCallback = (sessionId: string, bridgeMessageId: number | string, content: string, sourceBridge: 'telegram' | 'discord' | 'slack', editedAt?: string) => void | Promise<void>;
+type OperatorMessageDeleteCallback = (sessionId: string, bridgeMessageId: number | string, sourceBridge: 'telegram' | 'discord' | 'slack', deletedAt?: string) => void | Promise<void>;
+/** Webhook handler configuration */
+interface WebhookConfig {
+    telegramBotToken?: string;
+    slackBotToken?: string;
+    discordBotToken?: string;
+    allowedBotIds?: string[];
+    onOperatorMessage: OperatorMessageCallback;
+    onOperatorMessageEdit?: OperatorMessageEditCallback;
+    onOperatorMessageDelete?: OperatorMessageDeleteCallback;
+}
+declare class WebhookHandler {
+    private config;
+    constructor(config: WebhookConfig);
+    /**
+     * Create an Express/Connect middleware for handling Telegram webhooks
+     */
+    handleTelegramWebhook(): (req: IncomingMessage & {
+        body?: unknown;
+    }, res: ServerResponse) => Promise<void>;
+    /**
+     * Create an Express/Connect middleware for handling Slack webhooks
+     */
+    handleSlackWebhook(): (req: IncomingMessage & {
+        body?: unknown;
+    }, res: ServerResponse) => Promise<void>;
+    /**
+     * Create an Express/Connect middleware for handling Discord webhooks
+     */
+    handleDiscordWebhook(): (req: IncomingMessage & {
+        body?: unknown;
+    }, res: ServerResponse) => Promise<void>;
+    private parseBody;
+    private writeOK;
+    private downloadTelegramFile;
+    private downloadSlackFile;
+    private getSlackUserName;
+}
+
+export { type AIProvider, type Bridge, type BridgeMessageIds, type BridgeMessageResult, type ConnectRequest, type ConnectResponse, type CustomEvent, type CustomEventHandler, DEFAULT_BOT_PATTERNS, type DeleteMessageRequest, type DeleteMessageResponse, type DiscordBotOptions, DiscordBridge, type DiscordWebhookOptions, type EditMessageRequest, type EditMessageResponse, type IpFilterConfig, type IpFilterLogEvent, type IpFilterMode, MemoryStorage, type Message, type OperatorAttachment, type OperatorMessageCallback, type OperatorMessageDeleteCallback, type OperatorMessageEditCallback, PocketPing, type PocketPingConfig, type PresenceResponse, type SendMessageRequest, type SendMessageResponse, type Session, type SlackBotOptions, SlackBridge, type SlackWebhookOptions, type Storage, TelegramBridge, type TelegramBridgeOptions, type TrackedElement, type TriggerOptions, type UaFilterConfig, type UaFilterLogEvent, type UaFilterMode, type UaFilterReason, type UaFilterResult, type WebhookConfig, WebhookHandler, type WebhookPayload, checkIpFilter, checkUaFilter, ipMatchesAny, ipMatchesCidr, isBot, matchesAnyPattern };