priori-chat-sdk 1.0.0

package/README.md

@@ -0,0 +1,254 @@
+# Priori Chat SDK
+
+A TypeScript SDK for building real-time chat applications with the Priori Chat API.
+
+## Installation
+
+```bash
+npm install priori-chat-sdk
+```
+
+## Quick Start
+
+```typescript
+import { PrioriChat } from 'priori-chat-sdk';
+
+const client = new PrioriChat("your-api-key");
+
+// Start a conversation
+const { conversation, initialData } = await client.conversation(
+  { user_id: "user-123", bot_id: "12345678-1234-1234-1234-123456789012" },
+  {
+    onNewMessage: (message) => {
+      console.log(`${message.from_bot ? 'Bot' : 'User'}: ${message.text}`);
+      if (message.attached_media) {
+        console.log(`  📎 Image: ${message.attached_media.url}`);
+      }
+    }
+  }
+);
+
+// Print initial message history
+console.log(`Loaded ${initialData.messages.length} previous messages`);
+initialData.messages.forEach(msg => {
+  console.log(`${msg.from_bot ? 'Bot' : 'User'}: ${msg.text}`);
+});
+
+// Send a message
+await conversation.sendMessage("Hello!");
+
+// Clean up when done
+conversation.disconnect();
+```
+
+## Core Concepts
+
+### Conversation Identification
+
+Conversations can be identified in two ways:
+
+1. **By user and bot pair** - There can only be one conversation between a specific `user_id` and `bot_id`. If a conversation already exists, it will be retrieved; otherwise, a new one will be created.
+
+```typescript
+const options = {
+  user_id: "user-123",
+  bot_id: "12345678-1234-1234-1234-123456789012"
+};
+```
+
+2. **By conversation ID** - If you already have a conversation ID, you can connect directly to it.
+
+```typescript
+const options = {
+  conversation_id: "87654321-4321-4321-4321-210987654321"
+};
+```
+
+### Creating Conversations
+
+You can also create conversations explicitly before starting real-time messaging:
+
+```typescript
+const result = await client.createConversation({
+  bot_id: "12345678-1234-1234-1234-123456789012",
+  user_id: "user-123",
+  create_user_if_not_exists: true
+});
+
+console.log(`Created conversation: ${result.conversation.id}`);
+```
+
+## Real-time Messaging
+
+### Callbacks and Initial Data
+
+When starting a conversation, you receive both the conversation instance and initial data containing the message history:
+
+```typescript
+const { conversation, initialData } = await client.conversation(options, {
+  onInitialData: (data) => {
+    console.log(`Loaded ${data.messages.length} previous messages`);
+    // Display message history in your UI
+    data.messages.forEach(msg => {
+      console.log(`${msg.from_bot ? 'Bot' : 'User'}: ${msg.text}`);
+    });
+  },
+  
+  onNewMessage: (message) => {
+    // Handle new messages in real-time
+    console.log(`${message.from_bot ? 'Bot' : 'User'}: ${message.text}`);
+    if (message.attached_media) {
+      console.log(`  📎 Image: ${message.attached_media.url}`);
+    }
+  },
+  
+  onError: (error) => {
+    console.error('Chat error:', error.message);
+    // Show error message to user
+  }
+});
+
+// The initialData contains the same message history that onInitialData receives
+console.log(`Message history: ${initialData.messages.length} messages`);
+```
+
+### Sending Messages
+
+```typescript
+// Send text message
+await conversation.sendMessage("How can you help me?");
+
+// Send message with image
+await conversation.sendMessage("Here's a screenshot of the issue", {
+  url: "https://example.com/screenshot.png"
+});
+```
+
+### Handling Media
+
+Both users and bots can send and receive images:
+
+```typescript
+const { conversation } = await client.conversation(options, {
+  onNewMessage: (message) => {
+    console.log(`${message.from_bot ? 'Bot' : 'User'}: ${message.text}`);
+    if (message.attached_media) {
+      console.log(`  📎 Image: ${message.attached_media.url}`);
+      // Display image in your UI
+    }
+  }
+});
+
+// User sends an image
+// In a real app, you'd get this URL from file upload
+const imageUrl = "https://example.com/user-uploaded-image.jpg"; // Your upload logic
+await conversation.sendMessage("Check out this image!", { url: imageUrl });
+```
+
+## Complete Example
+
+Here's a complete implementation demonstrating the SDK usage:
+
+```typescript
+import { PrioriChat, Conversation, Message } from 'priori-chat-sdk';
+
+class ChatApplication {
+  private conversation: Conversation | null = null;
+  private messages: Message[] = [];
+
+  async initialize() {
+    const client = new PrioriChat("your-api-key");
+    
+    const { conversation, initialData } = await client.conversation(
+      { user_id: "user-123", bot_id: "12345678-1234-1234-1234-123456789012" },
+      {
+        onInitialData: (data) => {
+          this.messages = data.messages;
+          this.renderMessages();
+        },
+        onNewMessage: (message) => {
+          this.messages.push(message);
+          this.renderMessage(message);
+        },
+        onError: (error) => {
+          console.error('Chat error:', error);
+          // Show error notification to user
+        }
+      }
+    );
+
+    this.conversation = conversation;
+    console.log(`Connected to conversation: ${conversation.id}`);
+  }
+
+  async sendMessage(text: string) {
+    if (!this.conversation) return;
+    await this.conversation.sendMessage(text);
+  }
+
+  async sendImage(file: File) {
+    if (!this.conversation) return;
+
+    // Upload file and get URL (implement your upload logic)
+    const imageUrl = await this.uploadFile(file);
+    await this.conversation.sendMessage("Shared an image", { url: imageUrl });
+  }
+
+  private renderMessages() {
+    this.messages.forEach(msg => this.renderMessage(msg));
+  }
+
+  private renderMessage(message: Message) {
+    // Implement your UI rendering logic
+    const sender = message.from_bot ? 'Bot' : 'User';
+    console.log(`${sender}: ${message.text}`);
+    
+    if (message.attached_media) {
+      console.log(`  📎 Image: ${message.attached_media.url}`);
+      // Display image in your UI
+    }
+  }
+
+  private async uploadFile(file: File): Promise<string> {
+    // Implement your file upload logic
+    // Return the URL of the uploaded file
+    return "https://your-storage.com/uploaded-file.jpg";
+  }
+
+  disconnect() {
+    this.conversation?.disconnect();
+  }
+}
+
+// Usage
+const chat = new ChatApplication();
+await chat.initialize();
+
+// Send messages
+await chat.sendMessage("Hello!");
+
+// Handle file uploads
+// chat.sendImage(selectedFile);
+
+// Clean up when done
+chat.disconnect();
+```
+
+For a complete working example, see [`examples/interactive-chat.ts`](./examples/interactive-chat.ts).
+
+## API Reference
+
+For detailed API documentation, see the generated TypeDoc documentation.
+
+### Key Classes and Types
+
+- `PrioriChat` - Main SDK client
+- `Conversation` - Real-time conversation instance
+- `ConversationOptions` - Configuration for conversation identification
+- `ConversationCallbacks` - Event handlers for real-time updates
+- `Message` - Message structure with text and optional media
+- `AttachedMedia` - Media attachment with URL
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type safety for all operations.

package/dist/index.d.mts

@@ -0,0 +1,460 @@
+type Content = {
+    /**
+     * Unique identifier for the content
+     */
+    content_id: string;
+    /**
+     * URL to the attached media
+     */
+    url: string;
+};
+type Conversation$1 = {
+    /**
+     * ID of the bot associated with this conversation
+     */
+    bot_id: string;
+    /**
+     * The unique ID of the conversation
+     */
+    id: string;
+    /**
+     * Messages in the conversation
+     */
+    messages: Array<Message$1>;
+    /**
+     * ID of the user associated with this conversation
+     */
+    user_id?: string | null;
+};
+type ConversationHeader = {
+    /**
+     * ID of the bot associated with this conversation
+     */
+    bot_id: string;
+    /**
+     * Unique identifier for the conversation
+     */
+    id: string;
+    /**
+     * ID of the bot associated with this conversation
+     */
+    user_id: string;
+};
+type CreateConversationResponse = {
+    conversation: Conversation$1;
+};
+type GetConversationResponse = {
+    /**
+     * ID of the bot associated with this conversation
+     */
+    bot_id: string;
+    /**
+     * Messages in the conversation
+     */
+    messages: Array<Message$1>;
+    /**
+     * ID of the user associated with this conversation
+     */
+    user_id: string;
+};
+type ListConversationsResponse = {
+    /**
+     * List of conversations
+     */
+    conversations: Array<ConversationHeader>;
+};
+type Message$1 = {
+    attached_media?: Content | null;
+    /**
+     * Whether this message is from a bot (true) or human (false)
+     */
+    from_bot: boolean;
+    /**
+     * Unique identifier for the content
+     */
+    id?: string | null;
+    /**
+     * The text content of the message
+     */
+    text: string;
+};
+
+/**
+ * Options for listing conversations
+ */
+interface ListConversationsOptions {
+    bot_id?: string;
+    user_id?: string;
+}
+/**
+ * Options for getting a conversation by ID
+ */
+interface GetConversationOptions {
+    id: string;
+}
+
+/**
+ * Represents media content attached to a message
+ * @example
+ * ```ts
+ * const media: AttachedMedia = {
+ *   url: "https://example.com/image.jpg"
+ * };
+ *
+ * // Use with message
+ * await conversation.sendMessage("Check out this image!", media);
+ * ```
+ */
+interface AttachedMedia {
+    url: string;
+}
+/**
+ * Represents a message in the conversation
+ * @example
+ * ```ts
+ * const userMessage: Message = {
+ *   text: "Hey there!",
+ *   from_bot: false,
+ * };
+ *
+ * const botMessageWithMedia: Message = {
+ *   text: "Just sent you a pic (;",
+ *   from_bot: true,
+ *   attached_media: { url: "https://example.com/image.jpg" },
+ *   timestamp: new Date("Sat Jul 05 2025 16:20:05")
+ * };
+ * ```
+ */
+interface Message {
+    id?: string;
+    text: string;
+    from_bot: boolean;
+    attached_media?: AttachedMedia;
+    timestamp?: Date;
+}
+/**
+ * Configuration for retrieving a conversation by its unique ID
+ * @example
+ * ```ts
+ * const config: ConversationWithId = {
+ *   conversation_id: "87654321-4321-4321-4321-210987654321"
+ * };
+ *
+ * const { conversation } = await client.conversation(config);
+ * ```
+ */
+interface ConversationWithId {
+    conversation_id: string;
+    pollingInterval?: number;
+}
+/**
+ * Configuration for retrieving or creating a conversation by user and bot pair.
+ * Note: There can only be one conversation between a specific user_id and bot_id.
+ * If a conversation already exists, it will be retrieved; otherwise, a new one will be created.
+ * @example
+ * ```ts
+ * const config: ConversationWithUserBot = {
+ *   user_id: "user-123",
+ *   bot_id: "12345678-1234-1234-1234-123456789012"
+ * };
+ *
+ * // This will either find the existing conversation or create a new one
+ * const { conversation } = await client.conversation(config);
+ * ```
+ */
+interface ConversationWithUserBot {
+    user_id: string;
+    bot_id: string;
+    pollingInterval?: number;
+}
+/**
+ * Union type for conversation configuration options.
+ * You can either specify a conversation_id directly, or provide user_id + bot_id
+ * to find/create the unique conversation between that user and bot.
+ * @example
+ * ```ts
+ * // Option 1: Use existing conversation ID
+ * const byId: ConversationOptions = {
+ *   conversation_id: "87654321-4321-4321-4321-210987654321"
+ * };
+ *
+ * // Option 2: Use user + bot pair (will find existing or create new)
+ * const byUserBot: ConversationOptions = {
+ *   user_id: "user-123",
+ *   bot_id: "12345678-1234-1234-1234-123456789012"
+ * };
+ * ```
+ */
+type ConversationOptions = ConversationWithId | ConversationWithUserBot;
+/**
+ * Callback functions for handling conversation events
+ * @example
+ * ```ts
+ * const callbacks: ConversationCallbacks = {
+ *   onInitialData: (data) => {
+ *     console.log(`Loaded ${data.messages.length} previous messages`);
+ *     data.messages.forEach(msg => {
+ *       console.log(`${msg.from_bot ? 'Bot' : 'User'}: ${msg.text}`);
+ *     });
+ *   },
+ *   onNewMessage: (message) => {
+ *     if (message.from_bot) {
+ *       console.log(`Bot: ${message.text}`);
+ *     } else {
+ *       console.log(`User: ${message.text}`);
+ *     }
+ *   },
+ *   onError: (error) => {
+ *     console.error('Conversation error:', error.message);
+ *   }
+ * };
+ *
+ * const { conversation } = await client.conversation(options, callbacks);
+ * ```
+ */
+interface ConversationCallbacks {
+    onInitialData?: (data: GetConversationResponse) => void;
+    onNewMessage?: (message: Message) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Represents a conversation between a user and a bot.
+ * Provides real-time message handling through it's methods and callbacks
+ */
+declare class Conversation {
+    private client;
+    private conversationId;
+    private pollingInterval;
+    private pollingTimer?;
+    private lastKnownMessageCount;
+    private callbacks;
+    private isInitialized;
+    private constructor();
+    /**
+     * Creates a new conversation instance and initializes it.
+     * @param client - The PrioriChat client instance
+     * @param options - Configuration options for the conversation
+     * @param callbacks - Event callbacks for handling conversation events
+     * @returns Promise resolving to the conversation instance and initial data containing message history
+     * @example
+     * ```ts
+     * const client = new PrioriChat("your-api-key");
+     *
+     * const { conversation, initialData } = await Conversation.create(
+     *   client,
+     *   { user_id: "user-123", bot_id: "12345678-1234-1234-1234-123456789012" },
+     *   {
+     *     onNewMessage: (message) => {
+     *       console.log(`${message.from_bot ? 'Bot' : 'User'}: ${message.text}`);
+     *     },
+     *     onError: (error) => {
+     *       console.error("Error:", error);
+     *     }
+     *   }
+     * );
+     *
+     * // Print message history
+     * initialData.messages.forEach(msg => {
+     *   console.log(`${msg.from_bot ? 'Bot' : 'User'}: ${msg.text}`);
+     * });
+     * ```
+     */
+    static create(client: PrioriChat, options: ConversationOptions, callbacks?: ConversationCallbacks): Promise<{
+        conversation: Conversation;
+        initialData: GetConversationResponse;
+    }>;
+    private initialize;
+    private startPolling;
+    /**
+     * Sends a message to the conversation
+     * @param text - The text content of the message
+     * @param attachedMedia - Optional attached media content
+     * @returns Promise that resolves when message is sent
+     * @example
+     * ```ts
+     * // Send a simple text message
+     * await conversation.sendMessage("Hello, how can you help me?");
+     *
+     * // Send a message with media attachment
+     * await conversation.sendMessage("Here's an image", {
+     *   url: "https://example.com/image.jpg"
+     * });
+     *
+     * // Continue the conversation by sending more messages
+     * // The onNewMessage callback will handle bot responses
+     * ```
+     */
+    sendMessage(text: string, attachedMedia?: AttachedMedia): Promise<void>;
+    /**
+     * Stops polling for new messages and cleans up resources.
+     * Call this method when you're done with the conversation to prevent memory leaks.
+     * @example
+     * ```ts
+     * // Always disconnect when done
+     * conversation.disconnect();
+     *
+     * // Or use in React useEffect cleanup
+     * useEffect(() => {
+     *   const setupConversation = async () => {
+     *     const { conversation } = await client.conversation(...);
+     *     setConversation(conversation);
+     *   };
+     *
+     *   setupConversation();
+     *
+     *   return () => {
+     *     conversation?.disconnect();
+     *   };
+     * }, []);
+     * ```
+     */
+    disconnect(): void;
+    /**
+     * Gets the current conversation ID.
+     * @returns The conversation ID string
+     * @example
+     * ```ts
+     * console.log(`Current conversation: ${conversation.id}`);
+     * // Output: Current conversation: 87654321-4321-4321-4321-210987654321
+     * ```
+     */
+    get id(): string;
+}
+
+declare class ApiError extends Error {
+    name: string;
+    status?: number;
+    method?: string;
+    url?: string;
+    payload?: unknown;
+    constructor({ message, status, method, url, payload, }: {
+        message: string;
+        status?: number;
+        method?: string;
+        url?: string;
+        payload?: unknown;
+    });
+}
+/**
+ * Options for creating a new conversation
+ */
+interface CreateConversationOptions {
+    bot_id: string;
+    user_id: string;
+    create_user_if_not_exists?: boolean;
+    with_messages?: Array<{
+        text: string;
+        from_bot: boolean;
+        id?: string;
+        attached_media?: AttachedMedia;
+    }>;
+}
+declare class PrioriChat {
+    private client;
+    private apiToken;
+    constructor(api_token: string, baseURL?: string);
+    private setupErrorInterceptor;
+    /**
+     * Creates a new conversation between a user and bot
+     * @param options - The conversation creation options
+     * @param options.bot_id - ID of the bot to associate with this conversation
+     * @param options.user_id - ID of the user to associate with this conversation
+     * @param options.create_user_if_not_exists - Whether to create the user if they don't exist (defaults to true)
+     * @param options.with_messages - Optional list of initial messages for the conversation
+     * @returns Promise resolving to the created conversation
+     * @example
+     * ```ts
+     * const client = new PrioriChat("your-api-key");
+     *
+     * const result = await client.createConversation({
+     *   bot_id: "12345678-1234-1234-1234-123456789012",
+     *   user_id: "user-123",
+     *   create_user_if_not_exists: true
+     * });
+     *
+     * console.log(`Created conversation: ${result.conversation.id}`);
+     * ```
+     */
+    createConversation(options: CreateConversationOptions): Promise<CreateConversationResponse>;
+    /**
+     * Lists conversations with optional filtering
+     * @param options - Optional filtering options
+     * @param options.bot_id - Filter conversations by bot ID
+     * @param options.user_id - Filter conversations by user ID
+     * @returns Promise resolving to list of conversations
+     * @example
+     * ```ts
+     * const client = new PrioriChat("your-api-key");
+     *
+     * // List all conversations
+     * const allConversations = await client.listConversations();
+     *
+     * // List conversations for a specific user and bot
+     * const userConversations = await client.listConversations({
+     *   user_id: "user-123",
+     *   bot_id: "12345678-1234-1234-1234-123456789012"
+     * });
+     * ```
+     */
+    listConversations(options?: ListConversationsOptions): Promise<ListConversationsResponse>;
+    /**
+     * Retrieves a specific conversation by ID
+     * @param options - The conversation retrieval options
+     * @param options.id - The ID of the conversation to retrieve
+     * @returns Promise resolving to the conversation details
+     * @example
+     * ```ts
+     * const client = new PrioriChat("your-api-key");
+     *
+     * const conversation = await client.getConversation({
+     *   id: "87654321-4321-4321-4321-210987654321"
+     * });
+     *
+     * console.log(`Found ${conversation.messages.length} messages`);
+     * ```
+     */
+    getConversation(options: GetConversationOptions): Promise<GetConversationResponse>;
+    /**
+     * Creates a new Conversation instance for real-time messaging
+     * @param options - Conversation initialization options (conversation_id OR user_id + bot_id)
+     * @param callbacks - Event callbacks for handling messages and errors
+     * @returns Promise resolving to conversation instance and initial data
+     * @example
+     * ```ts
+     * const client = new PrioriChat("your-api-key");
+     *
+     * const { conversation, initialData } = await client.conversation(
+     *   { user_id: "user-123", bot_id: "12345678-1234-1234-1234-123456789012" },
+     *   {
+     *     onNewMessage: (message) => {
+     *       if (message.from_bot) {
+     *         console.log(`Bot: ${message.text}`);
+     *       }
+     *     },
+     *     onError: (error) => {
+     *       console.error("Conversation error:", error);
+     *     }
+     *   }
+     * );
+     *
+     * // Print initial message history
+     * console.log(`Loaded ${initialData.messages.length} previous messages`);
+     * initialData.messages.forEach(msg => {
+     *   const sender = msg.from_bot ? "Bot" : "User";
+     *   console.log(`${sender}: ${msg.text}`);
+     * });
+     *
+     * // Send a message to start/continue the conversation
+     * await conversation.sendMessage("Hello!");
+     *
+     * // Continue the conversation by sending more messages
+     * // The onNewMessage callback will handle incoming bot responses
+     * ```
+     */
+    conversation(options: ConversationOptions, callbacks?: ConversationCallbacks): Promise<{
+        conversation: Conversation;
+        initialData: GetConversationResponse;
+    }>;
+}
+
+export { ApiError, type AttachedMedia, Conversation, type ConversationCallbacks, type ConversationOptions, type ConversationWithId, type ConversationWithUserBot, type CreateConversationOptions, type CreateConversationResponse, type GetConversationOptions, type GetConversationResponse, type ListConversationsOptions, type ListConversationsResponse, type Message, PrioriChat };