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

package/script/emitter.d.ts

@@ -0,0 +1,16 @@
+export type EventMap = Record<string, unknown>;
+/**
+ * Emitter
+ *
+ * Abstraction for type-assisting event targets.
+ *
+ * @internal
+ */
+export declare abstract class Emitter<M extends EventMap = Record<string, never>> extends EventTarget {
+    addEventListener<K extends keyof M>(type: Extract<K, string>, listener: ((event: CustomEvent<M[K]>) => void) | {
+        handleEvent: (event: CustomEvent<M[K]>) => void;
+    } | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof M>(type: Extract<K, string>, listener: ((event: CustomEvent<M[K]>) => void) | {
+        handleEvent: (event: CustomEvent<M[K]>) => void;
+    } | null, options?: boolean | AddEventListenerOptions): void;
+}

package/script/emitter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Emitter = void 0;
+/**
+ * Emitter
+ *
+ * Abstraction for type-assisting event targets.
+ *
+ * @internal
+ */
+class Emitter extends EventTarget {
+    addEventListener(type, listener, options) {
+        super.addEventListener(type, listener, options);
+    }
+    removeEventListener(type, listener, options) {
+        super.removeEventListener(type, listener, options);
+    }
+}
+exports.Emitter = Emitter;

package/script/event.d.ts

@@ -0,0 +1,37 @@
+import type { AgentErrorMessage } from "./message/agent-error.js";
+import type { AgentMessage } from "./message/agent.js";
+import type { ToolMessage } from "./message/tool.js";
+import type { UserMessage } from "./message/user.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: AgentMessage | UserMessage;
+}> {
+    readonly type = "message";
+    constructor(message: AgentMessage | UserMessage);
+    isUserMessage(): boolean;
+}
+export declare class TaskUpdateEvent extends CustomEvent<{
+    message: ToolMessage;
+}> {
+    readonly type = "update";
+    constructor(message: ToolMessage);
+}
+export declare class TaskErrorEvent extends CustomEvent<{
+    message: AgentErrorMessage;
+}> {
+    readonly type = "error";
+    constructor(message: AgentErrorMessage);
+}

package/script/event.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskErrorEvent = 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 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/agent-error.d.ts

@@ -0,0 +1,6 @@
+import { TaskMessage } from "./task.js";
+export interface AgentErrorMessageContent {
+    type: "agent-error";
+}
+export declare class AgentErrorMessage extends TaskMessage<AgentErrorMessageContent> {
+}

package/script/message/agent-error.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentErrorMessage = void 0;
+const task_js_1 = require("./task.js");
+class AgentErrorMessage extends task_js_1.TaskMessage {
+}
+exports.AgentErrorMessage = AgentErrorMessage;

package/script/message/agent.d.ts

@@ -0,0 +1,9 @@
+import { TaskMessage } from "./task.js";
+export interface AgentMessageContent {
+    type: "agent-message";
+    text: string;
+}
+export declare class AgentMessage extends TaskMessage<AgentMessageContent> {
+    get text(): string;
+    get agentId(): string;
+}

package/script/message/agent.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentMessage = void 0;
+const task_js_1 = require("./task.js");
+class AgentMessage extends task_js_1.TaskMessage {
+    get text() {
+        return this.message.content.text;
+    }
+    get agentId() {
+        return "";
+    }
+}
+exports.AgentMessage = AgentMessage;

package/script/message/task.d.ts

@@ -0,0 +1,42 @@
+import type { AgentMessage } from "./agent.js";
+import type { AgentErrorMessage } from "./agent-error.js";
+import type { ToolMessage } from "./tool.js";
+import type { UserMessage } from "./user.js";
+export type AnyTaskMessage = AgentMessage | AgentErrorMessage | ToolMessage | UserMessage;
+interface MessageContent {
+    type: AnyTaskMessage["type"];
+}
+export interface TaskMessageData<C extends MessageContent = MessageContent> {
+    item_id: string;
+    insert_date_: string;
+    content: C;
+}
+export declare abstract class TaskMessage<C extends MessageContent = MessageContent> {
+    protected readonly message: TaskMessageData<C>;
+    constructor(message: TaskMessageData<C>);
+    /**
+     * The task's message type.
+     *
+     * @property {"agent-error" | "agent-message" | "tool-run" | "user-message"}
+     */
+    get type(): C["type"];
+    /**
+     * The task message ID. Used for referencing the message.
+     *
+     * @property {string}
+     */
+    get id(): string;
+    /**
+     * The time the task was created.
+     *
+     * @property {Date}
+     */
+    get createdAt(): Date;
+    /**
+     * Returns if the message was sent from the agent.
+     *
+     * @returns {boolean}
+     */
+    isAgent(): boolean;
+}
+export {};

package/script/message/task.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskMessage = void 0;
+class TaskMessage {
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+    /**
+     * The task's message type.
+     *
+     * @property {"agent-error" | "agent-message" | "tool-run" | "user-message"}
+     */
+    get type() {
+        return this.message.content.type;
+    }
+    /**
+     * The task message ID. Used for referencing the message.
+     *
+     * @property {string}
+     */
+    get id() {
+        return this.message.item_id;
+    }
+    /**
+     * The time the task was created.
+     *
+     * @property {Date}
+     */
+    get createdAt() {
+        return new Date(this.message.insert_date_);
+    }
+    /**
+     * Returns if the message was sent from the agent.
+     *
+     * @returns {boolean}
+     */
+    isAgent() {
+        return this.type === "agent-message";
+    }
+}
+exports.TaskMessage = TaskMessage;

package/script/message/tool.d.ts

@@ -0,0 +1,108 @@
+import type { Region } from "../region.js";
+import { TaskMessage } from "./task.js";
+export interface ToolMessageContent {
+    type: "tool-run";
+    tool_run_state: "cancelled" | "error" | "finished" | "pending" | "running";
+    output: Record<string, unknown> & {
+        _agent_conversation_details?: {
+            agent_id: string;
+            conversation_id: string;
+        };
+    };
+    params: {
+        resolved?: Record<string, unknown>;
+        valid: boolean;
+    };
+    errors: {
+        body: string;
+        raw: string;
+        step_name: string;
+    }[];
+    tool_config: {
+        id: string;
+        type: "tool" | "agent";
+        region: Region;
+        project: string;
+    };
+}
+export declare class ToolMessage extends TaskMessage<ToolMessageContent> {
+    /**
+     * The tool status for _this_ message.
+     *
+     * @property {"cancelled" | "error" | "finished" | "pending" | "running"}
+     */
+    get status(): "cancelled" | "error" | "finished" | "pending" | "running";
+    /**
+     * Parameters used to call the tool.
+     *
+     * @property {object}
+     */
+    get params(): Record<string, unknown> | null;
+    /**
+     * The tool's output. Will be `null` if the status is **not** "finished".
+     *
+     * @property {object|null}
+     */
+    get output(): Record<string, unknown> | null;
+    /**
+     * Tool errors.
+     *
+     * @property {array}
+     * @see {@link ToolMessage#hasErrors}
+     */
+    get errors(): {
+        stepName: string;
+        message: string;
+    }[];
+    /**
+     * The tool's ID.
+     *
+     * @property {string}
+     */
+    get toolId(): string;
+    /**
+     * The agent's ID, if a sub-agent.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get agentId(): string | null;
+    /**
+     * The tool/agent's corresponding project.
+     *
+     * @property {string}
+     */
+    get project(): string;
+    /**
+     * The tool/agent's corresponding region.
+     *
+     * @property {Region}
+     */
+    get region(): Region;
+    /**
+     * The task ID the sub-agent ran. Will be `null` if the tool message is not
+     * a sub-agent.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get subAgentTaskId(): string | null;
+    /**
+     * Checks if the tool message came from a sub-agent.
+     *
+     * @returns {boolean}
+     */
+    isSubAgent(): boolean;
+    /**
+     * Checks if the tool call parameters where valid.
+     *
+     * @returns {boolean}
+     */
+    areParamsValid(): boolean;
+    /**
+     * Returns if the tool message has any errors.
+     *
+     * @returns {boolean}
+     */
+    hasErrors(): boolean;
+}

package/script/message/tool.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolMessage = void 0;
+const task_js_1 = require("./task.js");
+class ToolMessage extends task_js_1.TaskMessage {
+    /**
+     * The tool status for _this_ message.
+     *
+     * @property {"cancelled" | "error" | "finished" | "pending" | "running"}
+     */
+    get status() {
+        return this.message.content.tool_run_state;
+    }
+    /**
+     * Parameters used to call the tool.
+     *
+     * @property {object}
+     */
+    get params() {
+        return this.message.content.params.resolved ?? null;
+    }
+    /**
+     * The tool's output. Will be `null` if the status is **not** "finished".
+     *
+     * @property {object|null}
+     */
+    get output() {
+        return this.status === "finished" ? this.message.content.output : null;
+    }
+    /**
+     * Tool errors.
+     *
+     * @property {array}
+     * @see {@link ToolMessage#hasErrors}
+     */
+    get errors() {
+        return this.message.content.errors.map((e) => ({
+            stepName: e.step_name,
+            message: e.body,
+        }));
+    }
+    /**
+     * The tool's ID.
+     *
+     * @property {string}
+     */
+    get toolId() {
+        return this.message.content.tool_config.id;
+    }
+    /**
+     * The agent's ID, if a sub-agent.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get agentId() {
+        return this.isSubAgent()
+            ? this.message.content.output._agent_conversation_details?.agent_id
+            : null;
+    }
+    /**
+     * The tool/agent's corresponding project.
+     *
+     * @property {string}
+     */
+    get project() {
+        return this.message.content.tool_config.project;
+    }
+    /**
+     * The tool/agent's corresponding region.
+     *
+     * @property {Region}
+     */
+    get region() {
+        return this.message.content.tool_config.region;
+    }
+    /**
+     * The task ID the sub-agent ran. Will be `null` if the tool message is not
+     * a sub-agent.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get subAgentTaskId() {
+        return this.message.content.output._agent_conversation_details
+            ?.conversation_id ?? null;
+    }
+    /**
+     * Checks if the tool message came from a sub-agent.
+     *
+     * @returns {boolean}
+     */
+    isSubAgent() {
+        return this.message.content.tool_config.type === "agent";
+    }
+    /**
+     * Checks if the tool call parameters where valid.
+     *
+     * @returns {boolean}
+     */
+    areParamsValid() {
+        return this.message.content.params.valid;
+    }
+    /**
+     * Returns if the tool message has any errors.
+     *
+     * @returns {boolean}
+     */
+    hasErrors() {
+        return this.message.content.errors.length > 0;
+    }
+}
+exports.ToolMessage = ToolMessage;

package/script/message/user.d.ts

@@ -0,0 +1,20 @@
+import { TaskMessage } from "./task.js";
+export interface UserMessageContent {
+    type: "user-message";
+    text: string;
+    is_trigger_message: boolean;
+}
+export declare class UserMessage extends TaskMessage<UserMessageContent> {
+    /**
+     * The message as text sent.
+     *
+     * @property {string} text
+     */
+    get text(): string;
+    /**
+     * Returns if the message triggered a subject.
+     *
+     * @returns {boolean}
+     */
+    isTrigger(): boolean;
+}