@eliware/elera-lib 0.1.8 → 0.1.10

package/README.md

@@ -2,9 +2,9 @@
 
 The alternative SQL client for Eliware applications. It provides generic
 primary/balanced MySQL or MariaDB routing without embedding Elera, HAProxy,
-backup, or GitOps policy. It is a v0.1.8 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.10 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged. The current package version is
-0.1.8.
+0.1.10.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
 path. Both may accept writes; automatic routing sends only conservative,
@@ -34,7 +34,8 @@ Routing bundles passed to `createDbFromBundle` use the normalized shape
 `routes.primary` and `routes.balanced`, each containing ordered `{ host, port,
 weight }` nodes. A bundle may also carry an explicit `writer`, ordered
 `failover`, and `readers` assignment. The bundle carries `database`,
-`identity`, optional `credentials`, and `expiresAt`; `validateBundle` rejects
+`identity`, optional `application`, `credentialName`, `scopes`, and
+`credentials`, and `expiresAt`; `validateBundle` rejects
 expired, malformed, duplicated, or conflicting route data. The checked-in
 contract fixture documents the supervisor-facing wire representation
 separately.
@@ -49,6 +50,12 @@ library does not know about supervisors, Elera, HAProxy, GitOps, backups, or
 CLI commands. Applications provide those integrations through ordinary
 configuration and callbacks.
 
+An application-scoped token should resolve to one application, database, and
+credential context. The library does not select databases or credentials from
+request arguments. Callers that already have that authorization context may
+pass `tokenContext` to `createDb`; bundle creation and refresh then reject
+cross-database, identity, credential, or scope mismatches.
+
 When a route node is drained, the client immediately stops assigning new work
 to that node while existing operations continue. The drain window defaults to
 45 seconds and is capped at 45 seconds; remaining pool connections are then
@@ -61,8 +68,10 @@ automatically.
 `client.availability()` reports whether a primary route is usable. It returns
 `state: 'cluster-unavailable'` when every primary candidate is draining or
 unavailable; the `routes` fields report primary and balanced availability
-independently. New operations in that state fail with the exported
-`ClusterUnavailableError` using code `CLUSTER_UNAVAILABLE`.
+independently. A single-node route fails with the exported
+`ServerUnavailableError` using code `SERVER_UNAVAILABLE`; a multi-node route
+with no eligible candidates fails with `ClusterUnavailableError` using code
+`CLUSTER_UNAVAILABLE`.
 
 When an attached routing stream receives a `routing.shutdown` event, the
 client drains the identified node, performs a REST bundle resynchronization,
@@ -94,11 +103,14 @@ contents. The stream reports `websocket`, `rest`, or `disconnected` mode so
 callers can observe transport health without implementing transport policy.
 
 Applications may opt into generic in-memory telemetry with
-`createDb({ ..., telemetry: true })`. Query counts, failures, retries,
-in-flight work, and latency are exposed through `client.telemetry` and sent
-over an attached routing stream once per second. Telemetry is observational
-only; it does not carry SQL or credentials. Reconnect, failover, and cumulative
-reconnect-delay counters are included in the telemetry snapshot.
+`createDb({ ..., telemetry: true })`. Query, execute, and transaction counts,
+failures, retries, in-flight work, and latency are exposed through
+`client.telemetry` and sent over an attached routing stream once per second.
+Telemetry is observational only; it does not carry SQL or credentials.
+The snapshot may include the application, database, credential name, and
+scopes associated with the already-authorized client, plus reconnect, failover,
+and cumulative reconnect-delay counters. It never includes bearer tokens or
+passwords.
 
 `createMaterializer` supports bounded plaintext use for a caller-provided
 operation. It creates a mode-restricted temporary file and removes its entire

package/RELEASE_NOTES.md

@@ -1,5 +1,40 @@
 # Release notes
 
+## 0.1.10 — Token-bound routing context
+
+### Added
+
+- Adds `validateTokenContext` for enforcing an application token's authorized
+  application, database, credential, identity, and scopes against a routing
+  bundle.
+- Applies that authorization check during initial client creation and every
+  subsequent bundle refresh.
+- Keeps routing-stream authorization token-only; database and application
+  selectors are not sent as query parameters.
+- Includes safe application, database, credential, and scope context in
+  opt-in in-memory telemetry without exposing tokens or passwords.
+
+### Validation
+
+- Adds focused coverage for matching contexts, rejected cross-database and
+  scope mismatches, refresh-time enforcement, and isolated token contexts.
+- Maintains 100% statements, branches, functions, and lines coverage with zero
+  lint warnings.
+- Typecheck, contract, syntax, and package dry-run checks pass.
+
+## 0.1.9 — Standalone outage classification and complete operation telemetry
+
+### Added
+
+- Exposes `ServerUnavailableError` with the stable `SERVER_UNAVAILABLE` code when a standalone SQL route has no eligible server.
+- Keeps multi-node route exhaustion classified as `CLUSTER_UNAVAILABLE`.
+- Records telemetry for `execute()` and transaction operations alongside query latency and failure metrics.
+
+### Validation
+
+- Adds regression coverage for standalone drain classification and operation telemetry.
+- Maintains 100% statements, branches, functions, and lines coverage with zero lint warnings.
+
 ## 0.1.8 — Explicit outage state and recovery observability
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.8",
+    "version": "0.1.10",
     "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
     "keywords": [
         "eliware",

package/src/client/authorization-context.mjs

@@ -0,0 +1,9 @@
+export function validateTokenContext(bundle, tokenContext = {}) {
+  if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
+  for (const field of ['application', 'database', 'credentialName']) {
+    if (tokenContext[field] !== undefined && bundle[field] !== tokenContext[field]) throw new Error(`routing bundle ${field} does not match token context`);
+  }
+  if (tokenContext.identity !== undefined && bundle.identity !== tokenContext.identity) throw new Error('routing bundle identity does not match token context');
+  if (tokenContext.scopes !== undefined && (!Array.isArray(bundle.scopes) || tokenContext.scopes.some((scope) => !bundle.scopes.includes(scope)))) throw new Error('routing bundle scopes exceed token context');
+  return bundle;
+}

package/src/client/create-db.mjs

@@ -3,17 +3,18 @@ import * as mysql from 'mysql2/promise';
 import { validateProfile, redactedProfile } from '../config.mjs';
 import { asSqlError } from '../errors.mjs';
 import { resolveCredentials, credentialContext } from '../credential-provider.mjs';
-import { validateBundle, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs';
+import { validateBundle as validateBundleShape, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs';
 import { createRouteFactory } from './route-factory.mjs';
 import { classifyQuery, routeFor } from '../routing.mjs';
 import { compareBundleVersions } from '../routing/bundle-version.mjs';
 import { clientDrainTimeout } from '../lifecycle/drain-policy.mjs';
 import { createTelemetry } from '../telemetry.mjs';
 import { createTimedOperation } from './telemetry-wrapper.mjs';
+import { validateTokenContext } from './authorization-context.mjs';
 
 const olderVersion = (candidate, current) => compareBundleVersions(candidate, current) < 0;
 
-export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, quarantineMs = 5000, drainTimeoutMs = 45000, now = () => Date.now(), telemetry } = {}) {
+export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, tokenContext, quarantineMs = 5000, drainTimeoutMs = 45000, now = () => Date.now(), telemetry } = {}) {
   if (!primary || typeof primary !== 'object') throw new TypeError('primary connection profile is required');
   const credentials = await resolveCredentials(credentialProvider, credentialContext(primary, { identity }));
   let primaryConfig = validateProfile({ ...primary, ...credentials }, 'primary');
@@ -23,17 +24,18 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
     primaryConfig = validateProfile({ ...primaryConfig, ...credentials }, 'primary');
     if (balancedConfig) balancedConfig = validateProfile({ ...balancedConfig, ...credentials }, 'balanced');
   }
+  const validateBundle = (candidate) => validateTokenContext(validateBundleShape(candidate), tokenContext);
   let activeBundle = bundle ? validateBundle(bundle) : undefined;
   const makeRoute = (route, fallback) => createRouteFactory({ bundle: activeBundle, now, mysqlLib, log, quarantineMs })(route, fallback);
   let primaryPool = makeRoute('primary', primaryConfig);
   let balancedPool = balancedConfig || activeBundle?.routes?.balanced ? makeRoute('balanced', balancedConfig ?? primaryConfig) : null;
   const choose = (sql, options = {}) => options.connection ?? (routeFor(sql, options.route ?? routing) === 'balanced' && balancedPool ? balancedPool : primaryPool);
-  const metrics = telemetry === true ? createTelemetry({ application: bundle?.application ?? identity ?? 'default', now }) : telemetry;
+  const metrics = telemetry === true ? createTelemetry({ application: bundle?.application ?? 'default', credentialName: bundle?.credentialName, database: bundle?.database, scopes: bundle?.scopes, now }) : telemetry;
   const timed = createTimedOperation({ metrics, now });
   const client = {
     async query(sql, values, options) { return timed(async () => { const selected = choose(sql, options); try { return await selected.query(sql, values); } catch (error) { const requestedRoute = options?.route ?? routing; if (error.retryable && balancedPool && routeFor(sql, requestedRoute) === 'balanced' && classifyQuery(sql) === 'balanced') { metrics?.record?.({ retry: true }); return balancedPool.query(sql, values); } throw error; } }); },
-    async execute(sql, values, options) { return choose(sql, options).execute(sql, values); },
-    async transaction(callback) { const node = primaryPool.choose(); const connection = await node.getConnection(); try { await connection.beginTransaction(); const tx = { query: (sql, values) => connection.query(sql, values), execute: (sql, values) => connection.execute(sql, values) }; const result = await callback(tx); await connection.commit(); return result; } catch (error) { await connection.rollback().catch(() => {}); throw asSqlError(error); } finally { connection.release(); } },
+    async execute(sql, values, options) { return timed(async () => choose(sql, options).execute(sql, values)); },
+    async transaction(callback) { return timed(async () => { const node = primaryPool.choose(); const connection = await node.getConnection(); try { await connection.beginTransaction(); const tx = { query: (sql, values) => connection.query(sql, values), execute: (sql, values) => connection.execute(sql, values) }; const result = await callback(tx); await connection.commit(); return result; } catch (error) { await connection.rollback().catch(() => {}); throw asSqlError(error); } finally { connection.release(); } }); },
     async health(route = 'primary') { const started = now(); const selected = route === 'balanced' && balancedPool ? balancedPool : primaryPool; const nodes = await selected.health(); return { ok: nodes.some((node) => node.ok), route: selected === balancedPool ? 'balanced' : 'primary', nodes, latencyMs: now() - started }; },
     async refresh(nextBundle) { const candidate = validateBundle(nextBundle); if (bundleExpired(candidate, now())) throw new Error('routing bundle is expired'); if (olderVersion(candidate.bundleVersion, activeBundle?.bundleVersion)) return { bundleVersion: activeBundle?.bundleVersion, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; const previous = [primaryPool, balancedPool]; const credentials = candidate.credentials ?? { username: primaryConfig.user, password: primaryConfig.password }; const writer = candidate.writer ?? candidate.routes.primary?.[0]; const reader = candidate.readers?.[0] ?? candidate.routes.balanced?.[0]; primaryConfig = validateProfile({ ...primaryConfig, host: writer.host, port: writer.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); balancedConfig = reader ? validateProfile({ ...primaryConfig, host: reader.host, port: reader.port }, 'balanced') : undefined; activeBundle = candidate; primaryPool = makeRoute('primary', primaryConfig); balancedPool = balancedConfig ? makeRoute('balanced', balancedConfig) : null; await Promise.all(previous.filter(Boolean).map((pool) => pool.close())); return { bundleVersion: activeBundle.bundleVersion ?? null, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; },
     async attachRoutingStream(stream) { if (!stream?.connect) throw new TypeError('routing stream is required'); metrics?.start?.(stream); stream.setTelemetry?.(metrics); stream.setOnUpdate?.(async (event) => { const update = event.type === 'routing.update' ? event : event.type === 'routing.resync' ? event.bundle : undefined; if (update && (update.writer || update.routes?.primary?.length)) await client.refresh({ ...activeBundle, ...update, database: update.database ?? activeBundle?.database ?? primaryConfig.database, credentials: update.credentials ?? activeBundle?.credentials, routes: update.routes ?? activeBundle?.routes, bundleVersion: update.bundleVersion ?? update.version ?? activeBundle?.bundleVersion, expiresAt: update.expiresAt ?? activeBundle?.expiresAt ?? new Date(now() + 60000).toISOString() }); if (event.type === 'routing.drain' || event.type === 'routing.shutdown') for (const pool of [primaryPool, balancedPool].filter(Boolean)) (event.type === 'routing.drain' ? pool.drain : pool.drain)(event.node, drainTimeoutMs); if (event.type === 'routing.recovery') for (const pool of [primaryPool, balancedPool].filter(Boolean)) pool.recover(event.node, drainTimeoutMs); }); await stream.connect(); return () => stream.close?.(); },

package/src/errors.mjs

@@ -11,6 +11,13 @@ export class ClusterUnavailableError extends SqlClientError {
   }
 }
 
+export class ServerUnavailableError extends SqlClientError {
+  constructor(message = 'The SQL server is unavailable', options = {}) {
+    super(message, { code: 'SERVER_UNAVAILABLE', retryable: false, ...options });
+    this.name = 'ServerUnavailableError';
+  }
+}
+
 export function classifyError(error) {
   const code = error?.code;
   if (['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'PROTOCOL_CONNECTION_LOST', 'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR'].includes(code)) return { code: 'CONNECTION_ERROR', retryable: true };

package/src/index.d.ts

@@ -15,6 +15,9 @@ export interface RoutingBundle {
   apiVersion?: string;
   database?: string;
   identity?: string;
+  application?: string;
+  credentialName?: string;
+  scopes?: string[];
   credentials?: { username?: string; password?: string };
   bundleVersion?: number | string;
   expiresAt: string;
@@ -28,7 +31,7 @@ export interface CredentialProviderResult { user: string; password: string; }
 export type CredentialProvider = (context: { database: string; identity: string | null; route: string }) => Promise<CredentialProviderResult> | CredentialProviderResult;
 export type QueryFunction = (sql: string, values?: unknown) => Promise<any>;
 export interface DbOptions { route?: 'auto' | 'primary' | 'balanced'; connection?: unknown; }
-export interface TelemetrySnapshot { type: 'client.telemetry'; application: string; queries: number; failures: number; retries: number; reconnects: number; failoverCount: number; reconnectDelayMs: number; inflight: number; totalLatencyMs: number; maxLatencyMs: number; avgLatencyMs: number; sentAt: string; }
+export interface TelemetrySnapshot { type: 'client.telemetry'; application: string; credentialName?: string; database?: string; scopes?: string[]; queries: number; failures: number; retries: number; reconnects: number; failoverCount: number; reconnectDelayMs: number; inflight: number; totalLatencyMs: number; maxLatencyMs: number; avgLatencyMs: number; sentAt: string; }
 export interface Telemetry { begin(): number; record(event?: { latencyMs?: number; failed?: boolean; retry?: boolean; reconnect?: boolean; failover?: boolean }): void; recordReconnect(event?: { delayMs?: number; failover?: boolean }): void; snapshot(): TelemetrySnapshot; start(stream: Pick<RoutingStream, 'sendTelemetry'>): void; stop(): void; }
 
 export interface DbClient {
@@ -61,7 +64,7 @@ export interface RoutingStream {
 export type RoutingEvent = { type: 'routing.update' | 'routing.resync' | 'routing.drain' | 'routing.recovery'; node?: string; version?: number | string; [key: string]: unknown } | { type: 'routing.shutdown'; node?: string; reason?: string; reconnect?: boolean; reconnectDeadlineMs?: number; loadBalancerEndpoint?: string };
 export function validateRoutingEvent(event: unknown): RoutingEvent;
 
-export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number; telemetry?: true | Telemetry }): Promise<DbClient>;
+export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number; telemetry?: true | Telemetry }): Promise<DbClient>;
 export function createDbFromEnvironment(options?: { env?: Record<string, string | undefined>; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string; telemetry?: true | Telemetry }): Promise<DbClient>;
 export function classifyQuery(sql: unknown): 'primary' | 'balanced';
 export function routeFor(sql: unknown, requested?: 'auto' | 'primary' | 'balanced'): 'primary' | 'balanced';
@@ -69,6 +72,7 @@ export function validateProfile(profile: ConnectionProfile, name?: string): Conn
 export function redactedProfile(profile: ConnectionProfile): ConnectionProfile;
 export class SqlClientError extends Error { code?: string; retryable?: boolean; cause?: unknown; }
 export class ClusterUnavailableError extends SqlClientError {}
+export class ServerUnavailableError extends SqlClientError {}
 export function classifyError(error: unknown): { retryable: boolean; code?: string };
 export function asSqlError(error: unknown): SqlClientError;
 export function validateBundle(bundle: RoutingBundle): RoutingBundle;
@@ -77,7 +81,7 @@ export function bundleNeedsRefresh(bundle: RoutingBundle, now?: number): boolean
 export function createAdminSql(options: { query: QueryFunction }): { transaction<T>(work: (context: { query: QueryFunction }) => Promise<T>): Promise<T>; migration(statements?: string[]): Promise<unknown> };
 export function createMigrationRunner(options: { query: QueryFunction; migrations?: Array<{ version: number; name: string; statements: string[] }> }): { status(): Promise<{ applied: unknown[] }>; migrate(): Promise<unknown> };
 export function selectRouteNodes(options: { bundle: RoutingBundle; route?: 'primary' | 'balanced'; now?: number }): RoutingNode[];
-export function createRoutingStream(options: { endpoint: string; token?: string; application?: string; fetchBundle: (application: string) => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number; telemetry?: Pick<Telemetry, 'recordReconnect'> }): RoutingStream;
+export function createRoutingStream(options: { endpoint: string; token?: string; fetchBundle: () => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number; telemetry?: Pick<Telemetry, 'recordReconnect'> }): RoutingStream;
 export function writerAssignment(bundle: RoutingBundle): WriterAssignment;
 export function failoverNodes(bundle: RoutingBundle): WriterAssignment[];
 export function compareBundleVersions(left: number | string | undefined, right: number | string | undefined): number;
@@ -86,4 +90,4 @@ export function clientDrainTimeout(timeoutMs?: number): number;
 export function createQuiesceController(options?: { close?: () => Promise<void>; onChange?: (state: string) => void }): { state(): { state: string; active: number }; enter(): () => void; begin(): Promise<void>; end(): Promise<void>; close(): Promise<void> };
 export function createSqlVerifier(options: { query: QueryFunction }): { connectivity(): Promise<{ verified: boolean }>; schema(database: string): Promise<{ database: string; verified: boolean }>; account(user: string, host?: string): Promise<{ user: string; host: string; verified: boolean; grants: string[] }>; all(options?: { database?: string; user?: string; host?: string }): Promise<unknown> };
 export function createMaterializer(options?: Record<string, unknown>): unknown;
-export function createTelemetry(options?: { application?: string; intervalMs?: number; now?: () => number; setIntervalImpl?: typeof setInterval; clearIntervalImpl?: typeof clearInterval }): Telemetry;
+export function createTelemetry(options?: { application?: string; credentialName?: string; database?: string; scopes?: string[]; intervalMs?: number; now?: () => number; setIntervalImpl?: typeof setInterval; clearIntervalImpl?: typeof clearInterval }): Telemetry;

package/src/index.mjs

@@ -1,9 +1,10 @@
 export { createDb } from './client/create-db.mjs';
+export { validateTokenContext } from './client/authorization-context.mjs';
 export { createDbFromBundle, profilesFromBundle } from './client/from-bundle.mjs';
 export { createDbFromEnvironment } from './client/environment.mjs';
 export { classifyQuery, routeFor } from './routing.mjs';
 export { validateProfile, redactedProfile } from './config.mjs';
-export { SqlClientError, ClusterUnavailableError, classifyError, asSqlError } from './errors.mjs';
+export { SqlClientError, ClusterUnavailableError, ServerUnavailableError, classifyError, asSqlError } from './errors.mjs';
 export { validateBundle, bundleExpired, bundleNeedsRefresh } from './bundle.mjs';
 export { createAdminSql } from './admin/sql.mjs';
 export { createMigrationRunner } from './admin/migrations.mjs';

package/src/pools/route-pool.mjs

@@ -1,11 +1,11 @@
-import { ClusterUnavailableError } from '../errors.mjs';
+import { ClusterUnavailableError, ServerUnavailableError } from '../errors.mjs';
 
-export function createRoutePool(nodes, { preferred = false } = {}) {
+export function createRoutePool(nodes, { preferred = false, unavailableError = nodes.length === 1 ? ServerUnavailableError : ClusterUnavailableError } = {}) {
   let cursor = 0;
   const candidates = () => nodes.filter((node) => node.available);
   const choose = () => {
     const available = candidates();
-    if (!available.length) throw new ClusterUnavailableError('no eligible SQL nodes available');
+    if (!available.length) throw new unavailableError('no eligible SQL nodes available');
     if (preferred) return available[0];
     const total = available.reduce((sum, node) => sum + Math.max(0, node.weight), 0);
     if (!total) return available[cursor++ % available.length];

package/src/routing/stream-client.mjs

@@ -2,12 +2,12 @@ import { log as defaultLog } from '@eliware/common';
 import { compareBundleVersions } from './bundle-version.mjs';
 import { validateRoutingEvent } from './event-contract.mjs';
 
-export function createRoutingStream({ endpoint, token, application = 'default', fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, heartbeatMs = 45000, now = () => Date.now(), telemetry } = {}) {
+export function createRoutingStream({ endpoint, token, fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, heartbeatMs = 45000, now = () => Date.now(), telemetry } = {}) {
   if (!endpoint || typeof fetchBundle !== 'function') throw new TypeError('endpoint and fetchBundle are required');
   let socket; let closed = false; let timer; let heartbeat; let expectedVersion = 0; let delay = reconnectMs; let updateHandler = onUpdate; let mode = 'disconnected'; let plannedReconnect = false; let lastReconnectWasPlanned = false; let disconnectedAt; let reconnectDeadlineAt;
   const log = arguments[0]?.log ?? defaultLog;
-  const streamUrl = () => `${endpoint.replace(/^http/i, 'ws').replace(/\/$/, '')}/api/v1/routing/stream?application=${encodeURIComponent(application)}&token=${encodeURIComponent(token ?? '')}`;
-  async function fallback() { try { const bundle = await fetchBundle(application); if (closed) return; mode = 'rest'; updateHandler?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { if (closed) return; mode = 'disconnected'; onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
+  const streamUrl = () => `${endpoint.replace(/^http/i, 'ws').replace(/\/$/, '')}/api/v1/routing/stream?token=${encodeURIComponent(token ?? '')}`;
+  async function fallback() { try { const bundle = await fetchBundle(); if (closed) return; mode = 'rest'; updateHandler?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { if (closed) return; mode = 'disconnected'; onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
   function schedule() { if (closed || timer || (reconnectDeadlineAt !== undefined && now() >= reconnectDeadlineAt)) return; const wait = Math.min(delay, Math.max(0, reconnectDeadlineAt === undefined ? delay : reconnectDeadlineAt - now())); timer = setTimeout(() => { timer = undefined; void connect(); }, wait); delay = Math.min(maxReconnectMs, delay * 2); }
   async function connect() {
     if (closed || typeof WebSocketImpl !== 'function') { await fallback(); schedule(); return; }

package/src/telemetry.mjs

@@ -1,9 +1,9 @@
-export function createTelemetry({ application = 'default', intervalMs = 1000, now = () => Date.now(), setIntervalImpl = setInterval, clearIntervalImpl = clearInterval } = {}) {
+export function createTelemetry({ application = 'default', credentialName = undefined, database = undefined, scopes = undefined, intervalMs = 1000, now = () => Date.now(), setIntervalImpl = setInterval, clearIntervalImpl = clearInterval } = {}) {
   const stats = { queries: 0, failures: 0, retries: 0, reconnects: 0, failoverCount: 0, reconnectDelayMs: 0, inflight: 0, totalLatencyMs: 0, maxLatencyMs: 0 };
   let timer;
   const begin = () => { stats.inflight += 1; return now(); };
   const record = ({ latencyMs = 0, failed = false, retry = false, reconnect = false, failover = false } = {}) => { stats.queries += 1; stats.inflight = Math.max(0, stats.inflight - 1); stats.totalLatencyMs += latencyMs; stats.maxLatencyMs = Math.max(stats.maxLatencyMs, latencyMs); if (failed) stats.failures += 1; if (retry) stats.retries += 1; if (reconnect) stats.reconnects += 1; if (failover) stats.failoverCount += 1; };
-  const snapshot = () => ({ type: 'client.telemetry', application, ...stats, avgLatencyMs: stats.queries ? stats.totalLatencyMs / stats.queries : 0, sentAt: new Date(now()).toISOString() });
+  const snapshot = () => ({ type: 'client.telemetry', application, credentialName, database, scopes, ...stats, avgLatencyMs: stats.queries ? stats.totalLatencyMs / stats.queries : 0, sentAt: new Date(now()).toISOString() });
   const recordReconnect = ({ delayMs = 0, failover = false } = {}) => { stats.reconnects += 1; stats.reconnectDelayMs += Math.max(0, Number(delayMs) || 0); if (failover) stats.failoverCount += 1; };
   return { begin, record, recordReconnect, snapshot, start(stream) { if (timer) return; timer = setIntervalImpl(() => stream.sendTelemetry?.(snapshot()), intervalMs); timer.unref?.(); }, stop() { if (timer) clearIntervalImpl(timer); timer = undefined; } };
 }