chat-nest-sdk 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# chat-nest-sdk
+
+> Frontend SDK for Chat Nest providing a simple React hook to consume streaming AI APIs safely.
+
+This package handles:
+- Streaming response handling
+- Cancellation propagation
+- Intelligent retry behavior
+- Error normalization
+- Message state management
+
+Designed for production usage in React applications.
+
+---
+
+## ✨ Features
+
+- Streaming token handling
+- Abort-safe cancellation
+- Retry only on network / server failures
+- No retries on client or policy errors
+- Message state management
+- Lightweight and framework-friendly
+
+---
+
+## 📦 Installation
+
+```bash
+npm install chat-nest-sdk
+```
+
+---
+
+## 🚀 Usage
+
+### Example
+
+```
+import { useAiChat } from "chat-nest-sdk";
+
+function App() {
+  const chat = useAiChat({
+    endpoint: "http://localhost:3001/api/chat",
+  });
+
+  return (
+    <>
+      <div>
+        {chat.messages.map((m) => (
+          <div key={m.id}>
+            <strong>{m.role}</strong>: {m.content}
+          </div>
+        ))}
+      </div>
+
+      <button onClick={() => chat.sendMessage("Hello!")}>
+        Send
+      </button>
+
+      <button onClick={chat.cancel}>
+        Cancel
+      </button>
+    </>
+  );
+}
+```
+
+---
+
+## 🧠 API
+
+### useAiChat(options)
+
+| Field    | Type   | Description          |
+| -------- | ------ | -------------------- |
+| endpoint | string | Backend API endpoint |
+
+| Field             | Description              |
+| ----------------- | ------------------------ |
+| messages          | Chat message list        |
+| sendMessage(text) | Sends user message       |
+| cancel()          | Cancels active request   |
+| isStreaming       | Whether stream is active |
+| error             | Last error               |
+
+---
+
+## ⚠️ Important Notes
+
+Only one active request is allowed at a time.
+
+Cancel immediately stops streaming and billing.
+
+4xx errors are never retried.
+
+Network failures retry automatically.
+
+---
+
+## 📄 License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { UseAIChatOptions, UseAIChatReturn, AIClient, AiClientConfig, Message, StreamCallbacks } from 'chat-nest-core';
+
+declare function useAiChat(options: UseAIChatOptions): UseAIChatReturn;
+
+declare class FetchAiClient implements AIClient {
+    private abortController?;
+    private config;
+    constructor(config: AiClientConfig);
+    streamChat(messages: Message[], callbacks: StreamCallbacks): Promise<void>;
+    cancel(): void;
+    private executeStream;
+    private normalizeError;
+    private backoff;
+}
+
+export { FetchAiClient, useAiChat };

package/dist/index.js

@@ -0,0 +1,195 @@
+// src/react/useAiChat.ts
+import { useCallback, useMemo, useRef, useState } from "react";
+import {
+  MessageRole
+} from "chat-nest-core";
+
+// src/core/aiClient.ts
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRIES = 2;
+var NonRetryableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NonRetryableError";
+  }
+};
+var FetchAiClient = class {
+  constructor(config) {
+    this.config = {
+      endpoint: config.endpoint,
+      headers: config.headers ?? {},
+      timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT,
+      maxRetries: config.maxRetries ?? DEFAULT_RETRIES
+    };
+  }
+  async streamChat(messages, callbacks) {
+    let attempt = 0;
+    while (attempt <= this.config.maxRetries) {
+      try {
+        await this.executeStream(messages, callbacks);
+        return;
+      } catch (error) {
+        if (error?.name === "AbortError") {
+          return;
+        }
+        if (error instanceof Error && error.name === "NonRetryableError") {
+          callbacks.onError(this.normalizeError(error));
+          return;
+        }
+        attempt++;
+        if (attempt > this.config.maxRetries) {
+          callbacks.onError(this.normalizeError(error));
+          return;
+        }
+        await this.backoff(attempt);
+      }
+    }
+  }
+  cancel() {
+    this.abortController?.abort();
+  }
+  async executeStream(messages, callbacks) {
+    this.abortController = new AbortController();
+    const timeoutId = setTimeout(
+      () => this.abortController?.abort(),
+      this.config.timeoutMs
+    );
+    try {
+      const response = await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        },
+        signal: this.abortController.signal,
+        body: JSON.stringify({ messages })
+      });
+      if (!response.ok) {
+        if (response.status >= 400 && response.status < 500) {
+          throw new NonRetryableError(`HTTP ${response.status}`);
+        }
+        throw new Error(`HTTP ${response.status}`);
+      }
+      if (!response.body) {
+        throw new Error("Streaming not supported by the response");
+      }
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        const chunk = decoder.decode(value, { stream: true });
+        callbacks.onToken(chunk);
+      }
+      callbacks.onComplete();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  normalizeError(error) {
+    if (error?.name === "AbortError") {
+      return new Error("Request cancelled by user");
+    }
+    if (error instanceof Error) {
+      return error;
+    }
+    return new Error("Unknown AI client error");
+  }
+  async backoff(attempt) {
+    const delay = Math.min(1e3 * attempt, 3e3);
+    return new Promise((resolve) => setTimeout(resolve, delay));
+  }
+};
+
+// src/core/utils/helpers.ts
+function generateId() {
+  return crypto.randomUUID();
+}
+
+// src/react/useAiChat.ts
+function useAiChat(options) {
+  const {
+    endpoint,
+    initialMessages = [],
+    maxMessages = 10
+  } = options;
+  const [messages, setMessages] = useState(
+    initialMessages
+  );
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState();
+  const clientRef = useRef(null);
+  if (!clientRef.current) {
+    clientRef.current = new FetchAiClient({
+      endpoint
+    });
+  }
+  const sendMessage = useCallback(async (text) => {
+    if (!text.trim() || isStreaming) return;
+    setError(void 0);
+    const userMessage = {
+      id: generateId(),
+      role: MessageRole.User,
+      content: text
+    };
+    const assistantMessage = {
+      id: generateId(),
+      role: MessageRole.Assistant,
+      content: ""
+    };
+    setMessages((prev) => {
+      const next = [...prev, userMessage, assistantMessage];
+      return next.slice(-maxMessages);
+    });
+    setIsStreaming(true);
+    const history = [...messages, userMessage];
+    try {
+      await clientRef.current.streamChat(history, {
+        onToken(token) {
+          setMessages(
+            (prev) => prev.map(
+              (msg) => msg.id === assistantMessage.id ? {
+                ...msg,
+                content: msg.content + token
+              } : msg
+            )
+          );
+        },
+        onComplete() {
+          setIsStreaming(false);
+        },
+        onError(err) {
+          setError(err.message);
+          setIsStreaming(false);
+        }
+      });
+    } catch (err) {
+      setError(err.message);
+      setIsStreaming(false);
+    }
+  }, [endpoint, isStreaming, maxMessages, messages]);
+  const cancel = useCallback(() => {
+    clientRef.current?.cancel();
+    setIsStreaming(false);
+  }, []);
+  const reset = useCallback(() => {
+    cancel();
+    setMessages(initialMessages);
+    setError(void 0);
+  }, [cancel, initialMessages]);
+  return useMemo(
+    () => ({
+      messages,
+      sendMessage,
+      cancel,
+      reset,
+      isStreaming,
+      error
+    }),
+    [messages, sendMessage, cancel, reset, isStreaming, error]
+  );
+}
+export {
+  FetchAiClient,
+  useAiChat
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "chat-nest-sdk",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"homepage": "https://github.com/shivams10/chat-nest",
+	"bugs": {
+		"url": "https://github.com/shivams10/chat-nest/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/shivams10/chat-nest"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup src/index.ts --format esm --dts --external react --external react-dom",
+		"dev": "tsup src/index.ts --format esm --watch --external react --external react-dom",
+		"clean": "rm -rf dist",	  
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"keywords": [],
+	"author": "Shivam Shukla",
+	"license": "ISC",
+	"description": "",
+	"sideEffects": false,
+	"devDependencies": {
+		"@types/react": "^19.2.8",
+		"tsup": "^8.5.1",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"react": ">=18",
+		"react-dom": ">=18"
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"dependencies": {
+		"chat-nest-core": "*"
+	}
+}