@cimulate/agentforce-sdk

A lightweight TypeScript SDK for Salesforce SCRT2 (Messaging for In-App and Web) APIs. Zero runtime dependencies beyond tslib.

Installation

npm install @cimulate/agentforce-sdk

Quick Start

import { CimulateAgentforceClient } from "@cimulate/agentforce-sdk";

const client = new CimulateAgentforceClient({
  baseURL: "https://your-instance.salesforce-scrt.com",
  orgId: "00DQZ...",
  esDeveloperName: "Agentforce",
  options: { enableLogging: true },
});

// Register event handlers
client.on("message", (event) => {
  console.log(`Agent: ${event.content}`);
});

client.on("streaming_token", (event) => {
  process.stdout.write(event.token);
});

client.on("typing_started", () => {
  console.log("Agent is typing...");
});

client.on("error", (event) => {
  console.error(`Error: ${event.message}`);
});

// Connect and start a conversation
await client.connect();
await client.createConversation();
await client.sendMessage("Hello!");

// When done
await client.endConversation();
client.disconnect();

API

Constructor

new CimulateAgentforceClient(options: AgentforceClientOptions)

| Option | Type | Required | Description | |--------|------|----------|-------------| | baseURL | string | Yes | SCRT2 instance URL | | orgId | string | Yes | Salesforce Organization ID | | esDeveloperName | string | Yes | Embedded Service developer name | | options.maxRetries | number | No | Max retries for REST requests (default: 3) | | options.timeout | number | No | Request timeout in ms (default: 15000) | | options.maxReconnectAttempts | number | No | Max SSE reconnect attempts (default: 5) | | options.reconnectDelay | number | No | Base reconnect delay in ms (default: 2000) | | options.enableLogging | boolean | No | Enable debug logging (default: false) |

Methods

| Method | Returns | Description | |--------|---------|-------------| | connect() | Promise<void> | Acquire token and open SSE stream | | createConversation(routingAttributes?) | Promise<string> | Create a new conversation, returns its ID | | sendMessage(text) | Promise<void> | Send a text message | | endConversation() | Promise<void> | End the current conversation | | disconnect() | void | Close SSE stream and clean up |

Events

| Event | Payload | Description | |-------|---------|-------------| | connected | void | SSE stream successfully opened | | disconnected | { reason } | SSE stream closed | | reconnecting | { attempt, maxAttempts } | Reconnection attempt started | | message | { conversationId, messageId, content, sender, timestamp } | Complete message received | | streaming_token | { conversationId, token } | Streaming token chunk | | typing_started | { conversationId, participant? } | Agent started typing | | typing_stopped | { conversationId, participant? } | Agent stopped typing | | progress_indicator | { conversationId, message, indicatorType?, raw? } | Action progress text (e.g. "Searching products...") while an agent action runs | | routing_result | { conversationId, isSuccessful, failureType? } | Routing completed | | participant_changed | { conversationId, participant, action } | Participant joined/left | | conversation_closed | { conversationId } | Conversation ended server-side | | error | { code?, message, recoverable } | Error occurred |

Properties

| Property | Type | Description | |----------|------|-------------| | isConnected | boolean | Whether SSE stream is active | | conversationId | string \| null | Current conversation ID | | accessToken | string \| null | Current access token |

Features

• Zero external dependencies — uses native fetch and ReadableStream for SSE
• Automatic token management — acquires and refreshes tokens transparently
• Exponential backoff reconnection — recovers from network drops automatically
• Full TypeScript support — complete type definitions for all events and options
• Lean bundle — ESM, CJS, and UMD outputs with tree-shaking support