Node SDK quickstart

This guide adds Era to a trusted Node.js backend. Your browser or mobile app should never receive the Node SDK API key. You need Node.js 18 or later, an Era API key, a partner ID, and a visitorId from the Web SDK or Flutter SDK.

Install

npm install @seasonlabs/era-node

Create the client

import { Era } from "@seasonlabs/era-node";

const era = new Era({
  apiKey: process.env.ERA_API_KEY!,
  baseUrl: process.env.ERA_URL!,
  partnerId: process.env.ERA_PARTNER_ID!,
});

Create one client and reuse it. Keep all three values on your backend.

Get context before the model call

Call turnContext() after adding the latest user message to messages.

const eraContext = await era.turnContext(messages, {
  visitorId,
  sessionId,
});

Use the same visitorId for the same visitor. Use the same sessionId for every turn in one conversation.

Add the context to your system prompt

const systemPrompt = `You are a helpful assistant.

${eraContext}`;

eraContext is a plain string. If it is empty, continue with the model call as usual.

Complete example

import { Era } from "@seasonlabs/era-node";

const era = new Era({
  apiKey: process.env.ERA_API_KEY!,
  baseUrl: process.env.ERA_URL!,
  partnerId: process.env.ERA_PARTNER_ID!,
});

// Run this after the latest user message is in `messages`.
const eraContext = await era.turnContext(messages, {
  visitorId: "era_vid_00000000-0000-4000-8000-000000000000",
  sessionId: "conversation_123",
});

const result = await yourModel.generate({
  system: `You are a helpful assistant.\n\n${eraContext}`,
  messages,
});

What to expect

The default mode is async:

The first turn normally returns "".
Later turns return the previous turn’s prepared context.
Network and API failures return "" instead of breaking your chat.

Use mode: "sync" if you need context for the current turn and can accept the extra latency.

Add signed-in identity

If your backend knows the signed-in user, include your stable user ID:

const eraContext = await era.turnContext(messages, {
  visitorId,
  partnerEndUserId: authenticatedUser.id,
  sessionId,
});

You can also send a verified email or phone with partnerEndUserId. Never copy those values directly from untrusted client input.

Get started

Concepts

Reference

Integrations

Node SDK quickstart

Complete example

What to expect

Add signed-in identity

Next steps

Async and sync modes

Node SDK reference

​Complete example

​What to expect

​Add signed-in identity

​Next steps

Async and sync modes

Node SDK reference

Complete example

What to expect

Add signed-in identity

Next steps