npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@elaras/sdk-node

v0.3.4

Published

Official Node.js SDK for the Elaras Chat developer API

Readme

@elaras/sdk-node

Official Node.js SDK for the Elaras Chat developer API.

Server-side TypeScript library for building backends, webhooks, and integrations against the /api/developer/v1/* endpoints.

  • Dual-published (ESM + CJS)
  • First-class TypeScript types
  • Built-in retry with exponential backoff + jitter
  • Typed error hierarchy
  • Timing-safe webhook signature verification

Requires Node 18+ (uses the global fetch and crypto built-ins).


Install

npm install @elaras/sdk-node

Authentication

Create a sk_ secret key from the Elaras dashboard (Settings → Developer → API Keys) and pass it to the client:

import { ElarasClient } from '@elaras/sdk-node';

const elaras = new ElarasClient({
  apiKey: process.env.ELARAS_API_KEY!,
});

Full options:

new ElarasClient({
  apiKey:     'sk_...',                   // required
  baseUrl:    'https://ask-api.elaras.ai',   // default
  timeout:    30_000,                     // default (ms, per-request)
  maxRetries: 3,                          // default (429 + 5xx + network only)
});

Quickstart: build + deploy an agent

The full chain — from empty workspace to an embeddable chatbot — in six calls.

import { ElarasClient } from '@elaras/sdk-node';

const elaras = new ElarasClient({ apiKey: process.env.ELARAS_API_KEY! });

// 1. Create a chatbot (the thing you embed on your site).
const bot = await elaras.chatbots.create({
  name:            'Support bot',
  aiProvider:      'anthropic',
  greetingMessage: 'Hi! Ask me anything about our pricing or returns.',
});

// 2. Ingest some knowledge (workspace-wide, reusable across chatbots).
const pricing = await elaras.knowledge.createFromUrl({ url: 'https://acme.com/pricing' });
const faq     = await elaras.knowledge.createQa({
  question: 'What is your refund window?',
  answer:   '30 days, no questions asked.',
});

// Wait for the URL doc to finish embedding.
await elaras.knowledge.waitForIndex(pricing.id);

// 3. Create a personality — the versioned behaviour layer. Fresh personalities
//    come with a v1 draft already created, so we patch that draft directly.
const personality = await elaras.personalities.create({
  name:        'Support bot personality',
  description: 'Friendly, concise, defers refunds to a human.',
});

// 4. Patch the draft (v1) with the system prompt + attached knowledge.
await elaras.personalities.versions.update(personality.id, 1, {
  snapshot: {
    system_prompt:        'You are a friendly support agent for Acme. Keep answers short.',
    knowledge_source_ids: [pricing.id, faq.id],
    ai_provider:          'anthropic',
    ai_model:             'claude-haiku-4-5-20251001',
  },
});

// 5. Publish the version (freezes it + makes it assignable).
const published = await elaras.personalities.versions.publish(personality.id, 1);

// 6. Activate the published version on the chatbot.
await elaras.chatbots.assignModel(bot.id, { versionId: published.id });

// Done — `bot.public_key` is the X-Chatbot-Key the browser widget uses.
console.log('Embed with key:', bot.public_key);

Sessions

// Create a session. Idempotent on sessionToken — passing the same token
// twice returns the existing session instead of erroring. Omit the token
// to let the server generate a UUID.
const session = await elaras.sessions.create({
  chatbotId:         'cbt_live_xxx',
  sessionToken:      crypto.randomUUID(), // optional
  externalUserId:    'user_42',           // optional identity passthrough
  externalProfileId: 'tenant:acme',       // optional
  externalOrgId:     'org_xyz',           // optional
});
// → { id, chatbot_id, external_user_id, started_at, message_count, ... }

// Fetch session detail (includes messages[]).
const detail     = await elaras.sessions.get(session.id);
const transcript = await elaras.sessions.getTranscript(session.id); // same endpoint, named alias

// Paginated list.
const page = await elaras.sessions.list({
  chatbotId:      'cbt_live_xxx',
  externalUserId: 'user_42',
  limit:          50,
  cursor:         '2',      // Laravel page number
});

Knowledge

Knowledge in Elaras is workspace-scoped, not per-chatbot. Attach a doc to a chatbot by adding its id to a personality version's snapshot.knowledge_source_ids and publishing.

Breaking in 0.2.0: chatbotId was removed from createFromUrl, createQa, and list. The field was previously accepted and silently ignored.

// Add a URL — content is fetched and chunked server-side.
const doc = await elaras.knowledge.createFromUrl({
  url:  'https://example.com/pricing',
  name: 'Pricing page',    // optional
});

// Add a Q&A pair.
await elaras.knowledge.createQa({
  question: 'What are your office hours?',
  answer:   'We are open 9am–5pm, Monday to Friday.',
});

// Fetch / list.
const detail = await elaras.knowledge.get(doc.id);
const list   = await elaras.knowledge.list();
// → { data: KnowledgeDocument[], locked: boolean }

// Block until the doc is indexed (useful after createFromUrl which is async).
const indexed = await elaras.knowledge.waitForIndex(doc.id, {
  timeoutMs:      60_000,
  pollIntervalMs: 2_000,
});

// Mutations.
await elaras.knowledge.delete(doc.id);
const refreshed = await elaras.knowledge.resync(doc.id);
const cloned    = await elaras.knowledge.clone(doc.id);
const chunks    = await elaras.knowledge.getChunks(doc.id);
// → { data: KnowledgeChunk[] }

Leads

// A lead in Elaras is a session with `lead_email` captured.
const leads = await elaras.leads.list({
  chatbotId: 'cbt_live_xxx',
  email:     '[email protected]',     // optional partial match
  limit:     50,
});

// Leads are sessions with lead_email populated — there's no separate lead ID.
// Fetch by the session the lead was captured on:
const lead = await elaras.leads.getBySession('sess_abc');

Chatbots

// CRUD
const bot     = await elaras.chatbots.create({ name: 'Support bot' });
const list    = await elaras.chatbots.list();
const fetched = await elaras.chatbots.get('cbt_live_xxx');
await elaras.chatbots.update('cbt_live_xxx', { status: 'inactive' });
await elaras.chatbots.delete('cbt_live_xxx');

// Activate a published personality version on this chatbot. `versionId` is the
// numeric `id` returned by elaras.personalities.versions.list(modelId).
await elaras.chatbots.assignModel('cbt_live_xxx', { versionId: 42 });

// Attach a Flow (deterministic conversation branch) to the chatbot.
await elaras.chatbots.attachFlow('cbt_live_xxx', 7, {
  triggerPhrase: 'book a call',   // optional — forces this flow when matched
  enabled:       true,
});

// Analytics
const stats   = await elaras.chatbots.getStats('cbt_live_xxx', { period: '7d' });
const flagged = await elaras.chatbots.listFlaggedSessions('cbt_live_xxx', {
  category: 'cannot_answer',
  limit:    50,
});

// `public_key` is exposed on get() — this is the X-Chatbot-Key the browser
// widget / JS SDK uses. Safe to ship client-side; it's not a secret.
console.log(bot.public_key);

Personalities + Versions

A personality is a versioned behaviour container. Draft versions are mutable; published versions are frozen. Attach knowledge, skills, and flows to a version via its snapshot, then publish and assign the published version to a chatbot.

Identifiers. personality.id is a UUID string — the public identifier. Pass it to every .get / .update / .delete method and as the first arg to versions.*. Versions within a personality are addressed by their sequential version_number (1, 2, 3, …), not by id — the SDK resolves the internal id for you.

// Personality CRUD — ids are UUIDs
const list       = await elaras.personalities.list();
const created    = await elaras.personalities.create({ name: 'Support bot' });
const personaId  = created.id;                                        // UUID
const detail     = await elaras.personalities.get(personaId);
const renamed    = await elaras.personalities.update(personaId, { name: 'Renamed' });
await elaras.personalities.delete(personaId);

// Versions — nested resource under elaras.personalities.versions
const versions   = await elaras.personalities.versions.list(personaId);
const v2         = await elaras.personalities.versions.get(personaId, 2);   // by version_number
const draft      = await elaras.personalities.versions.create(personaId, {
  changeNotes: 'Tightening the system prompt',
});

// Patch the draft snapshot. Deep-merged server-side.
await elaras.personalities.versions.update(personaId, draft.version_number, {
  snapshot: {
    system_prompt:        'You are helpful.',
    knowledge_source_ids: [7, 9],
    skill_ids:            [1, 2],
    ai_provider:          'anthropic',
    ai_model:             'claude-haiku-4-5-20251001',
    rules:                ['Never discuss competitor pricing.'],
  },
});

// Publish → freezes the version. Returns the published row.
const published  = await elaras.personalities.versions.publish(personaId, draft.version_number);

// Clone a published version into a new editable draft.
const clone      = await elaras.personalities.versions.clone(personaId, 2, {
  changeNotes: 'v2 → v3 iteration',
});

await elaras.personalities.versions.delete(personaId, draft.version_number);

Flows

A Flow is a deterministic conversation branch (step graph) that the LLM can hand off to. Flows are workspace-scoped; attach to a chatbot with elaras.chatbots.attachFlow().

const flows   = await elaras.flows.list();
const flow    = await elaras.flows.get(7);
const created = await elaras.flows.create({
  name:        'Book a slot',
  description: 'Walks the user through calendar availability.',
  definition:  { steps: [/* ... */] },
});

await elaras.flows.update(7, { name: 'Renamed', enabled: false });
await elaras.flows.delete(7);

// Ask the AI to draft a Flow definition from a plain-text description. The
// returned `definition` is a draft only — pass it to flows.create to persist.
const draft = await elaras.flows.generate('book a 30-minute discovery call');
await elaras.flows.create({ name: 'Discovery', definition: draft.definition });

Scenarios

Scenarios are stored multi-turn test cases bound to a personality. A scenario run replays one or more scenarios against a specific personality version and judges each reply. The typical pattern is to gate publishing a draft version on a passing run.

Identifiers. Scenarios are addressed by integer within their personality. Runs are addressed by UUID — the run id you get back is the public identifier for getRun, cancelRun, and waitForRun.

// Seed scenarios on the personality (manually or via AI draft)
const seeded = await elaras.scenarios.create(personaId, {
  name:            'Return policy — 30 days',
  initialMessage:  'Can I return something after 2 weeks?',
  overallCriteria: { should_resolve: true },
  turns: [
    { bot_criteria: { mentions_30_days: true }, user_reply: 'What about damaged items?' },
  ],
});

await elaras.scenarios.draft(personaId, { intent: 'returns + exchanges', count: 5 });
const all = await elaras.scenarios.list(personaId);   // Scenario[]
await elaras.scenarios.update(personaId, seeded.id, { name: 'Returns — 30 days (v2)' });
await elaras.scenarios.delete(personaId, seeded.id);

// Publish-gate: run → wait → publish only if clean
const run   = await elaras.scenarios.run(personaId, { versionNumber: 2 });
const final = await elaras.scenarios.waitForRun(personaId, run.id);     // run.id is a UUID

if (final.status === 'completed' && (final.failed ?? 0) === 0) {
  await elaras.personalities.versions.publish(personaId, 2);
  await elaras.chatbots.assignModel(chatbotId, { versionId: final.bot_model_version_id });
}

waitForRun polls getRun every 2s (configurable) and resolves when status leaves queued/running. Default timeout is 3 minutes — override with waitForRun(personaId, runId, { timeoutMs, pollIntervalMs }).


Error handling

Every failure thrown by the SDK extends ElarasError. Match on the specific subclass for ergonomic handling:

import {
  ElarasAuthError,
  ElarasValidationError,
  ElarasRateLimitError,
  ElarasServerError,
  ElarasNetworkError,
} from '@elaras/sdk-node';

try {
  await elaras.knowledge.createFromUrl({ url: 'nope' });
} catch (err) {
  if (err instanceof ElarasValidationError) {
    console.log(err.errors);           // { url: ['The url field is required.'] }
  } else if (err instanceof ElarasAuthError) {
    // 401 / 403 — bad key or missing scope
  } else if (err instanceof ElarasRateLimitError) {
    console.log(err.retryAfterSeconds); // honour this before retrying
  } else if (err instanceof ElarasServerError) {
    // 5xx — SDK already retried per `maxRetries`
  } else if (err instanceof ElarasNetworkError) {
    // DNS, TCP, timeout — SDK already retried
  }
}

Retry policy

  • 429 and 5xx responses are retried.
  • Backoff: 500ms * 2^attempt + jitter(0..100ms).
  • 429 responses honour the Retry-After header when present.
  • 4xx responses other than 429 are never retried.
  • Default retries: 3. Set maxRetries: 0 to opt out.

Webhook signature verification

When Elaras calls your skill endpoint it signs the request body with HMAC-SHA256 using the skill's API key. Verify every incoming request before acting on it:

import { verifyWebhookSignature } from '@elaras/sdk-node';
import type { SkillPayload } from '@elaras/sdk-node';
import express from 'express';

const app = express();

// IMPORTANT: use the raw body — re-serialising via JSON.stringify can reorder
// keys and break the signature.
app.post(
  '/webhooks/elaras/book-slot',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.get('X-Elaras-Signature');
    const ok  = verifyWebhookSignature(req.body, sig, process.env.ELARAS_SKILL_SECRET!);
    if (!ok) return res.status(401).send('invalid signature');

    const payload = JSON.parse(req.body.toString('utf8')) as SkillPayload;
    // payload.skill, payload.params, payload.session.{id, lead_name, lead_email}

    res.json({ booked: true });
  },
);

The signature header format is X-Elaras-Signature: sha256=<hex>. Comparison is done with crypto.timingSafeEqual.


Implementation notes

A few personalities.versions.* methods do a transparent extra fetch because the backend version-level routes take the internal integer id, while the SDK's public contract is version_number:

  • versions.get(personaId, versionNumber) — fetches the list and finds the matching row (the server has no single-version GET route).
  • versions.update / publish / clone / delete — resolve version_number → id via a single list fetch, then call the correct URL. From the caller's perspective nothing changes; you always pass version_number.

This adds one extra GET per mutating call. If you're running a tight loop, prefetch elaras.personalities.versions.list(personaId) yourself and reuse the result — each row's id can be used directly if you drop to the HTTP transport.


Development

npm install
npm test            # vitest run
npm run typecheck   # tsc --noEmit
npm run build       # tsup — emits dist/index.{js,cjs,d.ts}

License

MIT © Elaras