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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Relevance AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# 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.
+
+> **Note:** The SDK is in active development and not all features are available
+> yet. Please refer to our roadmap for updates.
+
+## Quickstart
+
+```js
+import { createClient, AU_REGION } from "@relevanceai/sdk";
+
+// Create a client with your credentials
+const client = createClient({
+  apiKey: "sk-abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKL",
+  region: AU_REGION,
+  project: "12345678-90ab-cdef-1234-567890abcdef",
+});
+
+// Create a task for an agent
+const task = client.createTask({
+  agent: "fedcba09-8765-4321-fedc-ba0987654321",
+});
+
+// Send a message to the agent
+task.sendMessage(
+  "What is the weather like in Sydney, Australia this weekend?"
+);
+
+// Listen for responses
+task.addEventListener("message", ({ detail }) => {
+  const { message } = detail;
+  console.log(message.text);
+
+  task.sendMessage("Thanks!");
+  
+  // Important: Stop listening when done to prevent memory leaks
+  task.stopListening();
+});
+```
+
+## Getting Started
+
+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.
+
+This multi-environment library allows you to build wherever modern JavaScript
+runs:
+
+- Node.js
+- Deno
+- Bun
+- Cloudflare Workers
+- Browser
+
+### Installation
+
+Install the SDK for your environment:
+
+```bash
+# Node.js / Cloudflare Workers / Browser (with bundler)
+npm install @relevanceai/sdk@latest
+
+# Deno
+deno add jsr:@relevanceai/sdk
+
+# Bun
+bun add @relevanceai/sdk@latest
+```
+
+#### Browser (CDN)
+
+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:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@relevanceai/sdk": "https://esm.run/@relevanceai/sdk"
+  }
+}
+</script>
+<script type="module">
+import { createClient } from "@relevanceai/sdk";
+// ...
+</script>
+```
+
+## Usage
+
+### Keys
+
+To communicate with Relevance AI, you will need a key. Keys authenticate your
+requests and grant access to your project.
+
+There are two types of keys: _API_ and _Embed_.
+
+#### API Key
+
+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.
+
+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.
+
+```js
+import { createClient, Key, AU_REGION } from "@relevanceai/sdk";
+
+const apiKey = "sk-...";
+const region = AU_REGION;
+const project = "1234...";
+
+const key = new Key({ apiKey, region, project });
+const client = createClient(key);
+```
+
+#### Embed 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.
+
+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:
+
+```js
+import { createClient, Key, AU_REGION } from "@relevanceai/sdk";
+
+const region = AU_REGION;
+const project = "1234...";
+const agent = "abcd..."; // a *public* agent
+
+const embedKey = await Key.generateEmbedKey({ region, project, agent });
+const client = createClient(embedKey);
+```
+
+### Clients
+
+A client is the main entry point for the SDK. It configures communication with
+Relevance AI and manages authentication.
+
+You can create multiple clients, which is useful for multi-project setups.
+
+```js
+import { Client, Key, AU_REGION } from "@relevanceai/sdk";
+
+const apiKey = "sk-...";
+const region = AU_REGION;
+const projectOne = "1234...";
+const projectTwo = "abcd...";
+
+const oneKey = new Key({ apiKey, region, project: projectOne });
+const twoKey = new Key({ apiKey, region, project: projectTwo });
+
+const oneClient = new Client(oneKey);
+const twoClient = new Client(twoKey);
+```
+
+#### Default client
+
+Typically, you will only need a single client. In this case, use the default
+client factory as shown in the quickstart:
+
+```js
+import { createClient, Client } from "@relevanceai/sdk";
+
+const client = createClient({ apiKey, region, project });
+
+// elsewhere in your app
+Client.default();
+```
+
+Attempting to create more than one default client will throw an error. Referencing
+the default client before creating one will also throw an error.
+
+### Tasks
+
+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.
+
+> **Important:** Always call `task.stopListening()` when you're done with a task
+> to prevent memory leaks and clean up resources properly.
+
+#### Creating Tasks
+
+The easiest way to create a new task is to use the client's convenient method
+`createTask` and provide the subject ID.
+
+```js
+const agentId = "1234...";
+const task = client.createTask({ agent: agentId });
+```
+
+#### Sending a Message
+
+Once you have a task instance, you can send messages to the subject using the
+`sendMessage()` method.
+
+```js
+task.sendMessage("How many letter r's are there in the word 'strawberry'?");
+```
+
+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.
+
+### Events
+
+Tasks are event-driven and an application must listen to predefined events to
+manage the status and messages of a task.
+
+Use `.addEventListener()` to listen for task events.
+
+```js
+task.sendMessage("What came first; the chicken or the egg?");
+
+task.addEventListener("message", ({ detail }) => {
+  const { message } = detail;
+  console.log("> %s", message.text);
+});
+```
+
+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.
+
+Remember to call `task.stopListening()` once you no longer need to listen to
+the task.
+
+---
+
+The following events are available for agent subjects.
+
+#### `start`
+
+When a _new_ task starts.
+
+**Details**
+
+```ts
+interface StartEventDetails {
+  id: string;
+  status: TaskStatus;
+}
+```
+
+#### `status`
+
+Whenever the task's _status_ changes.
+
+> **Note:** this event does **not** fire for starting status. Use the `start`
+> event if you need the initial status.
+
+**Details**
+
+```ts
+interface StatusEventDetails {
+  status: TaskStatus;
+}
+```
+
+##### `update`
+
+A task has updated. This update will always be a tool for now but may expand in
+the future.
+
+**Details**
+
+```ts
+interface UpdateEventDetails {
+  update: TaskMessage<"tool">;
+}
+```
+
+#### `message`
+
+A task has received a message.
+
+> **Note:** you will receive messages from _both_ subjects and users.
+
+**Details**
+
+```ts
+interface MessageEventDetails {
+  message: TaskMessage<"agent" | "user">;
+}
+```
+
+#### `error`
+
+Whenever the task has failed.
+
+**Details**
+
+```ts
+interface ErrorEventDetails {
+  error: TaskMessage<"error">;
+}
+```
+
+**Example**
+
+```js
+task.addEventListener("error", ({ detail }) => {
+  const { error } = detail;
+  console.error("Task failed:", error.text);
+  
+  // clean up
+  task.stopListening();
+});
+```

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@relevanceai/sdk",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-alpha.2",
   "license": "MIT",
+  "main": "./script/mod.js",
   "module": "./esm/mod.js",
   "exports": {
     ".": {
-      "import": "./esm/mod.js"
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
     }
   },
   "scripts": {},

package/script/agent-task.d.ts

@@ -0,0 +1,61 @@
+import type { Agent } from "./agent.js";
+import { TaskMessage } from "./message.js";
+import { Task, type TaskStatus } from "./task.js";
+type AgentTaskEvents = {
+    start: {
+        status: TaskStatus;
+    };
+    status: {
+        status: TaskStatus;
+    };
+    message: {
+        message: TaskMessage<"agent-message" | "user-message">;
+    };
+    update: {
+        message: TaskMessage<"tool-run">;
+    };
+};
+export type AgentTaskState = "idle" | "starting-up" | "running" | "pending-approval" | "waiting-for-capacity" | "cancelled" | "timed-out" | "escalated" | "unrecoverable" | "paused" | "completed" | "errored-pending-approval" | "queued-for-approval" | "queued-for-rerun";
+/**
+ * AgentTask represents a conversation task with an AI agent. It extends the
+ * base Task class with agent-specific functionality for sending messages and
+ * retrieving conversation history.
+ *
+ * @see {@link Task} for the base task functionality.
+ * @see {@link Agent} for the agent this task is associated with.
+ *
+ * @class AgentTask
+ * @extends Task<Agent, AgentTaskEvents>
+ */
+export declare class AgentTask extends Task<Agent, AgentTaskEvents> {
+    /**
+     * Sends a message to the agent. This method triggers the agent with the
+     * message and updates the task ID if this is the first message.
+     *
+     * Note: This method is asynchronous but doesn't return a promise. Use event
+     * listeners to track the response.
+     *
+     * @param {string} message
+     */
+    sendMessage(message: string): void;
+    /**
+     * Fetches the current status of the task from the API.
+     *
+     * @returns {Promise<TaskStatus>} The current task status.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    fetchStatus(): Promise<TaskStatus>;
+    /**
+     * Fetches messages from the conversation.
+     *
+     * @param {Object} [options] Optional fetch options.
+     * @param {Date} [options.from] Fetch messages after this timestamp.
+     *
+     * @returns {Promise<TaskMessage[]>} Array of messages in ascending order.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    fetchMessages({ from }?: {
+        from?: Date;
+    }): Promise<TaskMessage[]>;
+}
+export {};

package/script/agent-task.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTask = void 0;
+const message_js_1 = require("./message.js");
+const task_js_1 = require("./task.js");
+/**
+ * Converts an AgentTaskState to a simplified TaskStatus.
+ *
+ * @internal
+ *
+ * @param {AgentTaskState} state The agent task state to convert.
+ * @returns {TaskStatus} The simplified task status.
+ */
+function stateToStatus(state) {
+    switch (state) {
+        case "paused":
+        case "idle":
+            return "idle";
+        case "starting-up":
+        case "waiting-for-capacity":
+        case "queued-for-approval":
+        case "queued-for-rerun":
+            return "queued";
+        case "running":
+            return "running";
+        case "pending-approval":
+        case "escalated":
+            return "action";
+        case "timed-out":
+            return "error";
+        case "cancelled":
+        case "completed":
+            return "complete";
+        case "unrecoverable":
+        case "errored-pending-approval":
+            return "error";
+        default:
+            throw new Error(`unhandled task state: ${state}`);
+    }
+}
+/**
+ * AgentTask represents a conversation task with an AI agent. It extends the
+ * base Task class with agent-specific functionality for sending messages and
+ * retrieving conversation history.
+ *
+ * @see {@link Task} for the base task functionality.
+ * @see {@link Agent} for the agent this task is associated with.
+ *
+ * @class AgentTask
+ * @extends Task<Agent, AgentTaskEvents>
+ */
+class AgentTask extends task_js_1.Task {
+    /**
+     * Sends a message to the agent. This method triggers the agent with the
+     * message and updates the task ID if this is the first message.
+     *
+     * Note: This method is asynchronous but doesn't return a promise. Use event
+     * listeners to track the response.
+     *
+     * @param {string} message
+     */
+    sendMessage(message) {
+        this.subject.trigger(message, this.id || undefined).then(({ id, state }) => {
+            // started
+            if (!this.id) {
+                this.setId(id, stateToStatus(state));
+            }
+        });
+    }
+    /**
+     * Fetches the current status of the task from the API.
+     *
+     * @returns {Promise<TaskStatus>} The current task status.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    async fetchStatus() {
+        if (!this.subject.id) {
+            throw new Error("expecting agent id");
+        }
+        if (!this.id) {
+            return "not-started";
+        }
+        const url = `/agents/${this.subject.id}/tasks/${this.id}/metadata`;
+        const res = await this.client.fetch(url);
+        return stateToStatus(res.metadata.conversation.state);
+    }
+    /**
+     * Fetches messages from the conversation.
+     *
+     * @param {Object} [options] Optional fetch options.
+     * @param {Date} [options.from] Fetch messages after this timestamp.
+     *
+     * @returns {Promise<TaskMessage[]>} Array of messages in ascending order.
+     * @throws {Error} if the agent or task ID is missing.
+     */
+    async fetchMessages({ from = new Date(0) } = {}) {
+        if (!this.subject.id) {
+            throw new Error("expecting agent id");
+        }
+        if (!this.id) {
+            throw new Error("expecting task id");
+        }
+        const url = `/agents/${this.subject.id}/tasks/${this.id}/view`;
+        const res = await this.client.fetch(url, {
+            method: "POST",
+            body: JSON.stringify({
+                cursor: {
+                    after: from.toISOString(),
+                },
+            }),
+        });
+        // message should be in ascending order
+        return res.results.reverse().map((data) => new message_js_1.TaskMessage(data));
+    }
+}
+exports.AgentTask = AgentTask;

package/script/agent.d.ts

@@ -0,0 +1,17 @@
+import type { AgentTaskState } from "./agent-task.js";
+import { Client } from "./client.js";
+export declare class Agent {
+    #private;
+    private readonly client;
+    static fetch(agentId: string, cli?: Client): Promise<Agent>;
+    private constructor();
+    get id(): string;
+    get name(): string | undefined;
+    get description(): string | undefined;
+    get avatar(): string | undefined;
+    isPublic(): boolean;
+    trigger(message: string, taskId?: string): Promise<{
+        id: string;
+        state: AgentTaskState;
+    }>;
+}

package/script/agent.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const client_js_1 = require("./client.js");
+const utils_js_1 = require("./utils.js");
+const taskPrefixDelimiter = "_-_";
+class Agent {
+    #config;
+    client;
+    static async fetch(agentId, cli = client_js_1.Client.default()) {
+        const config = await cli.fetch(`/agents/${agentId}/get`);
+        return new Agent(config.agent, cli);
+    }
+    constructor(config, client) {
+        this.#config = config;
+        this.client = client;
+    }
+    get id() {
+        return this.#config.agent_id;
+    }
+    get name() {
+        return this.#config.name;
+    }
+    get description() {
+        return this.#config.description;
+    }
+    get avatar() {
+        return this.#config.emoji;
+    }
+    isPublic() {
+        return this.#config.public;
+    }
+    async trigger(message, taskId) {
+        // embed keys require a task prefixing for new tasks
+        if (!taskId && this.client.isEmbedKey()) {
+            taskId = [this.client.key.taskPrefix, await (0, utils_js_1.randomUUID)()].join(taskPrefixDelimiter);
+        }
+        const res = await this.client.fetch("/agents/trigger", {
+            method: "POST",
+            body: JSON.stringify({
+                agent_id: this.#config.agent_id,
+                conversation_id: taskId,
+                message: {
+                    role: "user",
+                    content: message,
+                    attachments: [], // @todo
+                },
+            }),
+        });
+        return {
+            id: res.conversation_id,
+            state: res.state,
+        };
+    }
+}
+exports.Agent = Agent;

package/script/client.d.ts

@@ -0,0 +1,36 @@
+import { Agent } from "./agent.js";
+import { type Region } from "./region.js";
+import { AgentTask } from "./agent-task.js";
+import { Key } from "./key.js";
+type CreateClientOptions = {
+    apiKey: string;
+    region: Region;
+    project: string;
+};
+/**
+ * Creates and returns the _default_ client instance.
+ *
+ * @throws {Error} if a default client already exists.
+ * @see {Client.default}
+ */
+export declare function createClient(keyOrOptions: Key | CreateClientOptions): Client;
+export declare class Client {
+    /**
+     * Returns the _default_ client instance.
+     *
+     * @throws {Error} if there is no default client.
+     * @see {createClient}
+     */
+    static default(): Client;
+    readonly key: Key;
+    private readonly baseURL;
+    constructor(key: Key);
+    get region(): Region;
+    get project(): string;
+    isEmbedKey(): boolean;
+    createTask({ agent }: {
+        agent: string | Agent;
+    }): Promise<AgentTask>;
+    fetch<T>(input: `/agents/trigger` | `/agents/${string}/get` | `/agents/${string}/tasks/${string}/metadata` | `/agents/${string}/tasks/${string}/view`, init?: RequestInit): Promise<T>;
+}
+export {};

package/script/client.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+exports.createClient = createClient;
+const agent_js_1 = require("./agent.js");
+const region_js_1 = require("./region.js");
+const agent_task_js_1 = require("./agent-task.js");
+const utils_js_1 = require("./utils.js");
+const key_js_1 = require("./key.js");
+let defaultClient;
+/**
+ * Creates and returns the _default_ client instance.
+ *
+ * @throws {Error} if a default client already exists.
+ * @see {Client.default}
+ */
+function createClient(keyOrOptions) {
+    if (defaultClient) {
+        throw new Error("default client already exists");
+    }
+    const key = keyOrOptions instanceof key_js_1.Key ? keyOrOptions : new key_js_1.Key({
+        key: keyOrOptions.apiKey,
+        region: keyOrOptions.region,
+        project: keyOrOptions.project,
+    });
+    defaultClient = new Client(key);
+    return defaultClient;
+}
+class Client {
+    /**
+     * Returns the _default_ client instance.
+     *
+     * @throws {Error} if there is no default client.
+     * @see {createClient}
+     */
+    static default() {
+        if (!defaultClient) {
+            throw new Error("no default client");
+        }
+        return defaultClient;
+    }
+    key;
+    baseURL;
+    constructor(key) {
+        this.key = key;
+        this.baseURL = (0, region_js_1.regionBaseURL)(this.key.region);
+    }
+    get region() {
+        return this.key.region;
+    }
+    get project() {
+        return this.key.project;
+    }
+    isEmbedKey() {
+        return this.key.isEmbed();
+    }
+    async createTask({ agent }) {
+        if (agent) {
+            return new agent_task_js_1.AgentTask(typeof agent === "string" ? await agent_js_1.Agent.fetch(agent) : agent, undefined, this);
+        }
+        throw new Error("task not implemented");
+    }
+    async fetch(input, init) {
+        const url = new URL((0, utils_js_1.cleanPath)(input), this.baseURL);
+        const headers = new Headers(this.key.fetchHeaders());
+        const response = await fetch(url, Object.assign({ headers }, init));
+        if (!response.ok) {
+            console.error(url, init, headers);
+            throw new Error(response.statusText);
+        }
+        return response.json();
+    }
+}
+exports.Client = Client;

package/script/events.d.ts

@@ -0,0 +1,40 @@
+import type { TaskMessage } from "./message.js";
+import type { TaskStatus } from "./task.js";
+export declare class TaskStartEvent extends CustomEvent<{
+    id: string;
+    status: TaskStatus;
+}> {
+    readonly type = "start";
+    constructor(id: string, status: TaskStatus);
+}
+export declare class TaskStatusEvent extends CustomEvent<{
+    status: TaskStatus;
+}> {
+    readonly type = "status";
+    constructor(status: TaskStatus);
+}
+export declare class TaskMessageEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "message";
+    constructor(message: TaskMessage);
+    isUserMessage(): boolean;
+}
+export declare class TaskUpdateEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "update";
+    constructor(message: TaskMessage);
+}
+export declare class TaskActionEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "action";
+    constructor(message: TaskMessage);
+}
+export declare class TaskErrorEvent extends CustomEvent<{
+    message: TaskMessage;
+}> {
+    readonly type = "error";
+    constructor(message: TaskMessage);
+}

package/script/events.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskErrorEvent = exports.TaskActionEvent = exports.TaskUpdateEvent = exports.TaskMessageEvent = exports.TaskStatusEvent = exports.TaskStartEvent = void 0;
+class TaskStartEvent extends CustomEvent {
+    type = "start";
+    constructor(id, status) {
+        super("start", { detail: { id, status } });
+    }
+}
+exports.TaskStartEvent = TaskStartEvent;
+class TaskStatusEvent extends CustomEvent {
+    type = "status";
+    constructor(status) {
+        super("status", { detail: { status } });
+    }
+}
+exports.TaskStatusEvent = TaskStatusEvent;
+class TaskMessageEvent extends CustomEvent {
+    type = "message";
+    constructor(message) {
+        super("message", { detail: { message } });
+    }
+    isUserMessage() {
+        return this.detail.message.type === "user-message";
+    }
+}
+exports.TaskMessageEvent = TaskMessageEvent;
+class TaskUpdateEvent extends CustomEvent {
+    type = "update";
+    constructor(message) {
+        super("update", { detail: { message } });
+    }
+}
+exports.TaskUpdateEvent = TaskUpdateEvent;
+class TaskActionEvent extends CustomEvent {
+    type = "action";
+    constructor(message) {
+        super("action", { detail: { message } });
+    }
+}
+exports.TaskActionEvent = TaskActionEvent;
+class TaskErrorEvent extends CustomEvent {
+    type = "error";
+    constructor(message) {
+        super("error", { detail: { message } });
+    }
+}
+exports.TaskErrorEvent = TaskErrorEvent;

package/script/key.d.ts

@@ -0,0 +1,86 @@
+import type { Region } from "./mod.js";
+type CreateKeyOptions = {
+    key: string;
+    region: Region;
+    project: string;
+    agentId?: string;
+    taskPrefix?: string;
+};
+type GenerateEmbedKeyOptions = Omit<CreateKeyOptions, "key" | "taskPrefix">;
+/**
+ * Key is used to authenticate requests for the {@link Client}. A Key can be
+ * either a _full_ key or an _embed_ key.
+ *
+ * A full key has access to SDK features. An embed key is scoped to a specific
+ * agent and is only used to create and interact with tasks for that agent.
+ *
+ * @see {@link Key.generateEmbedKey} to generate an embed key for a specific agent.
+ *
+ * @class Key
+ */
+export declare class Key {
+    #private;
+    /**
+     * Generates an embed key for the specified agent. The embed key can then be
+     * used to create a {@link Client} instance that can create and interact with
+     * tasks for that agent.
+     *
+     * @throws {Error} if the request to generate an embed key fails.
+     *
+     * @param {GenerateEmbedKeyOptions} options The generation options.
+     *
+     * @returns {Promise<Key>}
+     */
+    static generateEmbedKey({ region, project, agentId, }: GenerateEmbedKeyOptions): Promise<Key>;
+    /**
+     * The region the key is scoped to.
+     *
+     * @property {string} region
+     */
+    readonly region: Region;
+    /**
+     * The project the key is scoped to.
+     *
+     * @property {string} project
+     */
+    readonly project: string;
+    /**
+     * The agent ID the embed key is scoped to. This is `undefined` for full
+     * keys.
+     *
+     * @property {string | undefined} agentId
+     */
+    readonly agentId: string | undefined;
+    /**
+     * The task prefix used to namespace tasks created with the embed key. This
+     * is `undefined` for full keys.
+     *
+     * @property {string | undefined} taskPrefix
+     */
+    readonly taskPrefix: string | undefined;
+    /**
+     * Creates a new {@link Key} instance with the provided options.
+     *
+     * @param {CreateKeyOptions} options
+     */
+    constructor({ key, region, project, agentId, taskPrefix }: CreateKeyOptions);
+    /**
+     * Returns whether the key is an embed key.
+     *
+     * @returns {boolean}
+     */
+    isEmbed(): boolean;
+    /**
+     * Returns the headers required for authenticating requests with this key.
+     *
+     * @returns {HeadersInit}
+     */
+    fetchHeaders(): HeadersInit;
+    /**
+     * Returns a JSON representation of the key.
+     *
+     * @returns {CreateKeyOptions}
+     */
+    toJSON(): CreateKeyOptions;
+}
+export {};

package/script/key.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Key = void 0;
+const region_js_1 = require("./region.js");
+const utils_js_1 = require("./utils.js");
+/**
+ * Key is used to authenticate requests for the {@link Client}. A Key can be
+ * either a _full_ key or an _embed_ key.
+ *
+ * A full key has access to SDK features. An embed key is scoped to a specific
+ * agent and is only used to create and interact with tasks for that agent.
+ *
+ * @see {@link Key.generateEmbedKey} to generate an embed key for a specific agent.
+ *
+ * @class Key
+ */
+class Key {
+    /**
+     * Generates an embed key for the specified agent. The embed key can then be
+     * used to create a {@link Client} instance that can create and interact with
+     * tasks for that agent.
+     *
+     * @throws {Error} if the request to generate an embed key fails.
+     *
+     * @param {GenerateEmbedKeyOptions} options The generation options.
+     *
+     * @returns {Promise<Key>}
+     */
+    static async generateEmbedKey({ region, project, agentId, }) {
+        const embedKeyURL = new URL((0, utils_js_1.cleanPath)("/agents/get_embed_key"), (0, region_js_1.regionBaseURL)(region));
+        const response = await fetch(embedKeyURL, {
+            method: "POST",
+            body: JSON.stringify({ agent_id: agentId, project }),
+        });
+        if (!response.ok) {
+            throw new Error("failed to fetch embed key", { cause: response });
+        }
+        const { embed_key: embedKey, conversation_prefix: taskPrefix } = await response.json();
+        return new Key({
+            key: embedKey,
+            region,
+            project,
+            agentId,
+            taskPrefix,
+        });
+    }
+    /**
+     * The region the key is scoped to.
+     *
+     * @property {string} region
+     */
+    region;
+    /**
+     * The project the key is scoped to.
+     *
+     * @property {string} project
+     */
+    project;
+    /**
+     * The API key used for authentication.
+     *
+     * @private
+     * @property {string} key
+     */
+    #key;
+    /**
+     * The agent ID the embed key is scoped to. This is `undefined` for full
+     * keys.
+     *
+     * @property {string | undefined} agentId
+     */
+    agentId;
+    /**
+     * The task prefix used to namespace tasks created with the embed key. This
+     * is `undefined` for full keys.
+     *
+     * @property {string | undefined} taskPrefix
+     */
+    taskPrefix;
+    /**
+     * Creates a new {@link Key} instance with the provided options.
+     *
+     * @param {CreateKeyOptions} options
+     */
+    constructor({ key, region, project, agentId, taskPrefix }) {
+        this.#key = key;
+        this.region = region;
+        this.project = project;
+        this.agentId = agentId;
+        this.taskPrefix = taskPrefix;
+    }
+    /**
+     * Returns whether the key is an embed key.
+     *
+     * @returns {boolean}
+     */
+    isEmbed() {
+        return (this.agentId !== undefined && this.taskPrefix !== undefined);
+    }
+    /**
+     * Returns the headers required for authenticating requests with this key.
+     *
+     * @returns {HeadersInit}
+     */
+    fetchHeaders() {
+        return {
+            Authorization: `${this.project}:${this.#key}`,
+        };
+    }
+    /**
+     * Returns a JSON representation of the key.
+     *
+     * @returns {CreateKeyOptions}
+     */
+    toJSON() {
+        return {
+            key: this.#key,
+            region: this.region,
+            project: this.project,
+            agentId: this.agentId,
+            taskPrefix: this.taskPrefix,
+        };
+    }
+}
+exports.Key = Key;

package/script/message.d.ts

@@ -0,0 +1,18 @@
+type TaskMessageType = "user-message" | "agent-message" | "tool-run" | "agent-error";
+export type MessageData = {
+    item_id: string;
+    insert_date_: string;
+    content: {
+        type: TaskMessageType;
+        text: string;
+    };
+};
+export declare class TaskMessage<T extends TaskMessageType = TaskMessageType> {
+    #private;
+    constructor(data: MessageData);
+    get id(): string;
+    get type(): T;
+    get createdAt(): Date;
+    get text(): string;
+}
+export {};

package/script/message.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskMessage = void 0;
+class TaskMessage {
+    #data;
+    constructor(data) {
+        this.#data = data;
+    }
+    get id() {
+        return this.#data.item_id;
+    }
+    get type() {
+        return this.#data.content.type;
+    }
+    get createdAt() {
+        return new Date(this.#data.insert_date_);
+    }
+    get text() {
+        return this.#data.content.text;
+    }
+}
+exports.TaskMessage = TaskMessage;

package/script/mod.d.ts

@@ -0,0 +1,7 @@
+export { Agent } from "./agent.js";
+export { Client, createClient } from "./client.js";
+export { Key } from "./key.js";
+export { type Region, REGION_AU, REGION_EU, REGION_US } from "./region.js";
+export type { AgentTask } from "./agent-task.js";
+export type { TaskMessage } from "./message.js";
+export type { Task, TaskStatus } from "./task.js";

package/script/mod.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGION_US = exports.REGION_EU = exports.REGION_AU = exports.Key = exports.createClient = exports.Client = exports.Agent = void 0;
+var agent_js_1 = require("./agent.js");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return agent_js_1.Agent; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_js_1.createClient; } });
+var key_js_1 = require("./key.js");
+Object.defineProperty(exports, "Key", { enumerable: true, get: function () { return key_js_1.Key; } });
+var region_js_1 = require("./region.js");
+Object.defineProperty(exports, "REGION_AU", { enumerable: true, get: function () { return region_js_1.REGION_AU; } });
+Object.defineProperty(exports, "REGION_EU", { enumerable: true, get: function () { return region_js_1.REGION_EU; } });
+Object.defineProperty(exports, "REGION_US", { enumerable: true, get: function () { return region_js_1.REGION_US; } });

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/region.d.ts

@@ -0,0 +1,5 @@
+export type Region = "bcbe5a" | "d7b62b" | "f1db6c";
+export declare const REGION_US = "bcbe5a";
+export declare const REGION_EU = "d7b62b";
+export declare const REGION_AU = "f1db6c";
+export declare function regionBaseURL(region: Region): string;

package/script/region.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGION_AU = exports.REGION_EU = exports.REGION_US = void 0;
+exports.regionBaseURL = regionBaseURL;
+exports.REGION_US = "bcbe5a";
+exports.REGION_EU = "d7b62b";
+exports.REGION_AU = "f1db6c";
+function regionBaseURL(region) {
+    return `https://api-${region}.stack.tryrelevance.com`;
+}

package/script/task.d.ts

@@ -0,0 +1,25 @@
+import { Client } from "./client.js";
+import type { TaskMessage } from "./message.js";
+export type TaskStatus = "not-started" | "idle" | "queued" | "running" | "action" | "complete" | "error";
+export declare abstract class Task<S, E extends Record<string, unknown>> extends EventTarget {
+    #private;
+    readonly subject: S;
+    protected readonly client: Client;
+    private listenController;
+    abstract fetchMessages(fetchOptions?: {
+        from?: Date;
+    }): Promise<TaskMessage[]>;
+    abstract fetchStatus(): Promise<TaskStatus>;
+    constructor(subject: S, id?: string | undefined, client?: Client);
+    get id(): string | undefined;
+    protected setId(id: string, status?: TaskStatus): void;
+    listen(): void;
+    isListening(): boolean;
+    stopListening(): void;
+    addEventListener<K extends keyof E>(type: Extract<K, string>, listener: ((event: CustomEvent<E[K]>) => void) | {
+        handleEvent: (event: CustomEvent<E[K]>) => void;
+    } | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof E>(type: Extract<K, string>, listener: ((event: CustomEvent<E[K]>) => void) | {
+        handleEvent: (event: CustomEvent<E[K]>) => void;
+    } | null, options?: boolean | AddEventListenerOptions): void;
+}

package/script/task.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Task = void 0;
+const client_js_1 = require("./client.js");
+const events_js_1 = require("./events.js");
+const utils_js_1 = require("./utils.js");
+class Task extends EventTarget {
+    subject;
+    client;
+    #id;
+    listenController;
+    constructor(subject, id = undefined, client = client_js_1.Client.default()) {
+        super();
+        this.subject = subject;
+        this.client = client;
+        this.#id = id;
+    }
+    get id() {
+        return this.#id;
+    }
+    setId(id, status = "not-started") {
+        if (this.#id) {
+            throw new Error("task id is already set");
+        }
+        // @ts-ignore: allow assignment to readonly in this special case
+        this.#id = id;
+        this.dispatchEvent(new events_js_1.TaskStartEvent(id, status));
+    }
+    listen() {
+        if (this.isListening()) {
+            return;
+        }
+        this.listenController = new AbortController();
+        const signal = this.listenController.signal;
+        let currentStatus = null;
+        const messagesCursor = new Date(0);
+        void (0, utils_js_1.runInterval)(async () => {
+            // no task, yet
+            if (!this.id) {
+                return;
+            }
+            const [status, messages] = await Promise.all([
+                this.fetchStatus(),
+                this.fetchMessages({
+                    from: messagesCursor,
+                }),
+            ]);
+            if (!this.isListening()) {
+                return;
+            }
+            if (status !== currentStatus) {
+                currentStatus = status;
+                this.dispatchEvent(new events_js_1.TaskStatusEvent(status));
+            }
+            if (messages.length) {
+                for (const message of messages) {
+                    switch (message.type) {
+                        case "agent-error":
+                            this.dispatchEvent(new events_js_1.TaskErrorEvent(message));
+                            break;
+                        case "tool-run":
+                            this.dispatchEvent(new events_js_1.TaskUpdateEvent(message));
+                            break;
+                        case "agent-message":
+                        case "user-message":
+                            this.dispatchEvent(new events_js_1.TaskMessageEvent(message));
+                    }
+                }
+                messagesCursor.setTime(
+                // +1 the api treats after inclusively
+                messages.at(-1).createdAt.getTime() + 1);
+            }
+        }, 15_000, { signal });
+    }
+    isListening() {
+        return this.listenController !== undefined;
+    }
+    stopListening() {
+        this.listenController?.abort();
+        this.listenController = undefined;
+    }
+    addEventListener(type, listener, options) {
+        this.listen();
+        const signal = AbortSignal.any([
+            ...(options && typeof options === "object" && options.signal
+                ? [options.signal]
+                : []),
+            this.listenController.signal,
+        ]);
+        const capture = typeof options === "boolean"
+            ? options
+            : Boolean(options?.capture);
+        const addOptions = Object.assign({}, options, { signal, capture });
+        super.addEventListener(type, listener, addOptions);
+    }
+    removeEventListener(type, listener, options) {
+        super.removeEventListener(type, listener, options);
+    }
+}
+exports.Task = Task;

package/script/utils.d.ts

@@ -0,0 +1,8 @@
+export declare function abortPromise(signal: AbortSignal, reject?: boolean): Promise<void>;
+export declare function delay(timeout: number): Promise<void>;
+export declare function runInterval(runner: () => Promise<void> | void, interval: number, { signal, }?: {
+    signal?: AbortSignal;
+    immediate?: boolean;
+}): Promise<void>;
+export declare function cleanPath(path: string, version?: string): string;
+export declare function randomUUID(): Promise<any>;

package/script/utils.js

@@ -0,0 +1,69 @@
+"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.abortPromise = abortPromise;
+exports.delay = delay;
+exports.runInterval = runInterval;
+exports.cleanPath = cleanPath;
+exports.randomUUID = randomUUID;
+function abortPromise(signal, reject) {
+    return new Promise((res, rej) => signal.addEventListener("abort", () => reject ? rej() : res()));
+}
+function delay(timeout) {
+    return new Promise((done) => setTimeout(done, timeout));
+}
+async function runInterval(runner, interval, { signal, } = {}) {
+    while (true) {
+        if (signal?.aborted) {
+            break;
+        }
+        await runner();
+        await Promise.race([
+            delay(interval),
+            signal ? abortPromise(signal) : new Promise(() => { }),
+        ]);
+    }
+}
+function cleanPath(path, version = "latest") {
+    return `/${version}/${path.trim().replace(/^\/+/, "")}`;
+}
+async function randomUUID() {
+    if (typeof crypto !== "undefined") {
+        return crypto.randomUUID();
+    }
+    // @ts-ignore allow this import for node builds
+    const cryptoModule = await Promise.resolve().then(() => __importStar(require("node:crypto")));
+    return cryptoModule.randomUUID();
+}