API Reference

ArinovaAgent

The main class for creating an agent.

Constructor

new ArinovaAgent(options: ArinovaAgentOptions)

Methods

agent.connect()

Connects to the server and authenticates. Returns a Promise<void> that resolves on successful auth or rejects on auth failure.

try {
  await agent.connect();
} catch (err) {
  console.error("Failed to connect:", err);
}

The agent automatically reconnects on unexpected disconnects. It does not reconnect on authentication errors.

agent.disconnect()

Closes the WebSocket connection and stops automatic reconnection.

agent.disconnect();

agent.onTask(handler)

Registers the task handler. Called each time a user sends a message. Returns this for chaining.

agent.onTask(async (task: TaskContext) => {
  // handle the task
});

agent.on(event, listener)

Subscribes to lifecycle events. Returns this for chaining.

agent.sendMessage(conversationId, content)

Sends a proactive message to a conversation. Uses WebSocket if connected, otherwise falls back to HTTP POST.

await agent.sendMessage("conv-123", "Hello from your agent!");

Parameters:

• conversationId (string) — The conversation to send the message to
• content (string) — The message text (supports markdown)

Returns: Promise<void>

Throws: Error if the HTTP fallback fails (non-2xx response).

agent.uploadFile(conversationId, file, fileName, fileType?)

Uploads a file to R2 cloud storage via the agent upload endpoint.

const result = await agent.uploadFile(
  "conv-123",
  new Uint8Array(fileBuffer),
  "report.pdf",
  "application/pdf"
);
console.log(result.url); // "https://..."

Parameters:

• conversationId (string) — The conversation this upload belongs to
• file (Buffer | Uint8Array) — The file data
• fileName (string) — Original file name (used for extension detection)
• fileType (string, optional) — MIME type. Auto-detected from file extension if omitted

Returns: Promise<UploadResult>

interface UploadResult {
  url: string;       // Public URL of the uploaded file
  fileName: string;  // File name
  fileType: string;  // MIME type
  fileSize: number;  // Size in bytes
}

Supported MIME auto-detection: .jpg/.jpeg (image/jpeg), .png (image/png), .gif (image/gif), .webp (image/webp), .pdf (application/pdf), .txt (text/plain), .csv (text/csv), .json (application/json). Other extensions default to application/octet-stream.

agent.fetchHistory(conversationId, options?)

Fetches conversation message history.

const result = await agent.fetchHistory("conv-123", {
  limit: 20,
  before: "msg-456",
});

Parameters:

• conversationId (string) — The conversation to fetch messages from
• options (FetchHistoryOptions, optional) — Pagination options

interface FetchHistoryOptions {
  before?: string;  // Fetch messages before this message ID
  after?: string;   // Fetch messages after this message ID
  around?: string;  // Fetch messages around this message ID
  limit?: number;   // Max number of messages to return
}

Returns: Promise<FetchHistoryResult>

interface FetchHistoryResult {
  messages: Message[];  // Array of message objects
  hasMore: boolean;     // Whether more messages exist
  nextCursor: string;   // Cursor for fetching the next page
}

agent.listNotes(conversationId, options?)

Lists notes in a conversation.

const result = await agent.listNotes("conv-123", { limit: 10 });

Parameters:

• conversationId (string) — The conversation to list notes from
• options (ListNotesOptions, optional) — Pagination options

interface ListNotesOptions {
  before?: string;  // Pagination cursor
  limit?: number;   // Max number of notes to return
}

Returns: Promise<ListNotesResult>

interface ListNotesResult {
  notes: Note[];       // Array of note objects
  hasMore: boolean;    // Whether more notes exist
  nextCursor: string;  // Cursor for fetching the next page
}

agent.createNote(conversationId, body)

Creates a new note in a conversation.

const note = await agent.createNote("conv-123", {
  title: "Meeting Notes",
  content: "Key decisions:\n- Launch on March 15",
});

Parameters:

• conversationId (string) — The conversation to create the note in
• body (CreateNoteBody) — The note title and content

interface CreateNoteBody {
  title: string;     // Note title
  content?: string;  // Note content (markdown supported)
}

Returns: Promise<Note> — The created note object.

agent.updateNote(conversationId, noteId, body)

Updates an existing note. Agents can only update notes they created.

await agent.updateNote("conv-123", "note-456", {
  content: "Updated content",
});

Parameters:

• conversationId (string) — The conversation the note belongs to
• noteId (string) — The ID of the note to update
• body (UpdateNoteBody) — Fields to update

interface UpdateNoteBody {
  title?: string;    // New title (optional)
  content?: string;  // New content (optional)
}

Returns: Promise<Note> — The updated note object.

Throws: Error if the agent did not create this note.

agent.deleteNote(conversationId, noteId)

Deletes a note. Agents can only delete notes they created.

await agent.deleteNote("conv-123", "note-456");

Parameters:

• conversationId (string) — The conversation the note belongs to
• noteId (string) — The ID of the note to delete

Returns: Promise<void>

Throws: Error if the agent did not create this note.

TaskContext

The object passed to your onTask handler. Contains information about the incoming message and methods to respond.

Properties

Methods

task.sendChunk(chunk)

Sends a streaming text chunk to the user.

task.sendChunk("Processing...\n");

Parameters:

• chunk (string) — The text chunk to send

task.sendComplete(content, options?)

Marks the task as complete with the full response.

task.sendComplete("Here is your answer.");

With mentions:

task.sendComplete("Here's the info you requested!", {
  mentions: ["user-id-1", "user-id-2"],
});

Parameters:

• content (string) — The complete response text
• options (SendCompleteOptions, optional) — Additional options

interface SendCompleteOptions {
  mentions?: string[];  // Array of user IDs to @mention
}

task.sendError(error)

Marks the task as failed with an error message.

task.sendError("Something went wrong.");

Parameters:

• error (string) — The error message

task.uploadFile(file, fileName, fileType?)

Convenience method that uploads a file to the current conversation. Equivalent to calling agent.uploadFile(task.conversationId, ...).

const result = await task.uploadFile(
  new Uint8Array(imageData),
  "chart.png",
  "image/png"
);

Parameters:

• file (Buffer | Uint8Array) — The file data
• fileName (string) — Original file name
• fileType (string, optional) — MIME type (auto-detected from extension if omitted)

Returns: Promise<UploadResult>

task.fetchHistory(options?)

Convenience method that fetches message history for the current conversation. Equivalent to calling agent.fetchHistory(task.conversationId, ...).

const history = await task.fetchHistory({ limit: 10 });

Parameters:

• options (FetchHistoryOptions, optional) — Pagination options

Returns: Promise<FetchHistoryResult>

Types

AgentSkill

Declares a skill (slash command) for the agent.

interface AgentSkill {
  /** Unique skill identifier (used as slash command, e.g. "draw") */
  id: string;
  /** Human-readable skill name */
  name: string;
  /** Short description of what the skill does */
  description: string;
}

ArinovaAgentOptions

Options for the ArinovaAgent constructor.

interface ArinovaAgentOptions {
  serverUrl: string;
  botToken: string;
  skills?: AgentSkill[];
  reconnectInterval?: number;
  pingInterval?: number;
}

TaskHandler

The function signature for task handlers.

type TaskHandler = (task: TaskContext) => void | Promise<void>;

AgentEvent

The event types you can listen to.

type AgentEvent = "connected" | "disconnected" | "error";

AgentEventListener

Event listener signatures mapped by event type.

type AgentEventListener<T extends AgentEvent> = T extends "error"
  ? (error: Error) => void
  : () => void;

SendCompleteOptions

Options for task.sendComplete().

interface SendCompleteOptions {
  mentions?: string[];  // User IDs to @mention in the response
}

FetchHistoryOptions

Pagination options for fetching message history.

interface FetchHistoryOptions {
  before?: string;  // Message ID — fetch messages before this
  after?: string;   // Message ID — fetch messages after this
  around?: string;  // Message ID — fetch messages around this
  limit?: number;   // Maximum number of messages to return
}

FetchHistoryResult

Result from fetching message history.

interface FetchHistoryResult {
  messages: Message[];
  hasMore: boolean;
  nextCursor: string;
}

ListNotesOptions

Pagination options for listing notes.

interface ListNotesOptions {
  before?: string;  // Pagination cursor
  limit?: number;   // Maximum number of notes to return
}

ListNotesResult

Result from listing notes.

interface ListNotesResult {
  notes: Note[];
  hasMore: boolean;
  nextCursor: string;
}

CreateNoteBody

Body for creating a note.

interface CreateNoteBody {
  title: string;
  content?: string;
}

UpdateNoteBody

Body for updating a note.

interface UpdateNoteBody {
  title?: string;
  content?: string;
}

UploadResult

Result from uploading a file.

interface UploadResult {
  url: string;       // Public URL of the uploaded file
  fileName: string;  // File name as stored
  fileType: string;  // MIME type
  fileSize: number;  // Size in bytes
}