JavaScript / TypeScript SDK

Complete reference for caspian-sdk on npm. One CommClient, one onMessage handler, and a connect* call per channel. The package ships full TypeScript types, so every method, option, and return shape is checked at build time. This mirrors the Python reference: same methods, camelCase names, options-object arguments.

Install

npm install caspian-sdk

Needs Node 18+ (the SDK uses the global fetch and AbortSignal.timeout). TypeScript types are bundled: no @types package to add. Import the class as an ES module:

import { CommClient, CommError } from "caspian-sdk";

Constructor

Everything is optional. With no arguments the client reads COMM_API_KEY and COMM_BASE_URL from the environment or a ./.env file next to your code. It throws CommError(401) if no key is found.

from caspian_sdk import CommClient

client = CommClient()                       # env / .env
client = CommClient(api_key="comm_...", base_url="https://api.trycaspianai.com", timeout=30.0)

import { CommClient } from "caspian-sdk";

const client = new CommClient();            // env / .env
const client = new CommClient({
  apiKey: "comm_...",                       // falls back to COMM_API_KEY
  baseUrl: "https://api.trycaspianai.com",  // falls back to COMM_BASE_URL
  timeout: 30,                              // per-request timeout, seconds (default 30)
  // fetch: myFetch,                        // inject a custom fetch (testing)
});

A complete agent

The shape of nearly every program: construct, connect a channel, register a handler, listen.

from caspian_sdk import CommClient

client = CommClient()

inbox = client.connect_email()
print("Agent address:", inbox["address"])

@client.on_message
def handle(message):
    message.reply(f"You said: {message.text}")

client.listen()                             # blocks forever

import { CommClient } from "caspian-sdk";

const client = new CommClient();

const inbox = await client.connectEmail();
console.log("Agent address:", inbox.address);

client.onMessage(async (message) => {
  await message.reply(`You said: ${message.text}`);
});

await client.listen();                      // runs forever; pass a signal to stop

Behavior guides

Opt-in text you can inject into your agent's system prompt so it follows each channel's etiquette. Both return a plain string.

system_prompt += "\n\n" + client.behavior_prompt()
slack_rules = client.channel_guide("slack")

systemPrompt += "\n\n" + await client.behaviorPrompt();
const slackRules = await client.channelGuide("slack");

Resources

Optional scoping objects. Most single-agent programs never need them; pass the ids they return as customerId / agentId on any connect* call to group connections.

Connect a channel

Every connect* and install* method returns a Connection. They all accept the shared ConnectOptions below, plus their own channel-specific fields. Provisioned channels (email, Telegram, phone, WhatsApp) resolve once active; OAuth channels resolve immediately with an authorize_url on the returned connection; hand that link to the user to finish the install.

Shared ConnectOptions

Connect methods

client.connect_email()                                   # free, no args
client.connect_telegram(bot_token="123:abc")             # from @BotFather
client.connect_phone(provider="twilio")                  # your own number
client.install_slack(display_name="Acme Bot")            # returns authorize_url

x = client.connect_x(access_token="...", user_id="123", access_secret="...")
inst = client.install_x()
print("Sign in with X:", inst["authorize_url"])

await client.connectEmail();                              // free, no args
await client.connectTelegram({ botToken: "123:abc" });   // from @BotFather
await client.connectPhone({ provider: "twilio" });       // your own number
await client.installSlack({ displayName: "Acme Bot" });  // returns authorize_url

await client.connectX({ accessToken: "...", userId: "123", accessSecret: "..." });
const inst = await client.installX();
console.log("Sign in with X:", inst.authorize_url);

Custom domains

Bring your own subdomain for email addresses. Register it, add the DNS records it returns, then poll until active.

Conversations and messages

Read connection state and history, and reply to or send messages. Replies route back on the source channel automatically and stay in the right thread.

convos = client.list_conversations()
msgs = client.list_messages(convos[0]["id"])

# proactive send into an existing thread
client.send_message(convos[0]["id"], text="Following up on your ticket.")

# trigger your handler without a mail client
client.test_email(text="ping", subject="hello")

const convos = await client.listConversations();
const msgs = await client.listMessages(convos[0].id);

// proactive send into an existing thread
await client.sendMessage(convos[0].id, "Following up on your ticket.");

// trigger your handler without a mail client
await client.testEmail({ text: "ping", subject: "hello" });

Webhooks and channels

Receive events by push instead of (or alongside) the polling loop, and inspect what transports the gateway has configured.

Events and listening

The event stream is the source of truth for inbound messages. listen() polls it and dispatches to your handlers; the lower-level methods let you drive the loop yourself. Pass ack to send an instant acknowledgement (e.g. "On it, one moment…") the moment a message arrives, before your handler runs, so the human sees the agent is working while it thinks; the real answer follows.

ListenOptions

Stop the loop cleanly with an AbortController, the JS equivalent of catching KeyboardInterrupt in Python:

try:
    client.listen()               # blocks until Ctrl-C
except KeyboardInterrupt:
    pass

const controller = new AbortController();
process.on("SIGINT", () => controller.abort());

await client.listen({ signal: controller.signal });   // resolves when aborted

The Message object

What your handler receives. Fields are identical across every channel, so one handler works everywhere. Note the camelCase (conversationId, connectionId) versus Python's snake_case.

@client.on_message
def handle(message):
    message.typing()                         # extend the indicator for slow work
    answer = my_agent(message.text)
    message.reply(answer)

client.onMessage(async (message) => {
  await message.typing();                    // extend the indicator for slow work
  const answer = await myAgent(message.text);
  await message.reply(answer);
});

Errors

Any non-2xx gateway response (or a transport failure) throws CommError. It carries the HTTP status and the gateway's detail string.

from caspian_sdk import CommError

try:
    client.connect_telegram(bot_token="bad")
except CommError as e:
    print(e.status_code, e.detail)

import { CommError } from "caspian-sdk";

try {
  await client.connectTelegram({ botToken: "bad" });
} catch (e) {
  if (e instanceof CommError) console.error(e.statusCode, e.detail);
}

Next steps