feat(realtime): refuse expired client tokens before dialling; add apiKeyProvider for fresh tokens on connect and reconnect

[AdirAmsalem]

Why

Client tokens expire 60 s after minting by default. Apps often mint on page load and connect only after the user grants the camera and presses start, or reconnect after a drop with the same token. The server refuses the expired token after a round trip, and the SDK surfaced that as a generic connection error.

What changed

• Fail fast on expired tokens. Before every dial (connect, connect retry, reconnect, subscribe) the SDK decodes the client token's exp. An expired one (5 s clock-skew tolerance) rejects with TOKEN_EXPIRED without opening a socket, and the message says how late it is and what to do. Opaque keys pass through for the server to judge.
• apiKeyProvider option. Pass a function instead of (or alongside) apiKey; the SDK calls it before every connect and reconnect, so each dial carries a token minted for it. apiKey is then optional for realtime; the HTTP APIs still use apiKey or proxy.
• Static apiKey path unchanged, including timing.
• README: documents the 60 s default TTL, the expiresIn knob, and both ways to stay fresh.
• examples/nextjs-realtime shows the pattern: one createDecartClient({ apiKeyProvider }), a Start button, and the token minted inside connect() and again on every reconnect by the /api/realtime-token route.

Usage

const client = createDecartClient({
  apiKeyProvider: async () => {
    // Your server mints it with client.tokens.create({ expiresIn: ... }).
    const res = await fetch("/api/realtime-token", { method: "POST" });
    const { apiKey } = await res.json();
    return apiKey;
  },
});

const realtimeClient = await client.realtime.connect(stream, { model, onRemoteStream });

Without a provider, an expired static token now rejects connect() with:

TOKEN_EXPIRED: Client token expired 83 s ago (exp 2026-10-07T11:58:37.000Z). Mint a new one right before
connecting, or pass apiKeyProvider to createDecartClient so the SDK fetches a fresh token before every connect
and reconnect. Client tokens expire 60 s after minting by default (tokens.create({ expiresIn })).

Tests

26 new unit tests: expired token rejected before any socket, clock-skew tolerance, provider called on connect, connect retry and each reconnect, static token expiring mid-session stops the reconnect, provider failures (retried on redial unless the SDK refused the credential outright), subscribe, and createDecartClient option validation. Suite: 374 passed. Build, lint, format and typecheck clean.

---

Note

Medium Risk
Changes the realtime authentication and retry path for all dials; behavior is additive but static client tokens can now fail fast with TOKEN_EXPIRED, and reconnect semantics depend on provider correctness.

Overview
Adds apiKeyProvider to createDecartClient so realtime connect, connect retries, reconnects, and subscribe can mint a fresh client token per dial instead of reusing one from page load (default 60s TTL).

Before any socket opens, the SDK preflights JWT client tokens (exp, 5s skew) and fails with TOKEN_EXPIRED and actionable messaging; opaque keys still go to the server. redialUrl / dynamic signaling URLs refresh api_key on later dials; TOKEN_EXPIRED and INVALID_API_KEY stop retries, while transient provider/mint failures still retry.

The nextjs-realtime example documents the pattern (Start/Stop, provider-backed token route with expiresIn: 60). README and SDK docs describe TTL and both “mint right before connect” vs provider approaches.

^{Reviewed by Cursor Bugbot for commit f946417. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@decartai/sdk@216

commit: f946417

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f946417. Configure here.}