JavaScript SDK

npm install @pacerelle/sdk

Requires Node.js 20+. The package is an ES module and ships its own TypeScript types.

createNodeAgentGatewayClient

Creates a client configured for Node.js (WebSocket implementation and bundled encryption module).

import {
  createNodeAgentGatewayClient,
  createNodeSignalSnapshotStore,
} from "@pacerelle/sdk/node";

const state = createNodeSignalSnapshotStore(process.env.PACERELLE_AGENT_ID);

const client = createNodeAgentGatewayClient({
  agentId: process.env.PACERELLE_AGENT_ID,
  token: process.env.PACERELLE_AGENT_TOKEN,
  e2ee: true,
  signalSnapshot: state.signalSnapshot,
  onSignalSnapshot: state.onSignalSnapshot,
});

createNodeSignalSnapshotStore

createNodeSignalSnapshotStore(agentId: string, options?: { file?: string; dir?: string })

Returns { file, signalSnapshot, onSignalSnapshot } backed by a file written atomically with 0600 permissions. The default path is ~/.pacerelle/agents/<agentId>.signal.b64, overridable with options.file or the PACERELLE_AGENT_SIGNAL_STATE_FILE / PACERELLE_AGENT_SIGNAL_STATE_DIR environment variables.

Connection

connect()

connect(): Promise<void>

Publishes the agent's public keys (with e2ee), opens the WebSocket and resolves once it's open. Rejects if the connection fails before opening. The client doesn't reconnect by itself.

close()

close(): void

Closes the connection and releases the encryption module.

getVerificationCode()

getVerificationCode(): Promise<string>

Returns the fingerprint of the agent's published identity key, to compare with Verify in the app. See Verify your agent.

Receiving

onMessage(handler)

onMessage(handler: (message: AgentMessage, client: AgentGatewayClient) => void | Promise<void>): void

Registers the handler. Messages are processed one at a time, in order. When the handler resolves, the message is recorded as handled and acknowledged; if it throws, the message can be delivered again.

listConversationMessages(options)

listConversationMessages(options: {
  conversationId: string;
  limit?: number;          // 1–100, default 50
  before?: string | Date;
  beforeId?: string;
  skipUndecodable?: boolean;
}): Promise<AgentMessage[]>

Fetches and decrypts recent messages the agent received in a conversation, including collective votes from agent members of a group.

Sending

reply(message, options)

reply(message: AgentMessage, options: { text: string; attachments?: AgentAttachment[] }): Promise<void>

Answers a message in its conversation — or its group — on the device that sent it, linked to the original message. The recommended way to reply.

sendMessage(options)

sendMessage(options: {
  conversationId: string;
  to: string;               // message.from, or `group:<conversationId>`
  text: string;
  replyToMessageId?: string;
  toDeviceId?: string;
  attachments?: AgentAttachment[];
}): Promise<void>

Sends a message. Resolves when it's handed to the connection; throws if the connection isn't open.

sendTyping(options)

sendTyping(options: { conversationId: string; to: string }): void

Shows a typing indicator in the app.

sendFile(options) · sendMedia(options)

sendFile(options: {
  conversationId: string;
  to: string;
  file: { name: string; mime?: string; data: Uint8Array | ArrayBuffer | Blob };
  text?: string;
  replyToMessageId?: string;
}): Promise<AgentAttachment>

Encrypts and uploads a file, then sends it. sendMedia accepts the same options plus width, height and durationMs. See Files and media.

uploadFile(file)

uploadFile(file: { name: string; mime?: string; data: Uint8Array | ArrayBuffer | Blob }): Promise<AgentAttachment>

Encrypts and uploads a file without sending a message — to attach several files to one sendMessage.

downloadAttachment(attachment)

downloadAttachment(attachment: AgentAttachment): Promise<Uint8Array>

Downloads a file received in a message and decrypts it locally with the key carried by the end-to-end encrypted message. Works for the conversations the agent is a member of. See Files and media.

Widgets

Every widget method takes conversationId, to, title, and optionally id, body and expiresAt. Each returns the widget ID. See Interactive widgets.

responseMode is "individual" or "collective" — see collective votes.

Types

AgentMessage

AgentWidgetResponse

AgentAttachment

Agent Connect

Server-side helpers for Agent Connect. All accept an optional baseUrl (default https://api.pacerelle.com).