@pellux/goodvibes-sdk 0.19.6 → 0.19.9

package/dist/_internal/transport-realtime/runtime-events.js

@@ -1,8 +1,8 @@
 // Synced from packages/transport-realtime/src/runtime-events.ts
-// Extracted from legacy source: src/runtime/transports/runtime-events-client.ts
 import { RUNTIME_EVENT_DOMAINS } from '../contracts/index.js';
 import { normalizeAuthToken, openRawServerSentEventStream as openServerSentEventStream, normalizeStreamReconnectPolicy, getStreamReconnectDelay, } from '../transport-http/index.js';
 import { buildUrl, normalizeBaseUrl } from '../transport-http/index.js';
+import { injectTraceparentAsync, invokeTransportObserver } from '../transport-core/index.js';
 import { createRemoteDomainEvents, } from './domain-events.js';
 /**
  * Returns a filtered view of a {@link RemoteRuntimeEvents} object where every
@@ -33,8 +33,8 @@ import { createRemoteDomainEvents, } from './domain-events.js';
 export { forSession as forSessionRuntime } from './domain-events.js';
 /** Default max reconnect attempts for WebSocket connections (finite to prevent infinite auth loops). */
 export const DEFAULT_WS_MAX_ATTEMPTS = 10;
-/** Maximum number of messages that may be queued in outboundQueue pending a producer API. */
-const MAX_OUTBOUND_QUEUE = 256;
+/** Maximum number of messages that may be queued in the outbound queue before the oldest entry is dropped. */
+const MAX_OUTBOUND_QUEUE = 1024;
 export function createRemoteRuntimeEvents(connect) {
     return createRemoteDomainEvents(RUNTIME_EVENT_DOMAINS, connect);
 }
@@ -53,26 +53,45 @@ export function buildWebSocketUrl(baseUrl, domains) {
     return url.toString();
 }
 export function createEventSourceConnector(baseUrl, token, fetchImpl, options = {}) {
+    const { observer } = options;
     const handleError = options.onError ?? (options.reconnect?.enabled ? (() => { }) : undefined);
     return async (domain, onEnvelope) => {
         const url = buildEventSourceUrl(baseUrl, domain);
         const getAuthToken = normalizeAuthToken(token ?? undefined);
+        // Inject W3C traceparent if OTel is active (async probe for SSE cold-start).
+        const sseHeaders = {};
+        await injectTraceparentAsync(sseHeaders);
+        // Notify observer of outbound SSE connection attempt.
+        invokeTransportObserver(() => observer?.onTransportActivity?.({ direction: 'send', url, kind: 'sse' }));
         return await openServerSentEventStream(fetchImpl, url, {
             onEvent: (eventName, payload) => {
                 if (eventName !== domain)
                     return;
                 if (!payload || typeof payload !== 'object')
                     return;
-                onEnvelope(payload);
+                const envelope = payload;
+                onEnvelope(envelope);
+                // Notify observer of inbound event.
+                invokeTransportObserver(() => {
+                    observer?.onTransportActivity?.({ direction: 'recv', url, kind: 'sse' });
+                    if (envelope.payload) {
+                        observer?.onEvent?.(envelope.payload);
+                    }
+                });
+            },
+            onError: (err) => {
+                invokeTransportObserver(() => observer?.onError?.(err instanceof Error ? err : new Error(String(err))));
+                handleError?.(err);
             },
-            onError: handleError,
         }, {
             reconnect: options.reconnect,
             getAuthToken,
+            headers: Object.keys(sseHeaders).length > 0 ? sseHeaders : undefined,
         });
     };
 }
 export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options = {}) {
+    const { observer } = options;
     return async (domain, onEnvelope) => {
         const url = buildWebSocketUrl(baseUrl, [domain]);
         const reconnect = options.reconnect;
@@ -88,9 +107,39 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
         let hasReceivedMessage = false;
         let socket = null;
         let reconnectTimer = null;
-        // TODO: producer API not yet wired. When added, bound queue size via
-        // MAX_OUTBOUND_QUEUE (see below) and drop oldest or reject with onError.
+        // Bounded outbound message queue — max MAX_OUTBOUND_QUEUE entries, drop-oldest policy.
+        // Messages pushed while the socket is not yet open or is reconnecting are buffered here
+        // and flushed on the next successful open event.
         const outboundQueue = [];
+        let droppedOutboundCount = 0;
+        /**
+         * Enqueue a message for delivery over this WebSocket connection.
+         *
+         * If the socket is currently open the message is sent immediately.
+         * If the socket is not yet open (or is reconnecting), the message is
+         * buffered and will be flushed once the connection is re-established.
+         *
+         * When the buffer is full (> MAX_OUTBOUND_QUEUE), the oldest pending
+         * message is silently dropped and a counter is incremented. Callers that
+         * need back-pressure should check `socket?.readyState` before calling.
+         *
+         * @param data - Serialised message string to send.
+         */
+        const emitLocal = (data) => {
+            if (socket && socket.readyState === WebSocket.OPEN) {
+                socket.send(data);
+                return;
+            }
+            if (outboundQueue.length >= MAX_OUTBOUND_QUEUE) {
+                // Drop oldest message to make room (drop-oldest policy).
+                outboundQueue.shift();
+                droppedOutboundCount += 1;
+                options.onError?.(new Error(`WebSocket outbound queue full (limit ${MAX_OUTBOUND_QUEUE}). Oldest message dropped; total dropped: ${droppedOutboundCount}.`));
+            }
+            outboundQueue.push(data);
+        };
+        // Notify caller of the emitter handle (for test/shim use cases).
+        options.onEmitter?.(emitLocal);
         const closeSocket = () => {
             if (!socket)
                 return;
@@ -124,11 +173,18 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             const authToken = (await normalizeAuthToken(token ?? undefined)()) ?? null;
             if (!authToken || !socket)
                 return;
+            // Notify observer of outbound WS connection.
+            invokeTransportObserver(() => observer?.onTransportActivity?.({ direction: 'send', url, kind: 'ws' }));
             // Send auth frame first, then drain any messages buffered during resolution.
+            // Inject traceparent into the auth frame for W3C Trace Context propagation over WebSocket.
+            const wsTraceHeaders = {};
+            await injectTraceparentAsync(wsTraceHeaders);
             socket.send(JSON.stringify({
                 type: 'auth',
                 token: authToken,
                 domains: [domain],
+                ...(wsTraceHeaders['traceparent'] ? { traceparent: wsTraceHeaders['traceparent'] } : {}),
+                ...(wsTraceHeaders['tracestate'] ? { tracestate: wsTraceHeaders['tracestate'] } : {}),
             }));
             flushOutboundQueue(socket);
         };
@@ -142,7 +198,15 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                         hasReceivedMessage = true;
                         reconnectAttempt = 0;
                     }
-                    onEnvelope(frame.payload);
+                    const wsPayload = frame.payload;
+                    onEnvelope(wsPayload);
+                    // Notify observer of inbound WS event.
+                    invokeTransportObserver(() => {
+                        observer?.onTransportActivity?.({ direction: 'recv', url, kind: 'ws' });
+                        if (wsPayload.payload) {
+                            observer?.onEvent?.(wsPayload.payload);
+                        }
+                    });
                 }
             }
             catch {
@@ -155,6 +219,7 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             scheduleReconnect();
         };
         const onError = (event) => {
+            invokeTransportObserver(() => observer?.onError?.(event instanceof Error ? event : new Error(String(event))));
             options.onError?.(event);
         };
         const connect = async () => {

package/dist/auth.d.ts

@@ -2,16 +2,38 @@ import type { SDKObserver } from './observer/index.js';
 import type { OperatorMethodInput, OperatorMethodOutput } from './_internal/contracts/index.js';
 import type { AuthTokenResolver } from './_internal/transport-http/index.js';
 import type { OperatorSdk } from './_internal/operator/index.js';
-import { PermissionResolver, SessionManager, TokenStore } from './_internal/platform/auth/index.js';
+import { AutoRefreshCoordinator, PermissionResolver, SessionManager, TokenStore } from './_internal/platform/auth/index.js';
+import type { AutoRefreshOptions } from './_internal/platform/auth/index.js';
 export { PermissionResolver, SessionManager, TokenStore } from './_internal/platform/auth/index.js';
 export type { OAuthStartState, OAuthTokenPayload } from './_internal/platform/auth/oauth-types.js';
 export type GoodVibesCurrentAuth = OperatorMethodOutput<'control.auth.current'>;
 export type GoodVibesLoginInput = OperatorMethodInput<'control.auth.login'>;
 export type GoodVibesLoginOutput = OperatorMethodOutput<'control.auth.login'>;
+/**
+ * Token storage interface for the GoodVibes SDK.
+ *
+ * Implement all three core methods. The optional `getTokenEntry` / `setTokenEntry`
+ * methods are used by auto-refresh to track token expiry without requiring
+ * consumers to change their existing `GoodVibesTokenStore` implementations.
+ */
 export interface GoodVibesTokenStore {
     getToken(): Promise<string | null>;
     setToken(token: string | null): Promise<void>;
     clearToken(): Promise<void>;
+    /**
+     * Return the current token and its expiry timestamp (unix ms).
+     * Optional: when absent, auto-refresh falls back to `getToken()` with no
+     * expiry tracking (leeway-based pre-flight checks are disabled).
+     */
+    getTokenEntry?(): Promise<{
+        token: string | null;
+        expiresAt?: number;
+    }>;
+    /**
+     * Persist a token alongside its expiry timestamp (unix ms).
+     * Optional: when absent, auto-refresh falls back to `setToken()`.
+     */
+    setTokenEntry?(token: string | null, expiresAt?: number): Promise<void>;
 }
 export interface BrowserTokenStoreOptions {
     readonly key?: string;
@@ -57,6 +79,12 @@ export interface GoodVibesAuthClient {
     /** Clear the stored token. Delegates to `TokenStore.clearToken()`. */
     clearToken(): Promise<void>;
 }
+/**
+ * Options for the auto-refresh feature on the auth client.
+ *
+ * @see AutoRefreshOptions
+ */
+export type { AutoRefreshOptions };
 /**
  * Create a simple in-memory token store.
  *
@@ -70,7 +98,7 @@ export interface GoodVibesAuthClient {
  * const sdk = createGoodVibesSdk({ baseUrl: '...', tokenStore: store });
  * await sdk.auth.clearToken(); // clears only in-memory
  */
-export declare function createMemoryTokenStore(initialToken?: string | null): GoodVibesTokenStore;
+export declare function createMemoryTokenStore(initialToken?: string | null, initialExpiresAt?: number): GoodVibesTokenStore;
 /**
  * Create a token store backed by `localStorage` (or a custom `Storage`).
  *
@@ -108,5 +136,12 @@ export declare function createBrowserTokenStore(options?: BrowserTokenStoreOptio
  * // Later: clear the session
  * await sdk.auth.clearToken();
  */
-export declare function createGoodVibesAuthClient(operator: OperatorSdk, tokenStore: GoodVibesTokenStore | null, getAuthToken?: AuthTokenResolver, observer?: SDKObserver): GoodVibesAuthClient;
+export declare function createGoodVibesAuthClient(operator: OperatorSdk, tokenStore: GoodVibesTokenStore | null, getAuthToken?: AuthTokenResolver, observer?: SDKObserver, autoRefreshOptions?: AutoRefreshOptions, 
+/**
+ * Optional pre-built `AutoRefreshCoordinator`. When provided, it is reused
+ * directly (no new coordinator is constructed). This allows `createGoodVibesSdk`
+ * to share a single coordinator instance between the transport middleware and
+ * the auth client, avoiding duplicate refresh calls.
+ */
+existingCoordinator?: AutoRefreshCoordinator | null): GoodVibesAuthClient;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,UAAU,EACX,MAAM,oCAAoC,CAAC;AAW5C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AACpG,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAEnG,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AAChF,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;AAC5E,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,oBAAoB,CAAC,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,qFAAqF;IACrF,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;;OAOG;IACH,kBAAkB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,kBAAkB,CAAC;IACvE,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzC,KAAK,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtG,wEAAwE;IACxE,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,sEAAsE;IACtE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,GAAE,MAAM,GAAG,IAAW,GAAG,mBAAmB,CAa9F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,mBAAmB,CAmBnG;AAwBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,mBAAmB,GAAG,IAAI,EACtC,YAAY,CAAC,EAAE,iBAAiB,EAChC,QAAQ,CAAC,EAAE,WAAW,GACrB,mBAAmB,CAiErB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth.js

@@ -1,6 +1,6 @@
 import { ConfigurationError } from './_internal/errors/index.js';
 import { invokeObserver } from './observer/index.js';
-import { PermissionResolver, SessionManager, TokenStore, } from './_internal/platform/auth/index.js';
+import { AutoRefreshCoordinator, PermissionResolver, SessionManager, TokenStore, } from './_internal/platform/auth/index.js';
 // Re-export focused responsibility classes for consumers who prefer
 // narrower, single-concern APIs over the combined GoodVibesAuthClient facade.
 // NOTE: OAuthClient is intentionally NOT re-exported here. It depends on
@@ -30,17 +30,29 @@ function requireStorage(storage) {
  * const sdk = createGoodVibesSdk({ baseUrl: '...', tokenStore: store });
  * await sdk.auth.clearToken(); // clears only in-memory
  */
-export function createMemoryTokenStore(initialToken = null) {
+export function createMemoryTokenStore(initialToken = null, initialExpiresAt) {
     let token = initialToken;
+    let expiresAt = initialExpiresAt;
     return {
         async getToken() {
             return token;
         },
         async setToken(nextToken) {
             token = nextToken;
+            // When setToken is called directly (not via setTokenEntry), clear expiry
+            // to avoid stale expiry data attached to a manually-set token.
+            expiresAt = undefined;
         },
         async clearToken() {
             token = null;
+            expiresAt = undefined;
+        },
+        async getTokenEntry() {
+            return { token, expiresAt };
+        },
+        async setTokenEntry(nextToken, nextExpiresAt) {
+            token = nextToken;
+            expiresAt = nextExpiresAt;
         },
     };
 }
@@ -62,6 +74,7 @@ export function createMemoryTokenStore(initialToken = null) {
 export function createBrowserTokenStore(options = {}) {
     const storage = requireStorage(options.storage);
     const key = options.key?.trim() || 'goodvibes.token';
+    const expiresAtKey = `${key}.expiresAt`;
     return {
         async getToken() {
             const value = storage.getItem(key);
@@ -70,12 +83,37 @@ export function createBrowserTokenStore(options = {}) {
         async setToken(token) {
             if (!token) {
                 storage.removeItem(key);
+                storage.removeItem(expiresAtKey);
                 return;
             }
             storage.setItem(key, token);
+            // Clear expiry when set via setToken (no expiry info provided).
+            storage.removeItem(expiresAtKey);
         },
         async clearToken() {
             storage.removeItem(key);
+            storage.removeItem(expiresAtKey);
+        },
+        async getTokenEntry() {
+            const value = storage.getItem(key);
+            const token = value && value.trim() ? value : null;
+            const expiresAtStr = storage.getItem(expiresAtKey);
+            const expiresAt = expiresAtStr ? parseInt(expiresAtStr, 10) : undefined;
+            return { token, expiresAt: Number.isFinite(expiresAt) ? expiresAt : undefined };
+        },
+        async setTokenEntry(token, expiresAt) {
+            if (!token) {
+                storage.removeItem(key);
+                storage.removeItem(expiresAtKey);
+                return;
+            }
+            storage.setItem(key, token);
+            if (expiresAt !== undefined) {
+                storage.setItem(expiresAtKey, String(expiresAt));
+            }
+            else {
+                storage.removeItem(expiresAtKey);
+            }
         },
     };
 }
@@ -115,11 +153,34 @@ function assertWritableTokenStore(tokenStore) {
  * // Later: clear the session
  * await sdk.auth.clearToken();
  */
-export function createGoodVibesAuthClient(operator, tokenStore, getAuthToken, observer) {
+export function createGoodVibesAuthClient(operator, tokenStore, getAuthToken, observer, autoRefreshOptions, 
+/**
+ * Optional pre-built `AutoRefreshCoordinator`. When provided, it is reused
+ * directly (no new coordinator is constructed). This allows `createGoodVibesSdk`
+ * to share a single coordinator instance between the transport middleware and
+ * the auth client, avoiding duplicate refresh calls.
+ */
+existingCoordinator) {
     // Construct the split-class instances that own each concern.
     // The facade delegates to these rather than duplicating logic.
     const ts = tokenStore ? new TokenStore(tokenStore) : null;
     const sm = new SessionManager(operator, ts);
+    // Use the provided coordinator if available; otherwise build one.
+    const coordinator = existingCoordinator !== undefined
+        ? existingCoordinator
+        : (() => {
+            const autoRefresh = autoRefreshOptions?.autoRefresh ?? true;
+            const refreshLeewayMs = autoRefreshOptions?.refreshLeewayMs ?? 60_000;
+            return tokenStore && autoRefresh
+                ? new AutoRefreshCoordinator({
+                    tokenStore,
+                    autoRefresh,
+                    refreshLeewayMs,
+                    refresh: autoRefreshOptions?.refresh,
+                    observer,
+                })
+                : null;
+        })();
     return {
         get writable() {
             return sm.writable;
@@ -134,6 +195,10 @@ export function createGoodVibesAuthClient(operator, tokenStore, getAuthToken, ob
             return new PermissionResolver(snapshot);
         },
         async current() {
+            if (coordinator) {
+                await coordinator.ensureFreshToken();
+                return coordinator.withRetryOn401(() => sm.current());
+            }
             return sm.current();
         },
         async login(input, options = {}) {

package/dist/client.d.ts

@@ -1,9 +1,10 @@
 import { type OperatorSdk } from './_internal/operator/index.js';
 import { type PeerSdk } from './_internal/peer/index.js';
-import type { AuthTokenResolver, HeaderResolver, HttpRetryPolicy, StreamReconnectPolicy } from './_internal/transport-http/index.js';
+import type { AuthTokenResolver, HeaderResolver, HttpRetryPolicy, StreamReconnectPolicy, TransportMiddleware } from './_internal/transport-http/index.js';
 import { type RemoteRuntimeEvents } from './_internal/transport-realtime/index.js';
 import type { AnyRuntimeEvent } from './_internal/platform/runtime/events/index.js';
-import { type GoodVibesAuthClient, type GoodVibesTokenStore } from './auth.js';
+import { type AutoRefreshOptions, type GoodVibesAuthClient, type GoodVibesTokenStore } from './auth.js';
+import type { SDKObserver } from './observer/index.js';
 /**
  * Discriminated union of all runtime events emitted by the GoodVibes daemon.
  *
@@ -108,6 +109,50 @@ export interface GoodVibesSdkOptions {
      * reconnect policies, error callback).
      */
     readonly realtime?: GoodVibesRealtimeOptions;
+    /**
+     * Optional observer for SDK-level observability hooks.
+     *
+     * Pass a `SDKObserver` implementation (or one of the built-in adapters
+     * like `createConsoleObserver` / `createOpenTelemetryObserver`) to receive
+     * callbacks for auth transitions, transport activity, events, and errors.
+     *
+     * All observer methods are wrapped in a silent try/catch — observer
+     * exceptions never propagate into SDK logic.
+     */
+    readonly observer?: SDKObserver;
+    /**
+     * Initial middleware chain applied to every HTTP request/response cycle.
+     *
+     * Middleware functions receive a mutable `TransportContext` and a `next()`
+     * callback. They run in the order provided (outer-first, onion model).
+     *
+     * Additional middleware can be appended at any time via `sdk.use(mw)`.
+     *
+     * @example
+     * const sdk = createGoodVibesSdk({
+     *   baseUrl: 'https://daemon.example.com',
+     *   middleware: [
+     *     async (ctx, next) => {
+     *       ctx.headers['X-Request-Id'] = crypto.randomUUID();
+     *       await next();
+     *     },
+     *   ],
+     * });
+     */
+    readonly middleware?: TransportMiddleware[];
+    /**
+     * Options for silent token auto-refresh.
+     *
+     * - `autoRefresh` — when `false`, disables silent refresh entirely and lets
+     *   401 responses propagate to the caller immediately. Default: `true`.
+     * - `refreshLeewayMs` — milliseconds before token expiry to trigger a
+     *   pre-flight refresh. Default: 60_000 (1 minute).
+     * - `refresh` — optional callback invoked to obtain a new token on pre-flight
+     *   leeway trigger or reactive 401. When absent, pre-flight is a no-op and
+     *   401 retry re-reads the token store (useful when an external party updates
+     *   it). See `AutoRefreshOptions.refresh` for a full example.
+     */
+    readonly autoRefresh?: AutoRefreshOptions;
 }
 /**
  * Options controlling realtime transport behaviour.
@@ -184,6 +229,20 @@ export interface GoodVibesSdk {
      * @see https://github.com/mgd34msu/goodvibes-sdk/blob/main/docs/realtime-and-telemetry.md
      */
     readonly realtime: GoodVibesRealtime;
+    /**
+     * Append a middleware to the SDK's HTTP transport chain.
+     *
+     * Multiple `use()` calls compose in order (outer-first). The method is
+     * idempotent in the sense that each call simply appends — call it once per
+     * middleware to avoid double-registration.
+     *
+     * @example
+     * sdk.use(async (ctx, next) => {
+     *   ctx.headers['X-Tenant-Id'] = 'acme';
+     *   await next();
+     * });
+     */
+    use(middleware: TransportMiddleware): void;
 }
 /**
  * Create a GoodVibes SDK instance.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,WAAW,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,KAAK,OAAO,EAEb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAE1C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IAErC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IAClD,YAAY,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CACzF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AA+CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CA+Cd"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -4,10 +4,11 @@ import { createPeerSdk, } from './_internal/peer/index.js';
 import { normalizeAuthToken } from './_internal/transport-http/index.js';
 import { createEventSourceConnector, createRemoteRuntimeEvents, createWebSocketConnector, } from './_internal/transport-realtime/index.js';
 import { createGoodVibesAuthClient, createMemoryTokenStore, } from './auth.js';
+import { AutoRefreshCoordinator, createAutoRefreshMiddleware, } from './_internal/platform/auth/index.js';
 function requireBaseUrl(baseUrl) {
     const normalized = baseUrl.trim();
     if (!normalized) {
-        throw new ConfigurationError('GoodVibes baseUrl is required');
+        throw new ConfigurationError('GoodVibes baseUrl is required. Pass a non-empty baseUrl in your createGoodVibesSdk options (e.g. "https://my-daemon.example.com").');
     }
     return normalized;
 }
@@ -37,6 +38,7 @@ function createClientOptions(options) {
         ...(options.headers ? { headers: options.headers } : {}),
         ...(options.getHeaders ? { getHeaders: options.getHeaders } : {}),
         ...(options.retry ? { retry: options.retry } : {}),
+        ...(options.middleware ? { middleware: options.middleware } : {}),
     };
 }
 /**
@@ -63,36 +65,95 @@ function createClientOptions(options) {
 export function createGoodVibesSdk(options) {
     const baseUrl = requireBaseUrl(options.baseUrl);
     const tokenStore = options.tokenStore ?? (options.getAuthToken ? null : createMemoryTokenStore(options.authToken ?? null));
-    const authToken = options.authToken ?? null;
     const getAuthToken = tokenStore
         ? () => tokenStore.getToken()
         : options.getAuthToken;
     // Single normalized resolver used by realtime connectors.
     const tokenResolver = normalizeAuthToken(getAuthToken ?? options.authToken ?? undefined);
     const fetchImpl = () => requireFetchImplementation(options.fetch);
+    const { observer } = options;
+    // Build the auto-refresh coordinator when a writable token store is present
+    // and autoRefresh is not explicitly disabled.
+    const autoRefreshEnabled = (options.autoRefresh?.autoRefresh ?? true) && tokenStore !== null;
+    const coordinator = autoRefreshEnabled && tokenStore
+        ? new AutoRefreshCoordinator({
+            tokenStore,
+            autoRefresh: true,
+            refreshLeewayMs: options.autoRefresh?.refreshLeewayMs ?? 60_000,
+            refresh: options.autoRefresh?.refresh,
+            observer,
+        })
+        : null;
+    // Build the merged middleware list: auto-refresh first (if enabled), then
+    // consumer-provided middleware. This ensures the auto-refresh pre-flight runs
+    // before any consumer middleware sees ctx.headers.Authorization, and that the
+    // reactive 401 retry is transparent to consumer middleware.
+    //
+    // The transport reference for the retry callback is resolved lazily: we pass
+    // a proxy object whose `requestJson` property is populated immediately after
+    // createOperatorSdk / createPeerSdk returns. Because the middleware only calls
+    // `transport.requestJson` on a reactive 401 (not at construction time), the
+    // holder is always populated before it is accessed.
+    // Lazy transport proxy: populated after createOperatorSdk / createPeerSdk.
+    // The middleware only invokes requestJson on a reactive 401 — never at
+    // construction time — so the proxy is always populated before first use.
+    let operatorRequestJson = null;
+    let peerRequestJson = null;
+    const buildMiddleware = (getRequestJson) => {
+        const mws = [];
+        if (coordinator) {
+            // Wrap the coordinator + lazy transport reference into a minimal proxy
+            // that satisfies createAutoRefreshMiddleware's Pick<HttpJsonTransport, 'requestJson'>.
+            const transportProxy = {
+                requestJson(url, opts) {
+                    const rj = getRequestJson();
+                    if (!rj)
+                        throw new Error('Auto-refresh: transport not yet initialised');
+                    return rj(url, opts);
+                },
+            };
+            mws.push(createAutoRefreshMiddleware(coordinator, transportProxy, tokenStore));
+        }
+        if (options.middleware) {
+            mws.push(...options.middleware);
+        }
+        return mws;
+    };
     const operator = createOperatorSdk(createClientOptions({
         ...options,
         tokenStore: tokenStore ?? undefined,
+        middleware: buildMiddleware(() => operatorRequestJson),
     }));
+    // Populate the lazy reference now that the transport is fully constructed.
+    operatorRequestJson = (url, opts) => operator.transport.requestJson(url, opts);
     const peer = createPeerSdk(createClientOptions({
         ...options,
         tokenStore: tokenStore ?? undefined,
+        middleware: buildMiddleware(() => peerRequestJson),
     }));
+    // Populate the lazy reference now that the transport is fully constructed.
+    peerRequestJson = (url, opts) => peer.transport.requestJson(url, opts);
     return {
         operator,
         peer,
-        auth: createGoodVibesAuthClient(operator, tokenStore, getAuthToken),
+        auth: createGoodVibesAuthClient(operator, tokenStore, getAuthToken, observer, options.autoRefresh, coordinator),
+        use(middleware) {
+            operator.transport.use(middleware);
+            peer.transport.use(middleware);
+        },
         realtime: {
             viaSse() {
                 return createRemoteRuntimeEvents(createEventSourceConnector(baseUrl, tokenResolver, fetchImpl(), {
                     reconnect: options.realtime?.sseReconnect,
                     onError: options.realtime?.onError,
+                    observer,
                 }));
             },
             viaWebSocket(webSocketImpl) {
                 return createRemoteRuntimeEvents(createWebSocketConnector(baseUrl, tokenResolver, requireWebSocketImplementation(webSocketImpl ?? options.WebSocketImpl), {
                     reconnect: options.realtime?.webSocketReconnect,
                     onError: options.realtime?.onError,
+                    observer,
                 }));
             },
         },

package/dist/expo.d.ts

@@ -17,4 +17,5 @@ export interface ExpoGoodVibesSdkOptions extends ReactNativeGoodVibesSdkOptions
  */
 export { forSession } from './transport-realtime.js';
 export declare function createExpoGoodVibesSdk(options: ExpoGoodVibesSdkOptions): ReactNativeGoodVibesSdk;
+export { createExpoSecureTokenStore, type ExpoSecureTokenStore, type ExpoSecureTokenStoreOptions, type ExpoSecureStoreAccessible, } from './_internal/platform/auth/expo-secure-token-store.js';
 //# sourceMappingURL=expo.d.ts.map

package/dist/expo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expo.d.ts","sourceRoot":"","sources":["../src/expo.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACpC,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;CAAG;AAElF;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAEhG"}
+{"version":3,"file":"expo.d.ts","sourceRoot":"","sources":["../src/expo.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACpC,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;CAAG;AAElF;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAEhG;AAED,OAAO,EACL,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,GAC/B,MAAM,sDAAsD,CAAC"}

package/dist/expo.js

@@ -17,3 +17,4 @@ export { forSession } from './transport-realtime.js';
 export function createExpoGoodVibesSdk(options) {
     return createReactNativeGoodVibesSdk(options);
 }
+export { createExpoSecureTokenStore, } from './_internal/platform/auth/expo-secure-token-store.js';