@relayfile/sdk 0.6.11 → 0.6.12

package/dist/client.d.ts

@@ -51,6 +51,18 @@ export declare class RelayFileClient {
     private readonly userAgent?;
     private readonly retryOptions;
     constructor(options: RelayFileClientOptions);
+    /**
+     * Resolve the current access token via the configured token provider.
+     *
+     * Components that need a fresh JWT for out-of-band auth (the WebSocket
+     * upgrade handshake, signed URLs, downstream services that proxy Relayfile
+     * tokens) should call this on every connection rather than caching the
+     * value, so token rotation/refresh propagates without restart.
+     *
+     * Always returns a Promise so callers don't need to special-case the
+     * sync-vs-async tokenProvider shapes.
+     */
+    getToken(): Promise<string>;
     listTree(workspaceId: string, options?: ListTreeOptions): Promise<TreeResponse>;
     readFile(workspaceId: string, path: string, correlationId?: string, signal?: AbortSignal): Promise<FileReadResponse>;
     readFile(input: ReadFileInput): Promise<FileReadResponse>;

package/dist/client.js

@@ -171,6 +171,20 @@ export class RelayFileClient {
         this.userAgent = options.userAgent;
         this.retryOptions = normalizeRetryOptions(options.retry);
     }
+    /**
+     * Resolve the current access token via the configured token provider.
+     *
+     * Components that need a fresh JWT for out-of-band auth (the WebSocket
+     * upgrade handshake, signed URLs, downstream services that proxy Relayfile
+     * tokens) should call this on every connection rather than caching the
+     * value, so token rotation/refresh propagates without restart.
+     *
+     * Always returns a Promise so callers don't need to special-case the
+     * sync-vs-async tokenProvider shapes.
+     */
+    async getToken() {
+        return resolveToken(this.tokenProvider);
+    }
     async listTree(workspaceId, options = {}) {
         const query = buildQuery({
             path: options.path ?? "/",

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.
 export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
 export { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 export { WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
-export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState } from "./sync.js";
+export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState, type RelayFileSyncTokenProvider } from "./sync.js";
 export { onWrite, pathMatches, type OnWriteClient, type OnWriteHandler, type OnWriteHandlerError, type OnWriteOptions } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";

package/dist/onWrite.d.ts

@@ -1,6 +1,6 @@
 import type { WriteEvent, WriteEventOperation } from "@relayfile/core";
 import { RelayFileClient } from "./client.js";
-import { type RelayFileSyncSocket } from "./sync.js";
+import { type RelayFileSyncSocket, type RelayFileSyncTokenProvider } from "./sync.js";
 export type OnWriteHandler = (event: WriteEvent) => void | Promise<void>;
 export interface OnWriteHandlerError {
     pattern: string;
@@ -17,10 +17,30 @@ export interface OnWriteOptions {
     operations?: WriteEventOperation[];
     signal?: AbortSignal;
     baseUrl?: string;
-    token?: string;
+    /**
+     * Optional WebSocket auth override. Accepts the same `string | () =>
+     * string | Promise<string>` shape as the underlying sync.
+     *
+     * If omitted, onWrite auto-derives WS auth from `client.getToken()` — the
+     * same JWT the REST API is using — and re-resolves it on every reconnect
+     * so token rotation propagates without restart. **Most callers should
+     * leave this unset.** Passing a literal string is back-compat for older
+     * code; passing a factory is the right shape for production.
+     */
+    token?: RelayFileSyncTokenProvider;
     webSocketFactory?: (url: string) => RelayFileSyncSocket;
     pingIntervalMs?: number;
     pongTimeoutMs?: number;
+    /**
+     * Notification hook fired when the underlying sync degrades to HTTP
+     * polling because the WebSocket failed to open. Useful for surfacing a
+     * "live updates paused" banner. The SDK also `console.warn`s and emits
+     * an `error` regardless.
+     */
+    onPollingFallback?: (info: {
+        reason: string;
+        cause?: unknown;
+    }) => void;
 }
 export declare function pathMatches(pattern: string, path: string): boolean;
 export declare function onWrite(pattern: string, handler: OnWriteHandler, options?: OnWriteOptions): () => void;

package/dist/onWrite.js

@@ -69,7 +69,8 @@ export function onWrite(pattern, handler, options = {}) {
         token: options.token,
         webSocketFactory: options.webSocketFactory,
         pingIntervalMs: options.pingIntervalMs,
-        pongTimeoutMs: options.pongTimeoutMs
+        pongTimeoutMs: options.pongTimeoutMs,
+        onPollingFallback: options.onPollingFallback
     });
     debugLog("registered", { id: registration.id, pattern: normalizedPattern, workspaceId });
     return () => {
@@ -115,11 +116,21 @@ class OnWriteDispatcher {
         if (this.sync) {
             return;
         }
+        // Token resolution order:
+        //  1. options.token (literal or factory) — back-compat for callers that
+        //     mint their own auth.
+        //  2. RELAYFILE_TOKEN env var.
+        //  3. fall through to undefined → RelayFileSync auto-derives from
+        //     `client.getToken()` (the recommended path; same JWT as REST).
+        // (Bug 1 fix: previously, omitting `token` here passed `undefined` and
+        // the WS handshake silently failed with no auth, dropping us into
+        // backwards-walking polling forever.)
+        const token = options.token ?? readEnv("RELAYFILE_TOKEN") ?? undefined;
         this.sync = RelayFileSync.connect({
             client: this.client,
             workspaceId: options.workspaceId,
             baseUrl: options.baseUrl ?? readEnv("RELAYFILE_BASE_URL") ?? DEFAULT_RELAYFILE_BASE_URL,
-            token: options.token ?? readEnv("RELAYFILE_TOKEN"),
+            token,
             reconnect: {
                 minDelayMs: DEFAULT_RECONNECT_MIN_DELAY_MS,
                 maxDelayMs: DEFAULT_RECONNECT_MAX_DELAY_MS
@@ -127,6 +138,7 @@ class OnWriteDispatcher {
             webSocketFactory: options.webSocketFactory,
             pingIntervalMs: options.pingIntervalMs,
             pongTimeoutMs: options.pongTimeoutMs,
+            onPollingFallback: options.onPollingFallback,
             onEvent: (event) => {
                 void this.dispatch(event);
             }

package/dist/sync.d.ts

@@ -1,5 +1,13 @@
 import type { RelayFileClient } from "./client.js";
 import type { FilesystemEvent } from "./types.js";
+/**
+ * WebSocket auth source for {@link RelayFileSyncOptions.token}.
+ *
+ * The function form is preferred for production: it is re-invoked on every
+ * (re)connect, so token rotation/refresh propagates without restarting the
+ * sync. The plain string form is kept for backward compatibility and tests.
+ */
+export type RelayFileSyncTokenProvider = string | (() => string | undefined | Promise<string | undefined>);
 export type RelayFileSyncState = "idle" | "connecting" | "open" | "polling" | "reconnecting" | "closed";
 export interface RelayFileSyncPong {
     type: "pong";
@@ -14,7 +22,16 @@ export interface RelayFileSyncOptions {
     client: RelayFileClient;
     workspaceId: string;
     baseUrl?: string;
-    token?: string;
+    /**
+     * WebSocket auth token. Accepts either a literal string or a (sync/async)
+     * factory. The factory form is re-invoked on every (re)connect so token
+     * rotation propagates transparently.
+     *
+     * If omitted, sync resolves the token via `client.getToken()` on each
+     * connect — i.e. the same JWT the REST methods are using. Callers should
+     * normally NOT pass this and let it inherit from the client.
+     */
+    token?: RelayFileSyncTokenProvider;
     cursor?: string;
     preferPolling?: boolean;
     pollIntervalMs?: number;
@@ -24,6 +41,17 @@ export interface RelayFileSyncOptions {
     signal?: AbortSignal;
     webSocketFactory?: (url: string) => RelayFileSyncSocket;
     onEvent?: (event: FilesystemEvent) => void;
+    /**
+     * Notification hook invoked when the sync degrades to HTTP polling because
+     * the WebSocket failed to open or was rejected by the server. Live events
+     * will be delayed by `pollIntervalMs` while in this mode. Use this to
+     * surface a UI banner or alert; the SDK also emits `console.warn` and an
+     * `error` event regardless of whether this is wired.
+     */
+    onPollingFallback?: (info: {
+        reason: string;
+        cause?: unknown;
+    }) => void;
 }
 export interface RelayFileSyncSocket {
     addEventListener(type: "open", handler: (event: Event) => void): void;
@@ -46,7 +74,7 @@ export declare class RelayFileSync {
     private readonly client;
     private readonly workspaceId;
     private readonly baseUrl?;
-    private readonly token?;
+    private readonly tokenProvider?;
     private readonly pollIntervalMs;
     private readonly pingIntervalMs;
     private readonly pongTimeoutMs;
@@ -54,9 +82,13 @@ export declare class RelayFileSync {
     private readonly preferPolling;
     private readonly signal?;
     private readonly webSocketFactory;
+    private readonly onPollingFallback?;
     private readonly handlers;
     private state;
     private cursor?;
+    private readonly polledEventIds;
+    private readonly polledEventOrder;
+    private firstPollComplete;
     private socket?;
     private started;
     private stopped;
@@ -74,9 +106,12 @@ export declare class RelayFileSync {
     stop(): Promise<void>;
     on<TEventName extends RelayFileSyncEventName>(event: TEventName, handler: RelayFileSyncHandlerMap[TEventName]): () => void;
     private shouldUsePolling;
+    private resolveWsTokenMaybeSync;
     private openWebSocket;
+    private openWebSocketWithToken;
     private startPolling;
     private pollLoop;
+    private rememberPolledEvent;
     private handleSocketMessage;
     private startPingLoop;
     private forceReconnect;

package/dist/sync.js

@@ -2,6 +2,23 @@ const DEFAULT_POLL_INTERVAL_MS = 5000;
 const DEFAULT_PING_INTERVAL_MS = 30000;
 const DEFAULT_RECONNECT_MIN_DELAY_MS = 250;
 const DEFAULT_RECONNECT_MAX_DELAY_MS = 5000;
+// Cap on the dedupe cache used in polling mode. Sized large enough that no
+// realistic workspace burst can churn through it within one poll interval
+// (the events API is itself capped at ~1000 per page), small enough to keep
+// memory bounded across long-lived processes.
+const POLLING_DEDUPE_CACHE_LIMIT = 2048;
+function warnPollingFallback(reason, cause) {
+    // Always-on warning (NOT gated by RELAYFILE_SDK_DEBUG) because silent
+    // degradation to polling has historically masked real auth/connectivity
+    // bugs for hours at a time. Customers running the SDK in a Node service
+    // see the warning in their normal logs without any opt-in.
+    if (typeof console === "undefined" || typeof console.warn !== "function") {
+        return;
+    }
+    const detail = cause instanceof Error ? cause.message : cause !== undefined ? String(cause) : "";
+    const suffix = detail ? ` (${reason}: ${detail})` : ` (${reason})`;
+    console.warn(`[relayfile-sdk] WebSocket connect failed; falling back to HTTP polling. Live events will be delayed.${suffix}`);
+}
 const debugEnabled = (() => {
     try {
         const value = globalThis.process?.env?.RELAYFILE_SDK_DEBUG;
@@ -75,7 +92,10 @@ export class RelayFileSync {
     client;
     workspaceId;
     baseUrl;
-    token;
+    // Resolved on every connect attempt (string form is wrapped into a constant
+    // factory at construction time). `undefined` means "fall back to
+    // client.getToken()" — same JWT the REST methods use.
+    tokenProvider;
     pollIntervalMs;
     pingIntervalMs;
     pongTimeoutMs;
@@ -83,6 +103,7 @@ export class RelayFileSync {
     preferPolling;
     signal;
     webSocketFactory;
+    onPollingFallback;
     handlers = {
         event: new Set(),
         error: new Set(),
@@ -93,6 +114,9 @@ export class RelayFileSync {
     };
     state = "idle";
     cursor;
+    polledEventIds = new Set();
+    polledEventOrder = [];
+    firstPollComplete = false;
     socket;
     started = false;
     stopped = false;
@@ -112,8 +136,21 @@ export class RelayFileSync {
         this.client = options.client;
         this.workspaceId = options.workspaceId;
         this.baseUrl = options.baseUrl?.replace(/\/+$/, "");
-        this.token = options.token;
+        // Normalize token into a factory. `undefined` is preserved so the open
+        // path knows to fall back to `client.getToken()` (the recommended path —
+        // the WebSocket then auto-uses the same JWT the REST API is using).
+        if (options.token === undefined) {
+            this.tokenProvider = undefined;
+        }
+        else if (typeof options.token === "function") {
+            this.tokenProvider = options.token;
+        }
+        else {
+            const literal = options.token;
+            this.tokenProvider = () => literal;
+        }
         this.cursor = options.cursor;
+        this.onPollingFallback = options.onPollingFallback;
         this.pollIntervalMs = Math.max(1, Math.floor(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS));
         this.pingIntervalMs = Math.max(1, Math.floor(options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS));
         // Default the pong timeout to 2x ping interval so a single missed pong
@@ -161,7 +198,9 @@ export class RelayFileSync {
         }
         this.started = true;
         if (this.shouldUsePolling()) {
-            this.startPolling();
+            // Caller explicitly opted into polling, or there's no baseUrl to
+            // upgrade to wss. NOT a fallback — no warn here.
+            this.startPolling("explicit");
             return;
         }
         this.openWebSocket(false);
@@ -193,9 +232,63 @@ export class RelayFileSync {
         };
     }
     shouldUsePolling() {
-        return this.preferPolling || !this.baseUrl || !this.token;
+        // Token availability is no longer required up-front — the WS opener
+        // resolves it on demand from either `options.token` (a literal/factory)
+        // or `client.getToken()`. We only force polling when the caller asked
+        // for it or there is no baseUrl to derive a wss URL from.
+        return this.preferPolling || !this.baseUrl;
+    }
+    // Resolve a token for the WS upgrade. Returns either a string directly
+    // (sync fast-path; preserves the synchronous "start() → factory called"
+    // contract that pre-existed Bug 1's fix) or a Promise (async slow-path;
+    // factory is invoked on the next microtask). `undefined` means "no token
+    // available — the server may still accept the upgrade if it's configured
+    // for unauthenticated mode in tests/local-dev".
+    resolveWsTokenMaybeSync() {
+        if (this.tokenProvider) {
+            // Most production providers return synchronously (JWT pulled from a
+            // mutable cell that a refresh task updates in the background), so the
+            // sync path is the common case.
+            return this.tokenProvider();
+        }
+        // Auto-derive from the client's tokenProvider — the same JWT the REST
+        // surface is using. Bug 1 fix: callers no longer have to thread
+        // `token: await client.tokenProvider()` through every onWrite() call.
+        // client.getToken is always async (returns a Promise), so we land on
+        // the slow path here. That's fine: the WS open is async anyway.
+        return this.client.getToken();
     }
     openWebSocket(isReconnect) {
+        if (this.stopped) {
+            return;
+        }
+        this.setState(isReconnect ? "reconnecting" : "connecting");
+        // Resolve a fresh token on every (re)connect attempt. This is what
+        // makes mid-session token rotation transparent: the watchdog/close
+        // handler reconnects, we re-call the factory, and the new socket comes
+        // up with the new JWT. (Bug 4: pre-fix, the token was captured once at
+        // construction and a 4001/auth close on rotation triggered an infinite
+        // reconnect loop with the stale token.)
+        let resolved;
+        try {
+            resolved = this.resolveWsTokenMaybeSync();
+        }
+        catch (error) {
+            this.emit("error", error instanceof Error ? error : new Error("Failed to resolve WebSocket auth token."));
+            this.startPolling("token-resolution-failed", error);
+            return;
+        }
+        if (resolved && typeof resolved.then === "function") {
+            // Async path. The factory call gets deferred to the next microtask.
+            resolved.then((token) => this.openWebSocketWithToken(token), (error) => {
+                this.emit("error", error instanceof Error ? error : new Error("Failed to resolve WebSocket auth token."));
+                this.startPolling("token-resolution-failed", error);
+            });
+            return;
+        }
+        this.openWebSocketWithToken(resolved);
+    }
+    openWebSocketWithToken(token) {
         if (this.stopped) {
             return;
         }
@@ -203,17 +296,16 @@ export class RelayFileSync {
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
         // Pass token in query string — the server authenticates during the HTTP
         // upgrade handshake via r.URL.Query().Get("token").
-        if (this.token) {
-            url.searchParams.set("token", this.token);
+        if (token) {
+            url.searchParams.set("token", token);
         }
-        this.setState(isReconnect ? "reconnecting" : "connecting");
         let socket;
         try {
             socket = this.webSocketFactory(url.toString());
         }
         catch (error) {
             this.emit("error", error instanceof Error ? error : new Error("Failed to create WebSocket connection."));
-            this.startPolling();
+            this.startPolling("ws-factory-threw", error);
             return;
         }
         this.socket = socket;
@@ -273,16 +365,29 @@ export class RelayFileSync {
                 return;
             }
             if (!this.reconnect.enabled) {
-                this.startPolling();
+                this.startPolling("ws-closed-no-reconnect", { code: event?.code, reason: event?.reason });
                 return;
             }
             this.scheduleReconnect();
         });
     }
-    startPolling() {
+    startPolling(reason = "fallback", cause) {
         if (this.pollingPromise || this.stopped) {
             return;
         }
+        // Always-on warning + structured callback whenever we drop into polling
+        // *involuntarily*. `explicit` means the caller asked for it (preferPolling
+        // or no baseUrl) and we stay quiet — anything else is a real degradation
+        // signal that previously took hours to detect.
+        if (reason !== "explicit") {
+            warnPollingFallback(reason, cause);
+            try {
+                this.onPollingFallback?.({ reason, cause });
+            }
+            catch (error) {
+                debugLog("onPollingFallback handler threw", error);
+            }
+        }
         this.setState("polling");
         this.pollingPromise = this.pollLoop().finally(() => {
             this.pollingPromise = undefined;
@@ -298,16 +403,58 @@ export class RelayFileSync {
                 throw createAbortError();
             }
             try {
-                const response = await this.client.getEvents(this.workspaceId, {
-                    cursor: this.cursor,
-                    signal: this.signal
-                });
+                // The current server implementation paginates events from oldest to
+                // newest. Empty cursor starts at index 0, and nextCursor advances
+                // forward through history. To avoid replaying the whole event log on
+                // startup while still preserving live forward progress, the first poll
+                // drains to the tip and seeds `this.cursor` without emitting. Later
+                // polls resume from that live cursor and emit only newly appended
+                // events.
+                let cursor = this.cursor;
+                let latestCursor = cursor;
+                const pending = [];
+                for (;;) {
+                    const response = await this.client.getEvents(this.workspaceId, {
+                        cursor,
+                        limit: 1000,
+                        signal: this.signal
+                    });
+                    const events = response.events ?? [];
+                    if (!this.firstPollComplete) {
+                        for (const event of events) {
+                            this.rememberPolledEvent(event.eventId);
+                        }
+                    }
+                    else {
+                        for (const event of events) {
+                            if (!event.eventId || this.polledEventIds.has(event.eventId)) {
+                                continue;
+                            }
+                            this.rememberPolledEvent(event.eventId);
+                            pending.push(event);
+                        }
+                    }
+                    const nextCursor = response.nextCursor || null;
+                    if (events.length > 0) {
+                        latestCursor = events[events.length - 1]?.eventId ?? latestCursor;
+                    }
+                    if (nextCursor) {
+                        latestCursor = nextCursor;
+                    }
+                    if (!nextCursor || nextCursor === cursor) {
+                        break;
+                    }
+                    cursor = nextCursor;
+                }
                 retryAttempt = 0;
-                for (const event of response.events) {
-                    this.emit("event", event);
+                this.cursor = latestCursor;
+                if (!this.firstPollComplete) {
+                    this.firstPollComplete = true;
                 }
-                if (response.nextCursor) {
-                    this.cursor = response.nextCursor;
+                else {
+                    for (const event of pending) {
+                        this.emit("event", event);
+                    }
                 }
                 await this.sleep(this.pollIntervalMs);
             }
@@ -322,6 +469,19 @@ export class RelayFileSync {
             }
         }
     }
+    rememberPolledEvent(eventId) {
+        if (!eventId || this.polledEventIds.has(eventId)) {
+            return;
+        }
+        this.polledEventIds.add(eventId);
+        this.polledEventOrder.push(eventId);
+        while (this.polledEventOrder.length > POLLING_DEDUPE_CACHE_LIMIT) {
+            const evicted = this.polledEventOrder.shift();
+            if (evicted) {
+                this.polledEventIds.delete(evicted);
+            }
+        }
+    }
     handleSocketMessage(event) {
         if (typeof event.data !== "string") {
             return;
@@ -444,7 +604,7 @@ export class RelayFileSync {
             return;
         }
         if (!this.reconnect.enabled) {
-            this.startPolling();
+            this.startPolling("forced-reconnect-no-retry", reason);
             return;
         }
         this.scheduleReconnect();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.6.11"
+    "@relayfile/core": "0.6.12"
   },
   "devDependencies": {
     "typescript": "^5.7.3",