hai-api 1.1.2

package/README.md

@@ -0,0 +1,14 @@
+# hai-api (Node.js SDK)
+
+The official Node.js SDK for Hussain's Private AI Bridge (hAI). High-performance, type-safe integration for multi-AI orchestration.
+
+## Installation
+
+```bash
+npm install hai-api
+```
+
+## Features
+- Native TypeScript support.
+- Stream-ready API responses.
+- Easy integration with hAI Multi-AI Server.

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+export interface HSeekResponse {
+    text: string;
+    thinking_text: string;
+    search_text: string;
+    session_id: string | null;
+    parent_message_id: string | null;
+    latency_ms: number | null;
+    is_done: boolean;
+    /** Export the response as a plain object */
+    toDict(): Record<string, unknown>;
+    readonly process_text: string;
+}
+export interface ChatOptions {
+    /** Used to identify the conversation thread. SDK auto-manages session IDs for you. */
+    sessionId?: string;
+    /** Enable chain-of-thought reasoning before answering. */
+    thinking?: boolean;
+    /** Enable real-time web search to ground the response. */
+    search?: boolean;
+    /** Raw backend chat session ID (for manual persistence). Overrides sessionId. */
+    chatSessionId?: string;
+    /** Raw backend parent message ID (for manual persistence). */
+    parentMessageId?: string;
+    /** Set a persistent system-level personality or instruction for the AI. */
+    system?: string;
+    /** Control response creativity: 0.0 = precise/deterministic, 1.0 = creative/random. */
+    temperature?: number;
+    /** Limit the maximum number of tokens in the response. */
+    maxTokens?: number;
+    /** Force the response to be a valid JSON object. */
+    jsonMode?: boolean;
+    /** Auto-translate all responses to this language (e.g., "Arabic", "French"). */
+    translate?: string;
+    /** Put the AI in expert senior programmer mode. */
+    codeMode?: boolean;
+    /** Ask the AI to internally verify its answer before responding. */
+    verify?: boolean;
+    /** Append a 3-bullet summary at the end of every response. */
+    summarize?: boolean;
+    /** Whether to include the AI's internal thought process in the text response (when thinking=true). */
+    includeThought?: boolean;
+    /** URL of an image to analyze alongside the prompt (Vision). */
+    image?: string;
+    /** URL of a YouTube video. SDK will fetch the transcript and analyze it. */
+    youtube?: string;
+    /** Number of past message exchanges to include for context. 0 = no history, -1 = all. Default: 10. */
+    memoryDepth?: number;
+    /** Number of times to automatically retry on network failure. Default: 3. */
+    retries?: number;
+    /** Model to use (e.g., 'deepseek', 'gemini-nano-banana'). */
+    model?: string;
+    /** Callback function called once streaming is complete. */
+    onDone?: (response: HSeekResponse) => void;
+}
+interface SessionData {
+    chatSessionId: string | null;
+    parentMessageId: string | null;
+    history: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+/**
+ * HSeekClient — The official client for the hAI private AI.
+ *
+ * @example
+ * ```typescript
+ * const ai = new HSeekClient();
+ * const res = await ai.chat("Hello!", { sessionId: "user_1", thinking: true });
+ * console.log(res.text);
+ * ```
+ */
+export declare class HSeekClient {
+    private apiKey;
+    private baseUrl;
+    private memory;
+    constructor(apiKey?: string, baseUrl?: string);
+    private buildPayload;
+    private createResponse;
+    /**
+     * Stream a response in real-time, yielding chunks as they arrive.
+     */
+    streamChat(prompt: string, options?: ChatOptions): AsyncGenerator<HSeekResponse, void, unknown>;
+    /**
+     * Send a message and get the full response at once (non-streaming).
+     */
+    chat(prompt: string, options?: ChatOptions): Promise<HSeekResponse>;
+    /**
+     * Export the full conversation history for a session.
+     */
+    exportHistory(sessionId: string): SessionData;
+    /**
+     * Clear the conversation memory for a session.
+     */
+    clearHistory(sessionId: string): void;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,330 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HSeekClient = void 0;
+const dotenv = __importStar(require("dotenv"));
+dotenv.config();
+// ========================
+// Internal Memory Store
+// ========================
+class MemoryStore {
+    sessions = new Map();
+    getIds(sessionId) {
+        if (!sessionId)
+            return { chatSessionId: null, parentMessageId: null };
+        const s = this.sessions.get(sessionId);
+        return { chatSessionId: s?.chatSessionId ?? null, parentMessageId: s?.parentMessageId ?? null };
+    }
+    getHistory(sessionId, depth) {
+        const history = this.sessions.get(sessionId)?.history ?? [];
+        if (depth === 0)
+            return [];
+        if (depth < 0)
+            return history;
+        return history.slice(-(depth * 2));
+    }
+    addToHistory(sessionId, role, content) {
+        if (!this.sessions.has(sessionId)) {
+            this.sessions.set(sessionId, { chatSessionId: null, parentMessageId: null, history: [] });
+        }
+        this.sessions.get(sessionId).history.push({ role, content });
+    }
+    saveIds(sessionId, chatSessionId, parentMessageId) {
+        if (!sessionId || !chatSessionId || !parentMessageId)
+            return;
+        if (!this.sessions.has(sessionId)) {
+            this.sessions.set(sessionId, { chatSessionId: null, parentMessageId: null, history: [] });
+        }
+        const s = this.sessions.get(sessionId);
+        s.chatSessionId = chatSessionId;
+        s.parentMessageId = parentMessageId;
+    }
+    export(sessionId) {
+        return this.sessions.get(sessionId) ?? { chatSessionId: null, parentMessageId: null, history: [] };
+    }
+    clear(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+}
+// ========================
+// YouTube Helpers
+// ========================
+function extractYouTubeId(url) {
+    const match = url.match(/(?:v=|youtu\.be\/|\/v\/|\/embed\/|\/shorts\/)([0-9A-Za-z_-]{11})/);
+    return match ? match[1] : null;
+}
+async function fetchYouTubeTranscript(videoId) {
+    // Fetches transcript via a free public API
+    const apiUrl = `https://yt-transcript-api.vercel.app/api/transcript?videoId=${videoId}`;
+    try {
+        const res = await fetch(apiUrl);
+        if (!res.ok)
+            throw new Error(`Transcript API returned ${res.status}`);
+        const data = await res.json();
+        return data.map((d) => d.text).join(' ').substring(0, 15000);
+    }
+    catch (e) {
+        throw new Error(`Failed to fetch YouTube transcript for ${videoId}: ${e}`);
+    }
+}
+// ========================
+// Main HSeekClient
+// ========================
+/**
+ * HSeekClient — The official client for the hAI private AI.
+ *
+ * @example
+ * ```typescript
+ * const ai = new HSeekClient();
+ * const res = await ai.chat("Hello!", { sessionId: "user_1", thinking: true });
+ * console.log(res.text);
+ * ```
+ */
+class HSeekClient {
+    apiKey;
+    baseUrl;
+    memory;
+    constructor(apiKey, baseUrl = "https://ai.hussain.ink") {
+        this.apiKey = apiKey || process.env.MY_SECRET_API_KEY || '';
+        if (!this.apiKey) {
+            throw new Error("API Key is missing. Pass it directly or set MY_SECRET_API_KEY in .env");
+        }
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.memory = new MemoryStore();
+    }
+    buildPayload(prompt, options) {
+        const { sessionId, thinking = false, search = false, chatSessionId, parentMessageId, system, temperature, maxTokens, jsonMode, translate, codeMode, verify, summarize, includeThought, image, memoryDepth = 10, } = options;
+        // Build messages array
+        const messages = [];
+        if (sessionId && memoryDepth !== 0) {
+            messages.push(...this.memory.getHistory(sessionId, memoryDepth));
+        }
+        const userContent = image
+            ? [{ type: "image_url", image_url: { url: image } }, { type: "text", text: prompt }]
+            : prompt;
+        messages.push({ role: "user", content: userContent });
+        const payload = {
+            messages,
+            stream: true,
+            thinking,
+            search,
+        };
+        // Optional feature flags
+        if (system)
+            payload.system = system;
+        if (temperature !== undefined)
+            payload.temperature = temperature;
+        if (maxTokens !== undefined)
+            payload.max_tokens = maxTokens;
+        if (jsonMode)
+            payload.json_mode = true;
+        if (translate)
+            payload.translate = translate;
+        if (codeMode)
+            payload.code_mode = true;
+        if (verify)
+            payload.verify = true;
+        if (summarize)
+            payload.summarize = true;
+        if (includeThought)
+            payload.include_thought = true;
+        // Session management
+        if (chatSessionId) {
+            payload.chat_session_id = chatSessionId;
+        }
+        else if (sessionId) {
+            const ids = this.memory.getIds(sessionId);
+            if (ids.chatSessionId)
+                payload.chat_session_id = ids.chatSessionId;
+            if (ids.parentMessageId)
+                payload.parent_message_id = ids.parentMessageId;
+        }
+        if (parentMessageId)
+            payload.parent_message_id = parentMessageId;
+        if (options.model)
+            payload.model = options.model;
+        return payload;
+    }
+    createResponse() {
+        const r = {
+            text: "",
+            thinking_text: "",
+            search_text: "",
+            session_id: null,
+            parent_message_id: null,
+            latency_ms: null,
+            is_done: false,
+            toDict() {
+                return {
+                    text: this.text,
+                    thinking_text: this.thinking_text,
+                    search_text: this.search_text,
+                    session_id: this.session_id,
+                    parent_message_id: this.parent_message_id,
+                    latency_ms: this.latency_ms,
+                    is_done: this.is_done
+                };
+            },
+            get process_text() {
+                let p = this.search_text;
+                if (this.thinking_text) {
+                    if (p && !p.endsWith("\n"))
+                        p += "\n";
+                    p += this.thinking_text;
+                }
+                return p;
+            }
+        };
+        return r;
+    }
+    /**
+     * Stream a response in real-time, yielding chunks as they arrive.
+     */
+    async *streamChat(prompt, options = {}) {
+        const { sessionId, youtube, retries = 3, onDone } = options;
+        // Handle YouTube
+        let actualPrompt = prompt;
+        if (youtube) {
+            const videoId = extractYouTubeId(youtube);
+            if (!videoId)
+                throw new Error(`Could not extract YouTube video ID from: ${youtube}`);
+            const transcript = await fetchYouTubeTranscript(videoId);
+            actualPrompt = `[YOUTUBE VIDEO TRANSCRIPT]:\n${transcript}\n\n[USER REQUEST]:\n${prompt}`;
+        }
+        const payload = this.buildPayload(actualPrompt, options);
+        const currentResponse = this.createResponse();
+        let attempt = 0;
+        while (attempt <= retries) {
+            try {
+                const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify(payload)
+                });
+                if (!response.ok)
+                    throw new Error(`HSeek API Error: ${response.status}`);
+                if (!response.body)
+                    throw new Error("Response body is null");
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split('\n');
+                    buffer = lines.pop() || '';
+                    for (const line of lines) {
+                        if (!line.startsWith('data: '))
+                            continue;
+                        const dataStr = line.substring(6).trim();
+                        if (dataStr === '[DONE]') {
+                            currentResponse.is_done = true;
+                            if (sessionId) {
+                                this.memory.addToHistory(sessionId, 'user', actualPrompt);
+                                this.memory.addToHistory(sessionId, 'assistant', currentResponse.text);
+                            }
+                            if (onDone)
+                                onDone(currentResponse);
+                            yield currentResponse;
+                            return;
+                        }
+                        try {
+                            const dataJson = JSON.parse(dataStr);
+                            if (dataJson.choices?.[0]?.delta) {
+                                const delta = dataJson.choices[0].delta;
+                                if (delta.content) {
+                                    currentResponse.text += delta.content;
+                                    yield currentResponse;
+                                }
+                                if (delta.reasoning_content) {
+                                    currentResponse.thinking_text += delta.reasoning_content;
+                                    yield currentResponse;
+                                }
+                                if (delta.search_content) {
+                                    currentResponse.search_text += delta.search_content;
+                                    yield currentResponse;
+                                }
+                            }
+                            else if (dataJson.object === 'chat.completion.meta') {
+                                currentResponse.parent_message_id = dataJson.message_id;
+                                currentResponse.session_id = dataJson.chat_session_id;
+                                currentResponse.latency_ms = dataJson.latency_ms ?? null;
+                                this.memory.saveIds(sessionId, currentResponse.session_id, currentResponse.parent_message_id);
+                            }
+                        }
+                        catch (_) { /* ignore json parse errors */ }
+                    }
+                }
+                break; // Success
+            }
+            catch (e) {
+                attempt++;
+                if (attempt > retries)
+                    throw new Error(`HSeek failed after ${retries} retries. Last error: ${e}`);
+                await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
+            }
+        }
+    }
+    /**
+     * Send a message and get the full response at once (non-streaming).
+     */
+    async chat(prompt, options = {}) {
+        let finalResponse = null;
+        for await (const chunk of this.streamChat(prompt, options)) {
+            finalResponse = chunk;
+        }
+        if (!finalResponse)
+            throw new Error("HSeek API returned an empty response.");
+        return finalResponse;
+    }
+    /**
+     * Export the full conversation history for a session.
+     */
+    exportHistory(sessionId) {
+        return this.memory.export(sessionId);
+    }
+    /**
+     * Clear the conversation memory for a session.
+     */
+    clearHistory(sessionId) {
+        this.memory.clear(sessionId);
+    }
+}
+exports.HSeekClient = HSeekClient;

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "hai-api",
+  "version": "1.1.2",
+  "description": "The official Node.js SDK for hAI Private AI.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Hussain Alkhatib",
+  "license": "MIT",
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "hseek-api": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "typescript": "^5.4.5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,370 @@
+import * as dotenv from 'dotenv';
+
+dotenv.config();
+
+// ========================
+// Types & Interfaces
+// ========================
+
+export interface HSeekResponse {
+    text: string;
+    thinking_text: string;
+    search_text: string;
+    session_id: string | null;
+    parent_message_id: string | null;
+    latency_ms: number | null;
+    is_done: boolean;
+    /** Export the response as a plain object */
+    toDict(): Record<string, unknown>;
+    readonly process_text: string;
+}
+
+export interface ChatOptions {
+    /** Used to identify the conversation thread. SDK auto-manages session IDs for you. */
+    sessionId?: string;
+    /** Enable chain-of-thought reasoning before answering. */
+    thinking?: boolean;
+    /** Enable real-time web search to ground the response. */
+    search?: boolean;
+    /** Raw backend chat session ID (for manual persistence). Overrides sessionId. */
+    chatSessionId?: string;
+    /** Raw backend parent message ID (for manual persistence). */
+    parentMessageId?: string;
+    /** Set a persistent system-level personality or instruction for the AI. */
+    system?: string;
+    /** Control response creativity: 0.0 = precise/deterministic, 1.0 = creative/random. */
+    temperature?: number;
+    /** Limit the maximum number of tokens in the response. */
+    maxTokens?: number;
+    /** Force the response to be a valid JSON object. */
+    jsonMode?: boolean;
+    /** Auto-translate all responses to this language (e.g., "Arabic", "French"). */
+    translate?: string;
+    /** Put the AI in expert senior programmer mode. */
+    codeMode?: boolean;
+    /** Ask the AI to internally verify its answer before responding. */
+    verify?: boolean;
+    /** Append a 3-bullet summary at the end of every response. */
+    summarize?: boolean;
+    /** Whether to include the AI's internal thought process in the text response (when thinking=true). */
+    includeThought?: boolean;
+    /** URL of an image to analyze alongside the prompt (Vision). */
+    image?: string;
+    /** URL of a YouTube video. SDK will fetch the transcript and analyze it. */
+    youtube?: string;
+    /** Number of past message exchanges to include for context. 0 = no history, -1 = all. Default: 10. */
+    memoryDepth?: number;
+    /** Number of times to automatically retry on network failure. Default: 3. */
+    retries?: number;
+    /** Model to use (e.g., 'deepseek', 'gemini-nano-banana'). */
+    model?: string;
+    /** Callback function called once streaming is complete. */
+    onDone?: (response: HSeekResponse) => void;
+}
+
+interface SessionData {
+    chatSessionId: string | null;
+    parentMessageId: string | null;
+    history: Array<{ role: string; content: string }>;
+}
+
+// ========================
+// Internal Memory Store
+// ========================
+class MemoryStore {
+    private sessions: Map<string, SessionData> = new Map();
+
+    getIds(sessionId?: string): { chatSessionId: string | null; parentMessageId: string | null } {
+        if (!sessionId) return { chatSessionId: null, parentMessageId: null };
+        const s = this.sessions.get(sessionId);
+        return { chatSessionId: s?.chatSessionId ?? null, parentMessageId: s?.parentMessageId ?? null };
+    }
+
+    getHistory(sessionId: string, depth: number): Array<{ role: string; content: string }> {
+        const history = this.sessions.get(sessionId)?.history ?? [];
+        if (depth === 0) return [];
+        if (depth < 0) return history;
+        return history.slice(-(depth * 2));
+    }
+
+    addToHistory(sessionId: string, role: string, content: string): void {
+        if (!this.sessions.has(sessionId)) {
+            this.sessions.set(sessionId, { chatSessionId: null, parentMessageId: null, history: [] });
+        }
+        this.sessions.get(sessionId)!.history.push({ role, content });
+    }
+
+    saveIds(sessionId: string | undefined, chatSessionId: string | null, parentMessageId: string | null): void {
+        if (!sessionId || !chatSessionId || !parentMessageId) return;
+        if (!this.sessions.has(sessionId)) {
+            this.sessions.set(sessionId, { chatSessionId: null, parentMessageId: null, history: [] });
+        }
+        const s = this.sessions.get(sessionId)!;
+        s.chatSessionId = chatSessionId;
+        s.parentMessageId = parentMessageId;
+    }
+
+    export(sessionId: string): SessionData {
+        return this.sessions.get(sessionId) ?? { chatSessionId: null, parentMessageId: null, history: [] };
+    }
+
+    clear(sessionId: string): void {
+        this.sessions.delete(sessionId);
+    }
+}
+
+// ========================
+// YouTube Helpers
+// ========================
+function extractYouTubeId(url: string): string | null {
+    const match = url.match(/(?:v=|youtu\.be\/|\/v\/|\/embed\/|\/shorts\/)([0-9A-Za-z_-]{11})/);
+    return match ? match[1] : null;
+}
+
+async function fetchYouTubeTranscript(videoId: string): Promise<string> {
+    // Fetches transcript via a free public API
+    const apiUrl = `https://yt-transcript-api.vercel.app/api/transcript?videoId=${videoId}`;
+    try {
+        const res = await fetch(apiUrl);
+        if (!res.ok) throw new Error(`Transcript API returned ${res.status}`);
+        const data = await res.json() as Array<{ text: string }>;
+        return data.map((d) => d.text).join(' ').substring(0, 15000);
+    } catch (e) {
+        throw new Error(`Failed to fetch YouTube transcript for ${videoId}: ${e}`);
+    }
+}
+
+// ========================
+// Main HSeekClient
+// ========================
+
+/**
+ * HSeekClient — The official client for the hAI private AI.
+ *
+ * @example
+ * ```typescript
+ * const ai = new HSeekClient();
+ * const res = await ai.chat("Hello!", { sessionId: "user_1", thinking: true });
+ * console.log(res.text);
+ * ```
+ */
+export class HSeekClient {
+    private apiKey: string;
+    private baseUrl: string;
+    private memory: MemoryStore;
+
+    constructor(apiKey?: string, baseUrl: string = "https://ai.hussain.ink") {
+        this.apiKey = apiKey || process.env.MY_SECRET_API_KEY || '';
+        if (!this.apiKey) {
+            throw new Error("API Key is missing. Pass it directly or set MY_SECRET_API_KEY in .env");
+        }
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.memory = new MemoryStore();
+    }
+
+    private buildPayload(prompt: string, options: ChatOptions): Record<string, unknown> {
+        const {
+            sessionId, thinking = false, search = false,
+            chatSessionId, parentMessageId,
+            system, temperature, maxTokens, jsonMode,
+            translate, codeMode, verify, summarize, includeThought,
+            image, memoryDepth = 10,
+        } = options;
+
+        // Build messages array
+        const messages: Array<{ role: string; content: unknown }> = [];
+        if (sessionId && memoryDepth !== 0) {
+            messages.push(...this.memory.getHistory(sessionId, memoryDepth));
+        }
+
+        const userContent = image
+            ? [{ type: "image_url", image_url: { url: image } }, { type: "text", text: prompt }]
+            : prompt;
+
+        messages.push({ role: "user", content: userContent });
+
+        const payload: Record<string, unknown> = {
+            messages,
+            stream: true,
+            thinking,
+            search,
+        };
+
+        // Optional feature flags
+        if (system) payload.system = system;
+        if (temperature !== undefined) payload.temperature = temperature;
+        if (maxTokens !== undefined) payload.max_tokens = maxTokens;
+        if (jsonMode) payload.json_mode = true;
+        if (translate) payload.translate = translate;
+        if (codeMode) payload.code_mode = true;
+        if (verify) payload.verify = true;
+        if (summarize) payload.summarize = true;
+        if (includeThought) payload.include_thought = true;
+
+        // Session management
+        if (chatSessionId) {
+            payload.chat_session_id = chatSessionId;
+        } else if (sessionId) {
+            const ids = this.memory.getIds(sessionId);
+            if (ids.chatSessionId) payload.chat_session_id = ids.chatSessionId;
+            if (ids.parentMessageId) payload.parent_message_id = ids.parentMessageId;
+        }
+        if (parentMessageId) payload.parent_message_id = parentMessageId;
+        if (options.model) payload.model = options.model;
+
+        return payload;
+    }
+
+    private createResponse(): HSeekResponse {
+        const r: HSeekResponse = {
+            text: "",
+            thinking_text: "",
+            search_text: "",
+            session_id: null,
+            parent_message_id: null,
+            latency_ms: null,
+            is_done: false,
+            toDict() {
+                return {
+                    text: this.text,
+                    thinking_text: this.thinking_text,
+                    search_text: this.search_text,
+                    session_id: this.session_id,
+                    parent_message_id: this.parent_message_id,
+                    latency_ms: this.latency_ms,
+                    is_done: this.is_done
+                };
+            },
+            get process_text() {
+                let p = this.search_text;
+                if (this.thinking_text) {
+                    if (p && !p.endsWith("\n")) p += "\n";
+                    p += this.thinking_text;
+                }
+                return p;
+            }
+        };
+        return r;
+    }
+
+    /**
+     * Stream a response in real-time, yielding chunks as they arrive.
+     */
+    async *streamChat(prompt: string, options: ChatOptions = {}): AsyncGenerator<HSeekResponse, void, unknown> {
+        const { sessionId, youtube, retries = 3, onDone } = options;
+
+        // Handle YouTube
+        let actualPrompt = prompt;
+        if (youtube) {
+            const videoId = extractYouTubeId(youtube);
+            if (!videoId) throw new Error(`Could not extract YouTube video ID from: ${youtube}`);
+            const transcript = await fetchYouTubeTranscript(videoId);
+            actualPrompt = `[YOUTUBE VIDEO TRANSCRIPT]:\n${transcript}\n\n[USER REQUEST]:\n${prompt}`;
+        }
+
+        const payload = this.buildPayload(actualPrompt, options);
+
+        const currentResponse = this.createResponse();
+        let attempt = 0;
+
+        while (attempt <= retries) {
+            try {
+                const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify(payload)
+                });
+
+                if (!response.ok) throw new Error(`HSeek API Error: ${response.status}`);
+                if (!response.body) throw new Error("Response body is null");
+
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split('\n');
+                    buffer = lines.pop() || '';
+
+                    for (const line of lines) {
+                        if (!line.startsWith('data: ')) continue;
+                        const dataStr = line.substring(6).trim();
+
+                        if (dataStr === '[DONE]') {
+                            currentResponse.is_done = true;
+                            if (sessionId) {
+                                this.memory.addToHistory(sessionId, 'user', actualPrompt);
+                                this.memory.addToHistory(sessionId, 'assistant', currentResponse.text);
+                            }
+                            if (onDone) onDone(currentResponse);
+                            yield currentResponse;
+                            return;
+                        }
+
+                        try {
+                            const dataJson = JSON.parse(dataStr);
+                            if (dataJson.choices?.[0]?.delta) {
+                                const delta = dataJson.choices[0].delta;
+                                if (delta.content) {
+                                    currentResponse.text += delta.content;
+                                    yield currentResponse;
+                                }
+                                if (delta.reasoning_content) {
+                                    currentResponse.thinking_text += delta.reasoning_content;
+                                    yield currentResponse;
+                                }
+                                if (delta.search_content) {
+                                    currentResponse.search_text += delta.search_content;
+                                    yield currentResponse;
+                                }
+                            } else if (dataJson.object === 'chat.completion.meta') {
+                                currentResponse.parent_message_id = dataJson.message_id;
+                                currentResponse.session_id = dataJson.chat_session_id;
+                                currentResponse.latency_ms = dataJson.latency_ms ?? null;
+                                this.memory.saveIds(sessionId, currentResponse.session_id, currentResponse.parent_message_id);
+                            }
+                        } catch (_) { /* ignore json parse errors */ }
+                    }
+                }
+                break; // Success
+
+            } catch (e) {
+                attempt++;
+                if (attempt > retries) throw new Error(`HSeek failed after ${retries} retries. Last error: ${e}`);
+                await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
+            }
+        }
+    }
+
+    /**
+     * Send a message and get the full response at once (non-streaming).
+     */
+    async chat(prompt: string, options: ChatOptions = {}): Promise<HSeekResponse> {
+        let finalResponse: HSeekResponse | null = null;
+        for await (const chunk of this.streamChat(prompt, options)) {
+            finalResponse = chunk;
+        }
+        if (!finalResponse) throw new Error("HSeek API returned an empty response.");
+        return finalResponse;
+    }
+
+    /**
+     * Export the full conversation history for a session.
+     */
+    exportHistory(sessionId: string): SessionData {
+        return this.memory.export(sessionId);
+    }
+
+    /**
+     * Clear the conversation memory for a session.
+     */
+    clearHistory(sessionId: string): void {
+        this.memory.clear(sessionId);
+    }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "declaration": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}