@pocketping/sdk-node 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,222 @@
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Storage adapter interface.
+ * Implement this interface to use any database with PocketPing.
+ */
+interface Storage {
+    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>;
+    cleanupOldSessions?(olderThan: Date): Promise<number>;
+}
+
+/**
+ * Bridge interface for notification channels.
+ * Implement this interface to add support for Telegram, Discord, Slack, etc.
+ */
+interface Bridge {
+    /** Unique name for this bridge */
+    name: string;
+    /** Called when the bridge is added to PocketPing */
+    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 */
+    onMessage?(message: Message, session: Session): 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): void | Promise<void>;
+    /** Cleanup when bridge is removed */
+    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>;
+}
+
+interface PocketPingConfig {
+    /** Storage adapter for sessions and messages */
+    storage?: Storage | 'memory';
+    /** Notification bridges (Telegram, Discord, etc.) */
+    bridges?: Bridge[];
+    /** AI fallback configuration */
+    ai?: AIConfig;
+    /** Welcome message shown to new visitors */
+    welcomeMessage?: string;
+    /** Seconds of inactivity before AI takes over (default: 300) */
+    aiTakeoverDelay?: number;
+    /** Callback when a new session is created */
+    onNewSession?: (session: Session) => void | Promise<void>;
+    /** Callback when a message is received */
+    onMessage?: (message: Message, session: Session) => void | Promise<void>;
+}
+interface AIConfig {
+    provider: AIProvider | 'openai' | 'gemini' | 'anthropic';
+    apiKey?: string;
+    model?: string;
+    systemPrompt?: string;
+    fallbackAfter?: number;
+}
+interface Session {
+    id: string;
+    visitorId: string;
+    createdAt: Date;
+    lastActivity: Date;
+    operatorOnline: boolean;
+    aiActive: boolean;
+    metadata?: SessionMetadata;
+}
+interface SessionMetadata {
+    url?: string;
+    referrer?: string;
+    pageTitle?: string;
+    userAgent?: string;
+    timezone?: string;
+    language?: string;
+    screenResolution?: string;
+    ip?: string;
+    country?: string;
+    city?: string;
+    deviceType?: 'desktop' | 'mobile' | 'tablet';
+    browser?: string;
+    os?: string;
+    [key: string]: unknown;
+}
+type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
+interface Message {
+    id: string;
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator' | 'ai';
+    timestamp: Date;
+    replyTo?: string;
+    metadata?: Record<string, unknown>;
+    status?: MessageStatus;
+    deliveredAt?: Date;
+    readAt?: Date;
+}
+interface ConnectRequest {
+    visitorId: string;
+    sessionId?: string;
+    metadata?: SessionMetadata;
+}
+interface ConnectResponse {
+    sessionId: string;
+    visitorId: string;
+    operatorOnline: boolean;
+    welcomeMessage?: string;
+    messages: Message[];
+}
+interface SendMessageRequest {
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator';
+    replyTo?: string;
+}
+interface SendMessageResponse {
+    messageId: string;
+    timestamp: string;
+}
+interface GetMessagesRequest {
+    sessionId: string;
+    after?: string;
+    limit?: number;
+}
+interface GetMessagesResponse {
+    messages: Message[];
+    hasMore: boolean;
+}
+interface TypingRequest {
+    sessionId: string;
+    sender: 'visitor' | 'operator';
+    isTyping?: boolean;
+}
+interface ReadRequest {
+    sessionId: string;
+    messageIds: string[];
+    status?: MessageStatus;
+}
+interface ReadResponse {
+    updated: number;
+}
+interface PresenceResponse {
+    online: boolean;
+    operators?: Array<{
+        id: string;
+        name: string;
+        avatar?: string;
+    }>;
+    aiEnabled: boolean;
+    aiActiveAfter?: number;
+}
+
+declare class PocketPing {
+    private storage;
+    private bridges;
+    private config;
+    private wss;
+    private sessionSockets;
+    private operatorOnline;
+    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 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>;
+    sendOperatorMessage(sessionId: string, content: string): Promise<Message>;
+    setOperatorOnline(online: boolean): void;
+    private notifyBridges;
+    private notifyBridgesRead;
+    addBridge(bridge: Bridge): void;
+    private generateId;
+    getStorage(): Storage;
+}
+
+/**
+ * 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;
+    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>;
+    cleanupOldSessions(olderThan: Date): Promise<number>;
+}
+
+export { type AIProvider, type Bridge, type ConnectRequest, type ConnectResponse, MemoryStorage, type Message, PocketPing, type PocketPingConfig, type PresenceResponse, type SendMessageRequest, type SendMessageResponse, type Session, type Storage };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Storage adapter interface.
+ * Implement this interface to use any database with PocketPing.
+ */
+interface Storage {
+    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>;
+    cleanupOldSessions?(olderThan: Date): Promise<number>;
+}
+
+/**
+ * Bridge interface for notification channels.
+ * Implement this interface to add support for Telegram, Discord, Slack, etc.
+ */
+interface Bridge {
+    /** Unique name for this bridge */
+    name: string;
+    /** Called when the bridge is added to PocketPing */
+    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 */
+    onMessage?(message: Message, session: Session): 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): void | Promise<void>;
+    /** Cleanup when bridge is removed */
+    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>;
+}
+
+interface PocketPingConfig {
+    /** Storage adapter for sessions and messages */
+    storage?: Storage | 'memory';
+    /** Notification bridges (Telegram, Discord, etc.) */
+    bridges?: Bridge[];
+    /** AI fallback configuration */
+    ai?: AIConfig;
+    /** Welcome message shown to new visitors */
+    welcomeMessage?: string;
+    /** Seconds of inactivity before AI takes over (default: 300) */
+    aiTakeoverDelay?: number;
+    /** Callback when a new session is created */
+    onNewSession?: (session: Session) => void | Promise<void>;
+    /** Callback when a message is received */
+    onMessage?: (message: Message, session: Session) => void | Promise<void>;
+}
+interface AIConfig {
+    provider: AIProvider | 'openai' | 'gemini' | 'anthropic';
+    apiKey?: string;
+    model?: string;
+    systemPrompt?: string;
+    fallbackAfter?: number;
+}
+interface Session {
+    id: string;
+    visitorId: string;
+    createdAt: Date;
+    lastActivity: Date;
+    operatorOnline: boolean;
+    aiActive: boolean;
+    metadata?: SessionMetadata;
+}
+interface SessionMetadata {
+    url?: string;
+    referrer?: string;
+    pageTitle?: string;
+    userAgent?: string;
+    timezone?: string;
+    language?: string;
+    screenResolution?: string;
+    ip?: string;
+    country?: string;
+    city?: string;
+    deviceType?: 'desktop' | 'mobile' | 'tablet';
+    browser?: string;
+    os?: string;
+    [key: string]: unknown;
+}
+type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read';
+interface Message {
+    id: string;
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator' | 'ai';
+    timestamp: Date;
+    replyTo?: string;
+    metadata?: Record<string, unknown>;
+    status?: MessageStatus;
+    deliveredAt?: Date;
+    readAt?: Date;
+}
+interface ConnectRequest {
+    visitorId: string;
+    sessionId?: string;
+    metadata?: SessionMetadata;
+}
+interface ConnectResponse {
+    sessionId: string;
+    visitorId: string;
+    operatorOnline: boolean;
+    welcomeMessage?: string;
+    messages: Message[];
+}
+interface SendMessageRequest {
+    sessionId: string;
+    content: string;
+    sender: 'visitor' | 'operator';
+    replyTo?: string;
+}
+interface SendMessageResponse {
+    messageId: string;
+    timestamp: string;
+}
+interface GetMessagesRequest {
+    sessionId: string;
+    after?: string;
+    limit?: number;
+}
+interface GetMessagesResponse {
+    messages: Message[];
+    hasMore: boolean;
+}
+interface TypingRequest {
+    sessionId: string;
+    sender: 'visitor' | 'operator';
+    isTyping?: boolean;
+}
+interface ReadRequest {
+    sessionId: string;
+    messageIds: string[];
+    status?: MessageStatus;
+}
+interface ReadResponse {
+    updated: number;
+}
+interface PresenceResponse {
+    online: boolean;
+    operators?: Array<{
+        id: string;
+        name: string;
+        avatar?: string;
+    }>;
+    aiEnabled: boolean;
+    aiActiveAfter?: number;
+}
+
+declare class PocketPing {
+    private storage;
+    private bridges;
+    private config;
+    private wss;
+    private sessionSockets;
+    private operatorOnline;
+    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 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>;
+    sendOperatorMessage(sessionId: string, content: string): Promise<Message>;
+    setOperatorOnline(online: boolean): void;
+    private notifyBridges;
+    private notifyBridgesRead;
+    addBridge(bridge: Bridge): void;
+    private generateId;
+    getStorage(): Storage;
+}
+
+/**
+ * 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;
+    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>;
+    cleanupOldSessions(olderThan: Date): Promise<number>;
+}
+
+export { type AIProvider, type Bridge, type ConnectRequest, type ConnectResponse, MemoryStorage, type Message, PocketPing, type PocketPingConfig, type PresenceResponse, type SendMessageRequest, type SendMessageResponse, type Session, type Storage };