@season/era-sdk

Drop-in cognitive context for any conversational AI agent. Zero runtime dependencies (uses global fetch).

npm install @season/era-sdk

Quick start

import { Era } from "@season/era-sdk";

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

const block = await era.turnContext(messages, { visitorId, sessionId });
systemPrompt += "\n\n" + block;

Each turn requires the browser SDK's visitorId. If it is unavailable, the SDK fails open with "" and does not call Era. Your authenticated, case-sensitive partnerEndUserId is optional linking context:

await era.turnContext(messages, {
  visitorId,
  partnerEndUserId,
  email,         // optional trusted bridge assertion; sent unchanged
  phone,         // optional; must already be E.164
  sessionId,
});

Absent fields are omitted. The SDK does not normalize or hash identifiers.

For Vercel AI SDK auto-injection middleware, import @season/era-sdk/ai-sdk.

Modes & production behavior

• mode: "async" (default) — stale-while-revalidate; instant response with the previous turn's block. mode: "sync" waits for the current turn.
• Fail-open: any error returns "" — your agent never breaks.
• Bounded retries on transient failures (timeout/network/5xx); 4xx is terminal. Configure with maxRetries (default 1).
• Timeouts: 2s async / 30s sync, override with timeoutMs.
• Logging: pass a logger ({ warn, info }) to integrate with pino/winston, or debug: true for verbose per-turn console output. Warnings only by default.

Options

| Option | Default | Notes | |--------|---------|-------| | visitorId | — | Browser-issued era_vid_<uuidv4> continuity ID | | partnerEndUserId | — | Trusted, case-sensitive partner customer ID | | email / phone | — | Optional trusted bridge assertions | | sessionId | derived | Correlation ID; may be set per call | | mode | "async" | "async" | "sync" | | brandVoice | — | words the [REC] action | | timeoutMs | 2000 / 30000 | per request | | maxRetries | 1 | transient-only | | logger / debug | console / false | observability |

The same identity fields may be configured as constructor defaults and overridden per call. There is no userId or "anonymous" fallback.

Develop

npm run build   # tsc -> dist/
npm test        # node --test