Node SDK

Use the Node SDK when your client or agent runs in JavaScript or TypeScript.

The package name is @thalovant/sdk. Node.js 20 or newer is required.

Install

Install with npm install @thalovant/sdk.

npm install @thalovant/sdk

First Request

import { ThalovantClient, ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();

const publicHubs = await api.listPublicHubs({ limit: 12 });
for (const hub of publicHubs.data as Array<{ id: string; slug: string; title: string }>) {
  console.log(hub.id, hub.slug, hub.title);
}

await api.login("[email protected]", "password");

const result = await api.createClientIdentity("hub-id", {
  name: "node-demo-client",
  preferredProtocols: ["wss", "https", "mqtt"],
});

const client = new ThalovantClient(result.identity, { protocol: "wss" });
try {
  const reply = await client.ask("Tell me a short clean joke.");
  console.log(reply.text);
} finally {
  await client.close();
}

new ThalovantControlPlane() uses https://api.thalovant.com by default.

Caution

Keep result.identity secret. Authenticated API actions require API access on the workspace.

Use A Saved Identity

import { ThalovantClient } from "@thalovant/sdk";

const client = await ThalovantClient.fromConfig({ profile: "prod", protocol: "wss" });
try {
  const reply = await client.ask("What can this hub do?");
  console.log(reply.text);
} finally {
  await client.close();
}

Raw identity files work too:

import { ThalovantClient } from "@thalovant/sdk";

const client = await ThalovantClient.fromIdentityFile("_identity.json");
try {
  const reply = await client.ask("What can this hub do?");
  console.log(reply.text);
} finally {
  await client.close();
}

Environment variables work too:

import { ThalovantClient } from "@thalovant/sdk";

const client = ThalovantClient.fromEnv();

Choose A Protocol

const identity = result.identity;

console.log(identity.enabledProtocols());
console.log(identity.endpointFor("wss"));
console.log(identity.endpointFor("https"));
console.log(identity.endpointFor("mqtt"));

for (const protocol of ["wss", "https", "mqtt"] as const) {
  if (!identity.supportsProtocol(protocol)) continue;
  if (protocol === "mqtt" && !identity.mqtt) continue;

  const client = new ThalovantClient(identity, { protocol });
  try {
    const reply = await client.ask(`Reply over ${protocol}.`);
    console.log(protocol, reply.text);
  } finally {
    await client.close();
  }
}

MQTT requires the identity.mqtt broker credentials returned for that client.

For broker details, see MQTT.

Add Context

import { buildClientContext } from "@thalovant/sdk";

const context = buildClientContext({}, {
  userId: "user-42",
  userName: "Ada",
  source: "checkout-kiosk",
  platform: "kiosk",
  locale: "en-US",
  channel: "chat",
});

const reply = await client.ask("Show the next instruction.", { context });
console.log(reply.text);

Listen For Events

import { EVENT_SPEAK, EVENT_UTTERANCE_HANDLED } from "@thalovant/sdk";

const sub = client.on(EVENT_SPEAK, event => {
  console.log(event.text);
});

try {
  await client.sendUtterance("Say the current status.");
  await client.waitForEvent(EVENT_UTTERANCE_HANDLED, { timeoutMs: 12_000 });
} finally {
  sub.close();
}

Useful Helpers

ask

Send one request and receive normalized text, speech, and display items.

waitForEvent

Wait for one matching hub event with a timeout.

sendAction

Send a button, menu, or tool action.

sendCode

Send a barcode, QR value, serial number, or typed exact value.

For the full method list, see SDK Functions.

Common Issues

Symptom	Check
Missing access token	Call api.login(...) before private API actions.
API access requires a paid plan	Upgrade the workspace before provisioning private resources through the API.
Unsupported protocol	Enable that protocol on the hub and create a fresh identity.
MQTT fails immediately	Confirm the identity has mqtt broker credentials.