@pocketping/sdk-node 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -1,5 +1,14 @@
 import { IncomingMessage, ServerResponse } from 'http';
 
+/**
+ * Bridge message IDs for edit/delete sync.
+ * Stored when a message is sent to bridges.
+ */
+interface BridgeMessageIds {
+    telegramMessageId?: number;
+    discordMessageId?: string;
+    slackMessageTs?: string;
+}
 /**
  * Storage adapter interface.
  * Implement this interface to use any database with PocketPing.
@@ -13,9 +22,23 @@ interface Storage {
     saveMessage(message: Message): Promise<void>;
     getMessages(sessionId: string, after?: string, limit?: number): Promise<Message[]>;
     getMessage(messageId: string): Promise<Message | null>;
+    /** Update an existing message (for edit/delete) */
+    updateMessage?(message: Message): Promise<void>;
+    /** Save bridge message IDs for a message */
+    saveBridgeMessageIds?(messageId: string, bridgeIds: BridgeMessageIds): Promise<void>;
+    /** Get bridge message IDs for a message */
+    getBridgeMessageIds?(messageId: string): Promise<BridgeMessageIds | null>;
     cleanupOldSessions?(olderThan: Date): Promise<number>;
 }
 
+/**
+ * Result from sending a message to a bridge.
+ * Contains the bridge-specific message ID for later edit/delete.
+ */
+interface BridgeMessageResult {
+    /** Bridge-specific message ID */
+    messageId?: string | number;
+}
 /**
  * Bridge interface for notification channels.
  * Implement this interface to add support for Telegram, Discord, Slack, etc.
@@ -27,14 +50,32 @@ interface Bridge {
     init?(pocketping: PocketPing): void | Promise<void>;
     /** Called when a new chat session is created */
     onNewSession?(session: Session): void | Promise<void>;
-    /** Called when a visitor sends a message */
-    onVisitorMessage?(message: Message, session: Session): void | Promise<void>;
+    /**
+     * Called when a visitor sends a message.
+     * Return the bridge message ID for edit/delete sync.
+     */
+    onVisitorMessage?(message: Message, session: Session): void | BridgeMessageResult | Promise<void | BridgeMessageResult>;
     /** Called when an operator sends a message (for cross-bridge sync) */
     onOperatorMessage?(message: Message, session: Session, sourceBridge?: string, operatorName?: string): void | Promise<void>;
     /** Called when visitor starts/stops typing */
     onTyping?(sessionId: string, isTyping: boolean): void | Promise<void>;
     /** Called when messages are marked as delivered/read */
     onMessageRead?(sessionId: string, messageIds: string[], status: MessageStatus, session: Session): void | Promise<void>;
+    /**
+     * Called when a visitor edits their message.
+     * @param messageId - The message ID in PocketPing
+     * @param newContent - The new message content
+     * @param bridgeMessageId - The bridge-specific message ID
+     * @returns true if edit succeeded, false otherwise
+     */
+    onMessageEdit?(messageId: string, newContent: string, bridgeMessageId: string | number): boolean | Promise<boolean>;
+    /**
+     * Called when a visitor deletes their message.
+     * @param messageId - The message ID in PocketPing
+     * @param bridgeMessageId - The bridge-specific message ID
+     * @returns true if delete succeeded, false otherwise
+     */
+    onMessageDelete?(messageId: string, bridgeMessageId: string | number): boolean | Promise<boolean>;
     /** Called when a custom event is triggered from the widget */
     onCustomEvent?(event: CustomEvent, session: Session): void | Promise<void>;
     /** Called when a user identifies themselves via PocketPing.identify() */
@@ -184,6 +225,29 @@ interface SessionMetadata {
     [key: string]: unknown;
 }
 type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
+type AttachmentStatus = 'pending' | 'uploading' | 'ready' | 'failed';
+type UploadSource = 'widget' | 'telegram' | 'discord' | 'slack' | 'api';
+/** File attachment in a message */
+interface Attachment {
+    /** Unique attachment ID */
+    id: string;
+    /** Original filename */
+    filename: string;
+    /** MIME type (e.g., 'image/jpeg', 'application/pdf') */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** URL to access the file */
+    url: string;
+    /** Thumbnail URL (for images/videos) */
+    thumbnailUrl?: string;
+    /** Upload status */
+    status: AttachmentStatus;
+    /** Source of the upload */
+    uploadedFrom?: UploadSource;
+    /** External file ID (from Telegram/Discord/Slack) */
+    bridgeFileId?: string;
+}
 interface Message {
     id: string;
     sessionId: string;
@@ -192,9 +256,38 @@ interface Message {
     timestamp: Date;
     replyTo?: string;
     metadata?: Record<string, unknown>;
+    /** File attachments in this message */
+    attachments?: Attachment[];
     status?: MessageStatus;
     deliveredAt?: Date;
     readAt?: Date;
+    /** Timestamp when message was edited */
+    editedAt?: Date;
+    /** Timestamp when message was soft-deleted */
+    deletedAt?: Date;
+}
+/** Request to edit a message */
+interface EditMessageRequest {
+    sessionId: string;
+    messageId: string;
+    content: string;
+}
+/** Response after editing a message */
+interface EditMessageResponse {
+    message: {
+        id: string;
+        content: string;
+        editedAt: string;
+    };
+}
+/** Request to delete a message */
+interface DeleteMessageRequest {
+    sessionId: string;
+    messageId: string;
+}
+/** Response after deleting a message */
+interface DeleteMessageResponse {
+    deleted: boolean;
 }
 interface ConnectRequest {
     visitorId: string;
@@ -235,6 +328,10 @@ interface SendMessageRequest {
     content: string;
     sender: 'visitor' | 'operator';
     replyTo?: string;
+    /** Attachment IDs to include with the message */
+    attachmentIds?: string[];
+    /** Inline attachments (for operator messages from bridges) */
+    attachments?: Attachment[];
 }
 interface SendMessageResponse {
     messageId: string;
@@ -351,6 +448,16 @@ declare class PocketPing {
      * 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;
     /**
@@ -419,6 +526,14 @@ declare class PocketPing {
     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
@@ -455,6 +570,7 @@ 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>;
@@ -463,7 +579,379 @@ declare class MemoryStorage implements Storage {
     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>;
 }
 
-export { type AIProvider, type Bridge, type ConnectRequest, type ConnectResponse, type CustomEvent, type CustomEventHandler, MemoryStorage, type Message, PocketPing, type PocketPingConfig, type PresenceResponse, type SendMessageRequest, type SendMessageResponse, type Session, type Storage, type TrackedElement, type TriggerOptions, type WebhookPayload };
+/** 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] });
+ * ```
+ */
+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;
+}
+
+/**
+ * Options for Discord webhook mode
+ */
+interface DiscordWebhookOptions {
+    /** Custom username for webhook messages */
+    username?: string;
+    /** Custom avatar URL for webhook messages */
+    avatarUrl?: string;
+}
+/**
+ * Options for Discord bot mode
+ */
+interface DiscordBotOptions {
+    /** Custom username displayed in embeds */
+    username?: string;
+    /** Custom avatar URL for embeds */
+    avatarUrl?: string;
+}
+/**
+ * Discord Bridge for PocketPing.
+ * Sends visitor messages to a Discord channel using webhooks or bot API.
+ *
+ * @example Webhook mode
+ * ```ts
+ * const discord = DiscordBridge.webhook(
+ *   'https://discord.com/api/webhooks/123/abc',
+ *   { username: 'PocketPing' }
+ * );
+ * ```
+ *
+ * @example Bot mode
+ * ```ts
+ * const discord = DiscordBridge.bot(
+ *   'BOT_TOKEN',
+ *   'CHANNEL_ID',
+ *   { username: 'PocketPing' }
+ * );
+ * ```
+ */
+declare class DiscordBridge implements Bridge {
+    readonly name = "discord";
+    private pocketping?;
+    private readonly mode;
+    private readonly webhookUrl?;
+    private readonly botToken?;
+    private readonly channelId?;
+    private readonly username?;
+    private readonly avatarUrl?;
+    private constructor();
+    /**
+     * Create a Discord bridge using a webhook URL
+     */
+    static webhook(webhookUrl: string, options?: DiscordWebhookOptions): DiscordBridge;
+    /**
+     * Create a Discord bridge using a bot token
+     */
+    static bot(botToken: string, channelId: string, options?: DiscordBotOptions): DiscordBridge;
+    /**
+     * 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 Discord 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 an embed to Discord
+     */
+    private sendEmbed;
+}
+
+/**
+ * Options for Slack webhook mode
+ */
+interface SlackWebhookOptions {
+    /** Custom username for webhook messages */
+    username?: string;
+    /** Custom emoji icon (e.g., ':robot_face:') */
+    iconEmoji?: string;
+    /** Custom icon URL (overrides iconEmoji) */
+    iconUrl?: string;
+}
+/**
+ * Options for Slack bot mode
+ */
+interface SlackBotOptions {
+    /** Custom username for bot messages */
+    username?: string;
+    /** Custom emoji icon (e.g., ':robot_face:') */
+    iconEmoji?: string;
+    /** Custom icon URL (overrides iconEmoji) */
+    iconUrl?: string;
+}
+/**
+ * Slack Bridge for PocketPing.
+ * Sends visitor messages to a Slack channel using webhooks or bot API.
+ *
+ * @example Webhook mode
+ * ```ts
+ * const slack = SlackBridge.webhook(
+ *   'https://hooks.slack.com/services/T.../B.../xxx',
+ *   { username: 'PocketPing', iconEmoji: ':speech_balloon:' }
+ * );
+ * ```
+ *
+ * @example Bot mode
+ * ```ts
+ * const slack = SlackBridge.bot(
+ *   'xoxb-YOUR-BOT-TOKEN',
+ *   'C1234567890',
+ *   { username: 'PocketPing' }
+ * );
+ * ```
+ */
+declare class SlackBridge implements Bridge {
+    readonly name = "slack";
+    private pocketping?;
+    private readonly mode;
+    private readonly webhookUrl?;
+    private readonly botToken?;
+    private readonly channelId?;
+    private readonly username?;
+    private readonly iconEmoji?;
+    private readonly iconUrl?;
+    private constructor();
+    /**
+     * Create a Slack bridge using a webhook URL
+     */
+    static webhook(webhookUrl: string, options?: SlackWebhookOptions): SlackBridge;
+    /**
+     * Create a Slack bridge using a bot token
+     */
+    static bot(botToken: string, channelId: string, options?: SlackBotOptions): SlackBridge;
+    /**
+     * 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 Slack message timestamp 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 blocks to Slack
+     */
+    private sendBlocks;
+    /**
+     * Escape special characters for Slack mrkdwn
+     */
+    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 };