@reverbia/sdk 1.0.0-next.20251126182814 → 1.0.0-next.20251127132400

package/README.md

@@ -1,45 +1,186 @@
-# AI SDK
-
-A TypeScript SDK for interacting with ZetaChain's AI Portal API. This SDK
-provides a type-safe, developer-friendly interface for building applications
-that leverage AI chat completion capabilities.
-
-## Overview
-
-The AI SDK is an auto-generated TypeScript client library that wraps the
-ZetaChain AI Portal REST API. It enables seamless integration of AI-powered chat
-completion features into your applications with full TypeScript type safety and
-modern async/await patterns.
-
-## Features
-
-- **Type-Safe API Client**: Fully typed interfaces generated from the OpenAPI
-  specification, ensuring compile-time safety and excellent IDE autocomplete
-  support
-- **Chat Completions**: Generate AI-powered chat responses using configurable
-  models and conversation history
-- **Streaming Support**: Built-in support for streaming responses for real-time
-  AI interactions
-- **Health Monitoring**: Check service health and status to ensure reliable API
-  connectivity
-- **Flexible Configuration**: Customizable client instances with support for
-  custom base URLs, authentication, and request/response interceptors
-- **Error Handling**: Configurable error handling with support for throwing
-  errors or returning error objects
-- **Server-Sent Events**: Native support for SSE (Server-Sent Events) for
-  real-time streaming capabilities
-
-## Architecture
-
-The SDK is automatically generated from the OpenAPI specification using
-`@hey-api/openapi-ts`, ensuring it stays in sync with the latest API changes.
-The generated client provides a clean, promise-based API that follows modern
-JavaScript/TypeScript best practices.
-
-## Use Cases
-
-- Building AI-powered chatbots and conversational interfaces
-- Integrating AI capabilities into web and mobile applications
-- Creating applications that require natural language processing
-- Developing tools that leverage large language models through ZetaChain's
-  gateway
+# @reverbia/sdk
+
+A TypeScript SDK that empowers developers to build AI-powered applications. It
+enables you to send prompts to LLMs with streaming support, manage long-term
+memories, and encrypt sensitive data, all without needing your own LLM API key.
+
+## Installation
+
+```bash
+pnpm install @reverbia/sdk@next
+```
+
+> **Note:** Currently, the SDK is pre-release so all new versions are released
+> under the `next` tag (released on every merge to the `main` branch). Check out
+> npm to see the latest version.
+
+## Configuration
+
+To use the SDK, you'll need to configure your Privy provider and API URL.
+
+```env
+PRIVY_APP_ID=cmhwlx82v000xle0cde4rjy5y
+API_URL=https://ai-portal-dev.zetachain.com
+```
+
+## Authentication
+
+The SDK currently only supports authentication via [Privy](https://privy.io) and
+expects a Privy identity token.
+
+```typescript
+import { useIdentityToken } from "@privy-io/react-auth";
+
+const { identityToken } = useIdentityToken();
+```
+
+## Usage
+
+For an example of how to use this functionality check out [the example
+repo](https://github.com/zeta-chain/ai-examples).
+
+### useChat
+
+The `useChat` hook provides a convenient way to send chat messages to the LLM
+API with automatic token management and loading state handling.
+
+```typescript
+import { useChat } from "@reverbia/sdk/react";
+```
+
+```typescript
+const { sendMessage, isLoading, stop } = useChat({
+  getToken: async () => identityToken || null,
+  onFinish: (response) => {
+    console.log("Chat finished:", response);
+  },
+  onError: (error) => {
+    console.error("Chat error:", error);
+  },
+  onData: (chunk) => {
+    console.log("Received chunk:", chunk);
+  },
+});
+
+const handleSend = async () => {
+  const result = await sendMessage({
+    messages: [{ role: "user", content: "Hello!" }],
+    model: "gpt-4o-mini",
+  });
+
+  if (result.error) {
+    console.error("Error:", result.error);
+  } else {
+    console.log("Response:", result.data);
+  }
+};
+```
+
+### useMemory
+
+The `useMemory` hook allows you to extract facts/memories from messages and
+search through stored memories (in IndexedDB) using semantic search.
+
+How it works:
+
+1. **Fact Extraction:** When prompts are sent to the LLM, they are analyzed for
+   relevant facts. If found, these facts are extracted and converted into vector
+   embeddings.
+2. **Storage:** Extracted memories and their embeddings are stored locally in
+   IndexedDB.
+3. **Retrieval:** New prompts are converted into embedding vectors and compared
+   against stored memories. Relevant memories are then retrieved and used as
+   context for the LLM interaction.
+
+```typescript
+import { useMemory } from "@reverbia/sdk/react";
+```
+
+```typescript
+const { extractMemoriesFromMessage, searchMemories } = useMemory({
+  getToken: async () => identityToken || null,
+  embeddingModel: "openai/text-embedding-3-small",
+});
+
+const handleExtract = async () => {
+  await extractMemoriesFromMessage({
+    messages: [
+      { role: "user", content: "My favorite color is blue" },
+      {
+        role: "assistant",
+        content: "I will remember that your favorite color is blue.",
+      },
+    ],
+    model: "gpt-4o",
+  });
+};
+
+const handleSearch = async () => {
+  const memories = await searchMemories("What is my favorite color?");
+  console.log(memories);
+};
+```
+
+### useEncryption
+
+The `useEncryption` hook and utilities help you encrypt and decrypt local data
+using a key derived from a wallet signature (requires `@privy-io/react-auth`).
+
+```typescript
+import { usePrivy } from "@privy-io/react-auth";
+import { useEncryption, encryptData, decryptData } from "@reverbia/sdk/react";
+```
+
+```typescript
+const { authenticated } = usePrivy();
+
+// Initialize encryption (requests signature if key not present)
+// Pass true when user is authenticated with wallet
+useEncryption(authenticated);
+
+// Encrypt data
+const saveSecret = async (text: string) => {
+  const encrypted = await encryptData(text);
+  localStorage.setItem("secret", encrypted);
+};
+
+// Decrypt data
+const loadSecret = async () => {
+  const encrypted = localStorage.getItem("secret");
+  if (encrypted) {
+    const decrypted = await decryptData(encrypted);
+    console.log(decrypted);
+  }
+};
+```
+
+### Direct API Access
+
+You can also make requests to SDK functions directly without using the React
+hooks.
+
+```typescript
+import { postApiV1ChatCompletions } from "@reverbia/sdk";
+
+const response = await postApiV1ChatCompletions({
+  body: {
+    messages: [{ role: "user", content: "Tell me a joke" }],
+    model: "gpt-4o-mini",
+  },
+  headers: {
+    Authorization: `Bearer ${identityToken}`,
+  },
+});
+
+if (response.data) {
+  console.log(response.data.choices[0].message.content);
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a pull request.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -833,9 +833,10 @@ var createClient = (config = {}) => {
 };
 
 // src/clientConfig.ts
+var BASE_URL = "https://ai-portal-dev.zetachain.com";
 var createClientConfig = (config) => ({
   ...config,
-  baseUrl: "https://ai-portal-dev.zetachain.com"
+  baseUrl: BASE_URL
 });
 
 // src/client/client.gen.ts

package/dist/index.mjs

@@ -804,9 +804,10 @@ var createClient = (config = {}) => {
 };
 
 // src/clientConfig.ts
+var BASE_URL = "https://ai-portal-dev.zetachain.com";
 var createClientConfig = (config) => ({
   ...config,
-  baseUrl: "https://ai-portal-dev.zetachain.com"
+  baseUrl: BASE_URL
 });
 
 // src/client/client.gen.ts

package/dist/react/index.cjs

@@ -851,9 +851,10 @@ var createClient = (config = {}) => {
 };
 
 // src/clientConfig.ts
+var BASE_URL = "https://ai-portal-dev.zetachain.com";
 var createClientConfig = (config) => ({
   ...config,
-  baseUrl: "https://ai-portal-dev.zetachain.com"
+  baseUrl: BASE_URL
 });
 
 // src/client/client.gen.ts
@@ -863,7 +864,7 @@ var client = createClient(createClientConfig(createConfig()));
 function useChat(options) {
   const {
     getToken,
-    baseUrl,
+    baseUrl = BASE_URL,
     onData: globalOnData,
     onFinish,
     onError
@@ -920,6 +921,7 @@ function useChat(options) {
           return { data: null, error: errorMsg };
         }
         const sseResult = await client.sse.post({
+          baseUrl,
           url: "/api/v1/chat/completions",
           body: {
             messages,
@@ -1410,7 +1412,7 @@ var generateEmbeddingForText = async (text, options = {}) => {
   const {
     model = "openai/text-embedding-3-small",
     getToken,
-    baseUrl
+    baseUrl = BASE_URL
   } = options;
   try {
     const token = getToken ? await getToken() : null;
@@ -1455,7 +1457,7 @@ var generateEmbeddingsForMemories = async (memories, options = {}) => {
   const {
     model = "openai/text-embedding-3-small",
     getToken,
-    baseUrl
+    baseUrl = BASE_URL
   } = options;
   const embeddings = /* @__PURE__ */ new Map();
   for (const memory of memories) {
@@ -1518,7 +1520,7 @@ function useMemory(options = {}) {
     generateEmbeddings = true,
     onFactsExtracted,
     getToken,
-    baseUrl
+    baseUrl = BASE_URL
   } = options;
   const extractionInProgressRef = (0, import_react3.useRef)(false);
   const extractMemoriesFromMessage = (0, import_react3.useCallback)(

package/dist/react/index.mjs

@@ -807,9 +807,10 @@ var createClient = (config = {}) => {
 };
 
 // src/clientConfig.ts
+var BASE_URL = "https://ai-portal-dev.zetachain.com";
 var createClientConfig = (config) => ({
   ...config,
-  baseUrl: "https://ai-portal-dev.zetachain.com"
+  baseUrl: BASE_URL
 });
 
 // src/client/client.gen.ts
@@ -819,7 +820,7 @@ var client = createClient(createClientConfig(createConfig()));
 function useChat(options) {
   const {
     getToken,
-    baseUrl,
+    baseUrl = BASE_URL,
     onData: globalOnData,
     onFinish,
     onError
@@ -876,6 +877,7 @@ function useChat(options) {
           return { data: null, error: errorMsg };
         }
         const sseResult = await client.sse.post({
+          baseUrl,
           url: "/api/v1/chat/completions",
           body: {
             messages,
@@ -1366,7 +1368,7 @@ var generateEmbeddingForText = async (text, options = {}) => {
   const {
     model = "openai/text-embedding-3-small",
     getToken,
-    baseUrl
+    baseUrl = BASE_URL
   } = options;
   try {
     const token = getToken ? await getToken() : null;
@@ -1411,7 +1413,7 @@ var generateEmbeddingsForMemories = async (memories, options = {}) => {
   const {
     model = "openai/text-embedding-3-small",
     getToken,
-    baseUrl
+    baseUrl = BASE_URL
   } = options;
   const embeddings = /* @__PURE__ */ new Map();
   for (const memory of memories) {
@@ -1474,7 +1476,7 @@ function useMemory(options = {}) {
     generateEmbeddings = true,
     onFactsExtracted,
     getToken,
-    baseUrl
+    baseUrl = BASE_URL
   } = options;
   const extractionInProgressRef = useRef3(false);
   const extractMemoriesFromMessage = useCallback2(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reverbia/sdk",
-  "version": "1.0.0-next.20251126182814",
+  "version": "1.0.0-next.20251127132400",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",