@relevanceai/sdk 3.0.0-alpha.2 → 3.0.0-alpha.3

package/README.md

@@ -1,320 +1,549 @@
 # Relevance AI JavaScript SDK
 
-Build full-stack AI applications using our JavaScript SDK. This multi-environment
-SDK enables you to integrate, extend, or build end-to-end solutions on top of
-our powerful AI Workforce platform.
+A comprehensive JavaScript/TypeScript SDK for building AI-powered applications
+with Relevance AI's workforce platform. Build, deploy, and scale AI agents
+across any JavaScript runtime.
 
-> **Note:** The SDK is in active development and not all features are available
-> yet. Please refer to our roadmap for updates.
+## Description
 
-## Quickstart
+The Relevance AI JavaScript SDK provides a unified interface for integrating
+AI agents into your applications. Whether you're building server-side
+applications, browser-based interfaces, or edge computing solutions, this SDK
+delivers consistent, type-safe access to Relevance AI's powerful agent
+ecosystem.
 
-```js
-import { createClient, AU_REGION } from "@relevanceai/sdk";
+### Key Features
+
+- **Universal Compatibility**: Works seamlessly across Node.js, Deno, Bun,
+  Cloudflare Workers, and browsers
+- **Event-Driven Architecture**: Real-time updates via native EventTarget API
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **Multi-Client Support**: Manage multiple projects and authentication scopes
+  simultaneously
+- **Zero Dependencies**: Built on web standards for minimal footprint
+
+## Quick Start
+
+Get up and running with AI agents in under 5 minutes:
 
-// Create a client with your credentials
+```typescript
+import { Agent, createClient, EU_REGION } from "@relevanceai/sdk";
+
+// Initialize client with your credentials
 const client = createClient({
-  apiKey: "sk-abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKL",
-  region: AU_REGION,
-  project: "12345678-90ab-cdef-1234-567890abcdef",
+  apiKey: process.env.RELEVANCE_API_KEY,
+  region: EU_REGION,
+  project: process.env.PROJECT_ID,
 });
 
-// Create a task for an agent
-const task = client.createTask({
-  agent: "fedcba09-8765-4321-fedc-ba0987654321",
+// Load an agent and start a conversation
+const agent = await Agent.get("agent-id");
+const task = await agent.sendMessage("Hello, how can you help me today?");
+
+// Listen for agent responses
+task.addEventListener("message", ({ detail: { message } }) => {
+  if (message.isAgent()) {
+    console.log("Agent:", message.text);
+  }
 });
+```
 
-// Send a message to the agent
-task.sendMessage(
-  "What is the weather like in Sydney, Australia this weekend?"
-);
+## Installation
 
-// Listen for responses
-task.addEventListener("message", ({ detail }) => {
-  const { message } = detail;
-  console.log(message.text);
+Choose the installation method for your runtime:
 
-  task.sendMessage("Thanks!");
-  
-  // Important: Stop listening when done to prevent memory leaks
-  task.stopListening();
-});
+### Node.js / Bun
+
+```bash
+npm install @relevanceai/sdk@latest
+# or
+yarn add @relevanceai/sdk@latest
+# or
+pnpm add @relevanceai/sdk@latest
+# or
+bun add @relevanceai/sdk@latest
 ```
 
-## Getting Started
+### Deno
 
-The JavaScript SDK is a stateless, event-driven toolkit that provides the
-flexibility to build any application you need. It sits on top of our API and
-offers a streamlined developer experience, making it easier for your apps to
-integrate with agents, tools, and workforces.
+```bash
+deno add jsr:@relevanceai/sdk
+```
 
-This multi-environment library allows you to build wherever modern JavaScript
-runs:
+Or import directly:
 
-- Node.js
-- Deno
-- Bun
-- Cloudflare Workers
-- Browser
+```typescript
+import { createClient } from "jsr:@relevanceai/sdk";
+```
+
+### Cloudflare Workers
 
-### Installation
+```bash
+npm install @relevanceai/sdk@latest
+```
 
-Install the SDK for your environment:
+### Browser (with bundler)
 
 ```bash
-# Node.js / Cloudflare Workers / Browser (with bundler)
 npm install @relevanceai/sdk@latest
+```
 
-# Deno
-deno add jsr:@relevanceai/sdk
+For bundlers that warn about `node:crypto`, create a shim:
 
-# Bun
-bun add @relevanceai/sdk@latest
+```javascript
+// shims/crypto.js
+export default window.crypto;
 ```
 
-#### Browser (CDN)
+Configure your bundler to use the shim:
+
+- [Vite configuration](https://vite.dev/config/shared-options.html#resolve-alias)
+- [Webpack configuration](https://webpack.js.org/configuration/resolve/#resolvealias)
+- [Rollup configuration](https://www.npmjs.com/package/@rollup/plugin-alias)
 
-If you are developing a frontend application and not using a bundler like
-[Vite](https://vite.dev) or [Webpack](https://webpack.js.org), you can use the
-CDN version directly:
+### Browser (CDN)
 
 ```html
 <script type="importmap">
-{
-  "imports": {
-    "@relevanceai/sdk": "https://esm.run/@relevanceai/sdk"
+  {
+    "imports": {
+      "@relevanceai/sdk": "https://esm.run/@relevanceai/sdk"
+    }
   }
-}
 </script>
 <script type="module">
-import { createClient } from "@relevanceai/sdk";
-// ...
+  import { createClient } from "@relevanceai/sdk";
+  // Your code here
 </script>
 ```
 
 ## Usage
 
-### Keys
+### Authentication
 
-To communicate with Relevance AI, you will need a key. Keys authenticate your
-requests and grant access to your project.
+The SDK supports two authentication methods for different use cases:
 
-There are two types of keys: _API_ and _Embed_.
+#### API Keys (Server-side)
 
-#### API Key
+API keys grant full access to your project. Use these for server applications
+and secure environments:
 
-API keys grant access to the entire project, including agents, tools, and
-workforces. This key is best used for server-side applications or protected web
-apps where third parties do not have access.
+```typescript
+import { createClient, AU_REGION } from "@relevanceai/sdk";
 
-Using the default client `createClient({ apiKey, region, project })` will create
-an API Key for convenience. Alternatively, you can create a `Key` instance and
-pass it to the client.
+const client = createClient({
+  apiKey: "sk-...",
+  region: AU_REGION,
+  project: "project-uuid",
+});
+```
 
-```js
-import { createClient, Key, AU_REGION } from "@relevanceai/sdk";
+You can also create a Key instance explicitly:
 
-const apiKey = "sk-...";
-const region = AU_REGION;
-const project = "1234...";
+```typescript
+import { Client, Key, AU_REGION } from "@relevanceai/sdk";
 
-const key = new Key({ apiKey, region, project });
-const client = createClient(key);
-```
+const key = new Key({
+  key: "sk-...",
+  region: AU_REGION,
+  project: "project-uuid",
+});
 
-#### Embed Key
+const client = new Client(key);
+```
 
-If you are developing a web app that allows third-party access, such as for your
-customers, it's best to share resources from the Relevance AI platform. This
-makes them available for public use and requires an embed key scoped only to
-that resource.
+#### Embed Keys (Client-side)
 
-To get an embed key, specify which public resource you wish to scope it to. For
-example, to create an embed key for a publicly available agent in your project:
+For public-facing applications, use embed keys which are scoped to a specific
+public agent:
 
-```js
-import { createClient, Key, AU_REGION } from "@relevanceai/sdk";
+```typescript
+import { Key, createClient, US_REGION } from "@relevanceai/sdk";
 
-const region = AU_REGION;
-const project = "1234...";
-const agent = "abcd..."; // a *public* agent
+const embedKey = await Key.generateEmbedKey({
+  region: US_REGION,
+  project: "project-uuid",
+  agentId: "public-agent-id", // Must be a public agent
+});
 
-const embedKey = await Key.generateEmbedKey({ region, project, agent });
 const client = createClient(embedKey);
 ```
 
-### Clients
+### Fetching Agents
 
-A client is the main entry point for the SDK. It configures communication with
-Relevance AI and manages authentication.
+Load agents before creating tasks:
 
-You can create multiple clients, which is useful for multi-project setups.
+```typescript
+// Using default client
+const agent = await Agent.get("agent-id");
 
-```js
-import { Client, Key, AU_REGION } from "@relevanceai/sdk";
+// Using specific client
+const customClient = createClient({
+  /* config */
+});
+const agent = await Agent.get("agent-id", customClient);
+
+// Access agent properties
+console.log(agent.name);
+console.log(agent.avatar);
+console.log(agent.description);
+```
 
-const apiKey = "sk-...";
-const region = AU_REGION;
-const projectOne = "1234...";
-const projectTwo = "abcd...";
+### Sending Messages
 
-const oneKey = new Key({ apiKey, region, project: projectOne });
-const twoKey = new Key({ apiKey, region, project: projectTwo });
+#### Create a New Task
 
-const oneClient = new Client(oneKey);
-const twoClient = new Client(twoKey);
-```
+Start a new conversation with an agent:
 
-#### Default client
+```typescript
+const agent = await Agent.get("agent-id");
+const task = await agent.sendMessage("What's the weather like today?");
+```
 
-Typically, you will only need a single client. In this case, use the default
-client factory as shown in the quickstart:
+#### Send to Existing Task
 
-```js
-import { createClient, Client } from "@relevanceai/sdk";
+Continue an existing conversation:
 
-const client = createClient({ apiKey, region, project });
+```typescript
+// Get an existing task
+const task = await agent.getTask("task-id");
 
-// elsewhere in your app
-Client.default();
+// Send a follow-up message
+await agent.sendMessage("What about tomorrow?", task);
 ```
 
-Attempting to create more than one default client will throw an error. Referencing
-the default client before creating one will also throw an error.
+Note: `sendMessage` returns once the message is sent and doesn't wait for a
+response. Use event listeners to handle responses.
+
+### Event Handling
+
+Tasks use an event-driven architecture for real-time updates:
+
+#### Available Events
+
+- **`start`**: Task initialization
+- **`status`**: Status changes (queued, running, complete, error)
+- **`message`**: New messages from agent or user
+- **`update`**: Tool execution updates
+- **`error`**: Error notifications
 
-### Tasks
+#### Listening for Events
 
-Whenever you run anything in Relevance AI, these are known as tasks. Tasks have
-a subject: an agent, tool, or workforce. You can send messages to these subjects,
-receive replies, and follow updates and errors.
+```typescript
+// Listen for messages
+task.addEventListener("message", ({ detail }) => {
+  const { message } = detail;
 
-> **Important:** Always call `task.stopListening()` when you're done with a task
-> to prevent memory leaks and clean up resources properly.
+  if (message.isAgent()) {
+    console.log("Agent:", message.text);
+  }
+});
 
-#### Creating Tasks
+// Listen for status changes
+task.addEventListener("status", ({ detail }) => {
+  console.log("Status changed to:", detail.status);
+});
+
+// Listen for tool updates
+task.addEventListener("update", ({ detail }) => {
+  console.log("Tool update:", detail.message);
+});
 
-The easiest way to create a new task is to use the client's convenient method
-`createTask` and provide the subject ID.
+// Listen for errors
+task.addEventListener("error", ({ detail }) => {
+  console.error("Task error:", detail.message);
+});
 
-```js
-const agentId = "1234...";
-const task = client.createTask({ agent: agentId });
+// Clean up when done
+task.unsubscribe();
 ```
 
-#### Sending a Message
+#### Managing Subscriptions
 
-Once you have a task instance, you can send messages to the subject using the
-`sendMessage()` method.
+The SDK automatically starts listening when you add event listeners. Remember
+to clean up:
 
-```js
-task.sendMessage("How many letter r's are there in the word 'strawberry'?");
+```typescript
+// Start listening (called automatically with addEventListener)
+task.subscribe();
+
+// Stop listening and clean up
+task.unsubscribe();
 ```
 
-Note that this call is not `async`. It sends the message and does not `await`
-a reply. This is intentional, as tasks are event-driven.
+### Advanced Usage
+
+#### Default Client Pattern
 
-### Events
+Use a singleton client throughout your application:
 
-Tasks are event-driven and an application must listen to predefined events to
-manage the status and messages of a task.
+```typescript
+// Initialize once at startup
+createClient({ apiKey, region, project });
 
-Use `.addEventListener()` to listen for task events.
+// Access anywhere in your app
+import { Client } from "@relevanceai/sdk";
+const client = Client.default();
+```
 
-```js
-task.sendMessage("What came first; the chicken or the egg?");
+#### Multiple Clients
 
-task.addEventListener("message", ({ detail }) => {
-  const { message } = detail;
-  console.log("> %s", message.text);
+Manage multiple projects or authentication scopes:
+
+```typescript
+import { Client, Key, EU_REGION } from "@relevanceai/sdk";
+
+const projectOneKey = new Key({
+  key: "sk-project1",
+  region: EU_REGION,
+  project: "project-1-id",
+});
+
+const projectTwoKey = new Key({
+  key: "sk-project2",
+  region: EU_REGION,
+  project: "project-2-id",
 });
+
+const clientOne = new Client(projectOneKey);
+const clientTwo = new Client(projectTwoKey);
+
+// Use different clients for different agents
+const agentOne = await Agent.get("agent-1", clientOne);
+const agentTwo = await Agent.get("agent-2", clientTwo);
 ```
 
-Tasks dispatch `CustomEvent`. Event properties will be set in the `detail`
-field of the event. You can see the types of events for more information about
-the properties associated with different events.
+## Examples
+
+For complete working examples, check out the `internal/examples` directory:
+
+- **Deno Examples** (`internal/examples/deno/`):
 
-Remember to call `task.stopListening()` once you no longer need to listen to
-the task.
+  - Client setup and configuration
+  - Creating and managing tasks
+  - Fetching agent information
+  - Retrieving existing tasks
 
----
+- **Browser Example** (`internal/examples/browser/`):
+  - Full chat application with Preact
+  - Real-time message handling
+  - UI components for agent interactions
 
-The following events are available for agent subjects.
+## API Reference
 
-#### `start`
+### Client
 
-When a _new_ task starts.
+```typescript
+class Client {
+  constructor(key: Key);
+  static default(): Client;
 
-**Details**
+  readonly key: Key;
+  readonly region: Region;
+  readonly project: string;
 
-```ts
-interface StartEventDetails {
-  id: string;
-  status: TaskStatus;
+  isEmbedKey(): boolean;
+  fetch<T>(endpoint: string, init?: RequestInit): Promise<T>;
+  url(path: string): URL;
+}
+
+function createClient(keyOrOptions: Key | CreateClientOptions): Client;
+
+interface CreateClientOptions {
+  apiKey: string;
+  region: Region;
+  project: string;
 }
 ```
 
-#### `status`
+### Key
+
+```typescript
+class Key {
+  static async generateEmbedKey(options: GenerateEmbedKeyOptions): Promise<Key>;
 
-Whenever the task's _status_ changes.
+  constructor(options: CreateKeyOptions);
 
-> **Note:** this event does **not** fire for starting status. Use the `start`
-> event if you need the initial status.
+  readonly region: Region;
+  readonly project: string;
+  readonly agentId?: string;
+  readonly taskPrefix?: string;
 
-**Details**
+  isEmbed(): boolean;
+  fetchHeaders(): HeadersInit;
+  toJSON(): CreateKeyOptions;
+}
+
+interface CreateKeyOptions {
+  key: string;
+  region: Region;
+  project: string;
+  agentId?: string;
+  taskPrefix?: string;
+}
 
-```ts
-interface StatusEventDetails {
-  status: TaskStatus;
+interface GenerateEmbedKeyOptions {
+  region: Region;
+  project: string;
+  agentId: string;
 }
 ```
 
-##### `update`
+### Agent
 
-A task has updated. This update will always be a tool for now but may expand in
-the future.
+```typescript
+class Agent {
+  static async get(id: string, client?: Client): Promise<Agent>;
 
-**Details**
+  readonly id: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly avatar?: string;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly region: Region;
+  readonly project: string;
 
-```ts
-interface UpdateEventDetails {
-  update: TaskMessage<"tool">;
+  getTask(taskId: string): Promise<Task>;
+  sendMessage(message: string, task?: Task): Promise<Task>;
 }
 ```
 
-#### `message`
+### Task
 
-A task has received a message.
+```typescript
+class Task extends EventTarget {
+  static async get(
+    id: string,
+    agentOrAgentId: Agent | string,
+    client?: Client
+  ): Promise<Task>;
 
-> **Note:** you will receive messages from _both_ subjects and users.
+  readonly id: string;
+  readonly title: string;
+  readonly status: TaskStatus;
+  readonly agent: Agent;
 
-**Details**
+  isRunning(): boolean;
+  getMessages(options?: { from?: Date }): Promise<AnyTaskMessage[]>;
+  subscribe(): void;
+  unsubscribe(): void;
 
-```ts
-interface MessageEventDetails {
-  message: TaskMessage<"agent" | "user">;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
 }
+
+type TaskStatus =
+  | "not-started"
+  | "idle"
+  | "queued"
+  | "running"
+  | "action"
+  | "complete"
+  | "error";
 ```
 
-#### `error`
+### Messages
+
+```typescript
+abstract class TaskMessage {
+  readonly id: string;
+  readonly type: MessageType;
+  readonly createdAt: Date;
 
-Whenever the task has failed.
+  isAgent(): boolean;
+}
 
-**Details**
+class AgentMessage extends TaskMessage {
+  readonly text: string;
+}
 
-```ts
-interface ErrorEventDetails {
-  error: TaskMessage<"error">;
+class UserMessage extends TaskMessage {
+  readonly text: string;
+}
+
+class ToolMessage extends TaskMessage {
+  readonly status: "pending" | "running" | "completed" | "failed";
+}
+
+class AgentErrorMessage extends TaskMessage {
+  readonly error: string;
 }
 ```
 
-**Example**
+### Types
 
-```js
-task.addEventListener("error", ({ detail }) => {
-  const { error } = detail;
-  console.error("Task failed:", error.text);
-  
-  // clean up
-  task.stopListening();
-});
+```typescript
+type Region = "us" | "eu" | "au";
+
+const US_REGION: Region = "us";
+const EU_REGION: Region = "eu";
+const AU_REGION: Region = "au";
+```
+
+## Contributing
+
+We welcome contributions to improve the SDK. Please follow these guidelines:
+
+### Development Setup
+
+1. Clone the repository
+2. Install Deno (primary development environment)
+
+```bash
+# Build npm package
+deno run dnt
 ```
+
+### Code Style
+
+- Use TypeScript for all code
+- Follow existing patterns and conventions
+- Maintain 80-character line width where practical
+- Write clear, concise commit messages
+
+### Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request with clear description
+
+## Roadmap
+
+### Current
+
+- [x] Core client functionality
+- [x] Agent and task creation
+- [x] Event-driven messaging
+- [x] Multi-environment support
+
+### Upcoming Features
+
+- [ ] Streaming responses
+- [ ] File upload support
+- [ ] Enhanced error recovery
+- [ ] Agent and task management
+- [ ] Workforce support
+- [ ] Tool support
+
+### Future Considerations (2.0)
+
+- [ ] WebSocket support for real-time updates
+- [ ] Offline queue management
+- [ ] Tool building architecture
+- [ ] Voice modality
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/RelevanceAI/relevance-js-sdk/issues)
+- **Community**: [Discord Server](https://discord.gg/relevanceai)
+
+## License
+
+MIT License. See [LICENSE](./LICENSE) for details.
+
+## Security
+
+For security vulnerabilities, please email security@relevanceai.com directly
+rather than using public issue trackers.