@relevanceai/sdk 2.0.2 → 3.0.0-alpha.1

package/esm/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/esm/client.js

@@ -0,0 +1,69 @@
+import { Agent } from "./agent.js";
+import { regionBaseURL } from "./region.js";
+import { AgentTask } from "./agent-task.js";
+import { cleanPath } from "./utils.js";
+import { Key } from "./key.js";
+let defaultClient;
+/**
+ * Creates and returns the _default_ client instance.
+ *
+ * @throws {Error} if a default client already exists.
+ * @see {Client.default}
+ */
+export function createClient(keyOrOptions) {
+    if (defaultClient) {
+        throw new Error("default client already exists");
+    }
+    const key = keyOrOptions instanceof Key ? keyOrOptions : new Key({
+        key: keyOrOptions.apiKey,
+        region: keyOrOptions.region,
+        project: keyOrOptions.project,
+    });
+    defaultClient = new Client(key);
+    return defaultClient;
+}
+export 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 = 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 AgentTask(typeof agent === "string" ? await Agent.fetch(agent) : agent, undefined, this);
+        }
+        throw new Error("task not implemented");
+    }
+    async fetch(input, init) {
+        const url = new URL(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();
+    }
+}

package/esm/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/esm/events.js

@@ -0,0 +1,39 @@
+export class TaskStartEvent extends CustomEvent {
+    type = "start";
+    constructor(id, status) {
+        super("start", { detail: { id, status } });
+    }
+}
+export class TaskStatusEvent extends CustomEvent {
+    type = "status";
+    constructor(status) {
+        super("status", { detail: { status } });
+    }
+}
+export class TaskMessageEvent extends CustomEvent {
+    type = "message";
+    constructor(message) {
+        super("message", { detail: { message } });
+    }
+    isUserMessage() {
+        return this.detail.message.type === "user-message";
+    }
+}
+export class TaskUpdateEvent extends CustomEvent {
+    type = "update";
+    constructor(message) {
+        super("update", { detail: { message } });
+    }
+}
+export class TaskActionEvent extends CustomEvent {
+    type = "action";
+    constructor(message) {
+        super("action", { detail: { message } });
+    }
+}
+export class TaskErrorEvent extends CustomEvent {
+    type = "error";
+    constructor(message) {
+        super("error", { detail: { message } });
+    }
+}

package/esm/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/esm/key.js

@@ -0,0 +1,121 @@
+import { regionBaseURL } from "./region.js";
+import { cleanPath } from "./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
+ */
+export 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(cleanPath("/agents/get_embed_key"), 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,
+        };
+    }
+}

package/esm/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/esm/message.js

@@ -0,0 +1,18 @@
+export 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;
+    }
+}

package/esm/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/esm/mod.js

@@ -0,0 +1,4 @@
+export { Agent } from "./agent.js";
+export { Client, createClient } from "./client.js";
+export { Key } from "./key.js";
+export { REGION_AU, REGION_EU, REGION_US } from "./region.js";

package/esm/package.json

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

package/esm/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/esm/region.js

@@ -0,0 +1,6 @@
+export const REGION_US = "bcbe5a";
+export const REGION_EU = "d7b62b";
+export const REGION_AU = "f1db6c";
+export function regionBaseURL(region) {
+    return `https://api-${region}.stack.tryrelevance.com`;
+}

package/esm/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/esm/task.js

@@ -0,0 +1,96 @@
+import { Client } from "./client.js";
+import { TaskErrorEvent, TaskMessageEvent, TaskStartEvent, TaskStatusEvent, TaskUpdateEvent, } from "./events.js";
+import { runInterval } from "./utils.js";
+export class Task extends EventTarget {
+    subject;
+    client;
+    #id;
+    listenController;
+    constructor(subject, id = undefined, client = 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 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 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 TaskStatusEvent(status));
+            }
+            if (messages.length) {
+                for (const message of messages) {
+                    switch (message.type) {
+                        case "agent-error":
+                            this.dispatchEvent(new TaskErrorEvent(message));
+                            break;
+                        case "tool-run":
+                            this.dispatchEvent(new TaskUpdateEvent(message));
+                            break;
+                        case "agent-message":
+                        case "user-message":
+                            this.dispatchEvent(new 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);
+    }
+}

package/esm/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/esm/utils.js

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

package/package.json

@@ -1,38 +1,13 @@
 {
   "name": "@relevanceai/sdk",
-  "version": "2.0.2",
-  "description": "Javascript client for RelevanceAI APIs. Browser, Node.js and typescript support.",
-  "main": "./dist-cjs/index.js",
-  "types": "./dist-types/index.d.ts",
-  "module": "./dist-es/index.js",
-  "files": [
-    "dist-*"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json && tsc -p tsconfig.es.json && tsc -p tsconfig.types.json",
-    "generate": "ts-node ./src/shared/generate.ts",
-    "test": "jest",
-    "prepare": "npm run build",
-    "sample": "ts-node ./test/sample.test.mjs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/RelevanceAI/relevance-js-sdk.git"
-  },
-  "author": "",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/RelevanceAI/relevance-js-sdk/issues"
-  },
-  "homepage": "https://github.com/RelevanceAI/relevance-js-sdk#readme",
-  "devDependencies": {
-    "@types/jest": "^27.0.2",
-    "openapi-typescript": "^4.4.0",
-    "ts-jest": "^27.0.7",
-    "ts-node": "^10.4.0",
-    "typescript": "^4.4.4"
-  },
-  "dependencies": {
-    "cross-fetch": "^3.1.4"
-  }
-}
+  "version": "3.0.0-alpha.1",
+  "license": "MIT",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js"
+    }
+  },
+  "scripts": {},
+  "_generatedBy": "dnt@dev"
+}