@dremio/js-sdk 0.41.0 → 0.43.0

package/README.md

@@ -42,6 +42,17 @@ bun install @dremio/js-sdk
 </script>
 ```
 
+### Deno
+
+```typescript
+import { Dremio, fromPat } from "npm:@dremio/js-sdk@latest/cloud";
+
+const dremio = new Dremio({
+  origin: "https://api.dremio.cloud",
+  credentials: fromPat("PERSONAL_ACCESS_TOKEN"),
+});
+```
+
 ## Quick Start
 
 ```typescript
@@ -119,7 +130,9 @@ API responses are automatically converted to native JavaScript/TypeScript types:
 
 ## Table of Contents
 
+- [Configuration](#configuration)
 - [Authentication](#authentication)
+- [AI Agent](#ai-agent)
 - [Catalog](#catalog)
 - [Engine Rules](#engine-rules)
 - [Engines](#engines)
@@ -131,6 +144,65 @@ API responses are automatically converted to native JavaScript/TypeScript types:
 - [Scripts](#scripts)
 - [Users](#users)
 
+## Configuration
+
+The `Dremio` class accepts a configuration object with the following properties:
+
+```typescript
+interface DremioConfig {
+  origin: string;
+  credentials: CredentialProvider;
+  logger?: Logger;
+  fetch?: typeof fetch;
+}
+```
+
+### `origin`
+
+The base API URL of your Dremio instance:
+
+**Dremio Cloud:**
+
+- `"https://api.dremio.cloud"` - US region
+- `"https://api.eu.dremio.cloud"` - EU region
+
+**Dremio Self-Hosted:**
+
+- Your self-hosted Dremio URL (e.g., `"https://dremio.example.com"`)
+
+### `credentials`
+
+A credential provider function that returns authentication headers. See the [Authentication](#authentication) section for available options:
+
+- `fromAccessToken()` - OAuth access token
+- `fromRefreshToken()` - OAuth refresh token (auto-refreshes)
+- `fromPat()` - Personal access token
+
+### `logger` (optional)
+
+A custom logger implementation. Must implement:
+
+```typescript
+interface Logger {
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+}
+```
+
+See [Custom Logger](#custom-logger) for examples.
+
+### `fetch` (optional)
+
+A custom fetch implementation. Useful for:
+
+- Adding custom middleware
+- Using a specific fetch polyfill
+- Intercepting requests for testing
+
+Defaults to the global `fetch` function.
+
 ## Authentication
 
 ### Access Token
@@ -171,6 +243,214 @@ const dremio = new Dremio({
 });
 ```
 
+## AI Agent
+
+### `AgentConversation`
+
+Represents a conversation with the Dremio AI Agent.
+
+#### Properties
+
+- `id: string` - Unique identifier for the conversation
+- `title: string` - The conversation title
+- `createdAt: Temporal.Instant` - When the conversation was created
+- `modifiedAt: Temporal.Instant` - When the conversation was last modified
+- `modelName: string | null` - The AI model name last used for this conversation
+- `modelProviderId: string | null` - The AI model provider ID last used for this conversation
+
+#### `AgentConversation` implements the [`Observable` contract](https://github.com/WICG/observable) using `Symbol.observable`:
+
+```typescript
+import { from } from "rxjs";
+
+from(conversation).subscribe((chatEvent) => {
+  console.log(chatEvent);
+});
+```
+
+#### Create an `AgentConversation`
+
+```typescript
+const conversation = await dremio.ai("PROJECT_ID").createConversation({
+  message: new UserChatMessage(
+    new UserChatMessageStringContent(
+      "Can you help me visualize the data in the Citibike sample dataset?",
+    ),
+  ),
+});
+```
+
+#### Retrieve `AgentConversation` by ID
+
+```typescript
+const conversation = await dremio
+  .ai("PROJECT_ID")
+  .retrieveConversation("CONVERSATION_ID");
+```
+
+#### Update `AgentConversation`
+
+```typescript
+const result = await conversation.update({ title: "New title" });
+```
+
+#### Delete `AgentConversation`
+
+```typescript
+await conversation.delete();
+```
+
+#### List all `AgentConversation`s
+
+```typescript
+for await (const conversation of dremio
+  .ai("PROJECT_ID")
+  .listConversations()
+  .data()) {
+  console.log(conversation);
+}
+```
+
+#### Send message to `AgentConversation`
+
+To send a message to the Agent, use the `startRun()` method:
+
+```typescript
+await conversation.startRun({
+  message: new UserChatMessage(
+    new UserChatMessageStringContent(
+      "Please adjust the x-axis range to show only 2025-2026",
+    ),
+  ),
+});
+```
+
+### `AgentConversationSnapshotBuilder`
+
+Compiles a sequence of `ChatEvent`s into a structured view of the current conversation state.
+
+#### Building a Snapshot
+
+Create a snapshot from existing conversation history:
+
+```typescript
+const conversation = (
+  await dremio.ai("PROJECT_ID").retrieveConversation("CONVERSATION_ID")
+).unwrap();
+
+const conversationSnapshot = AgentConversationSnapshotBuilder.fromChatEvents(
+  conversation.id,
+  (await conversation.history()).unwrap(),
+);
+```
+
+#### Adding Events in Real-Time
+
+Monitor chat events as they stream in and add them to the snapshot:
+
+```typescript
+const runId = await conversation
+  .startRun({
+    message: new UserChatMessage(
+      new UserChatMessageStringContent(
+        "What data is available to me in Dremio?",
+      ),
+    ),
+  })
+  .then((res) => res.unwrap());
+
+conversation.runEvents$(runId).subscribe((chatEvent) => {
+  conversationSnapshot.addChatEvent(chatEvent);
+  console.log(conversationSnapshot.get(runId)!.toJSON());
+});
+```
+
+#### Accessing Snapshot Data
+
+The snapshot is iterable and provides access to exchanges:
+
+```typescript
+// Iterate through all exchanges
+for (const exchange of conversationSnapshot) {
+  console.log("Exchange ID:", exchange.id);
+  for (const message of exchange.messages) {
+    console.log("Message:", message);
+  }
+  for (const toolCall of exchange.toolCalls) {
+    console.log("Tool Call:", toolCall.id, toolCall.state);
+  }
+}
+
+// Get a specific exchange
+const exchange = conversationSnapshot.get(runId);
+```
+
+#### Snapshot Methods
+
+- `length: number` - Get the number of exchanges in the snapshot
+- `clone(): AgentConversationSnapshotBuilder` - Create a deep clone of the builder
+- `slice(startExchangeId, endExchangeId?)` - Get a shallow clone containing exchanges in a range
+- `toJSON()` - Serialize the snapshot to JSON
+
+#### Snapshot Output Example
+
+The `toJSON()` method returns an array of exchanges with their messages and tool calls:
+
+```json
+[
+  {
+    "id": "run-id-1",
+    "messages": [
+      {
+        "id": "msg-1",
+        "runId": "run-id-1",
+        "conversationId": "conv-id",
+        "role": "user",
+        "content": {
+          "chunkType": "userMessage",
+          "text": "What data is available?"
+        }
+      },
+      {
+        "id": "msg-2",
+        "runId": "run-id-1",
+        "conversationId": "conv-id",
+        "role": "agent",
+        "content": {
+          "chunkType": "model",
+          "name": "modelGeneric",
+          "result": {
+            "text": "Here are the available datasets..."
+          }
+        }
+      }
+    ],
+    "toolCalls": [
+      {
+        "id": "tool-call-1",
+        "state": "success",
+        "request": {
+          "content": {
+            "chunkType": "toolRequest",
+            "name": "queryTool",
+            "arguments": { "query": "SELECT * FROM schemas" }
+          }
+        },
+        "result": {
+          "content": {
+            "chunkType": "toolResponse",
+            "name": "queryTool",
+            "result": {
+              "rows": [{ "schema_name": "public" }]
+            }
+          }
+        }
+      }
+    ]
+  }
+]
+```
+
 ## Catalog
 
 ### `CatalogReference` Interface
@@ -883,10 +1163,10 @@ import { Result } from "ts-results-es";
 const result = await dremio.projects.retrieve("PROJECT_ID");
 
 if (result.isOk()) {
-  const project = result.unwrap();
+  const project = result.value;
   console.log(project.name);
 } else {
-  const error = result.unwrapErr();
+  const error = result.error;
   console.error("Error:", error);
 }