@relayfile/sdk 0.8.8 → 0.8.10

package/dist/client.d.ts

@@ -55,6 +55,9 @@ export interface WebSocketConnection {
 }
 export interface ConnectWebSocketOptions {
     token?: string;
+    from?: "now" | "legacy";
+    cursor?: string;
+    paths?: string[];
     onEvent?: (event: FilesystemEvent) => void;
 }
 interface ProactiveRequestContext {

package/dist/client.js

@@ -318,6 +318,14 @@ class RelayFileChangeSubscription {
         }
         await drain;
     }
+    serverPathFilters() {
+        const filters = new Set();
+        const patterns = this.pathScopes ?? this.globPatterns;
+        for (const pattern of patterns) {
+            filters.add(`/${pattern.join("/")}`);
+        }
+        return Array.from(filters);
+    }
     matches(path) {
         const pathSegments = normalizeChangePath(path);
         const matchesGlob = this.globPatterns.some((pattern) => matchChangeSegments(pattern, pathSegments));
@@ -353,18 +361,21 @@ class RelayFileChangeStreamManager {
     workspaceId;
     token;
     baseUrl;
+    startOptions;
     subscriptions = new Set();
     openHandleCount = 0;
     sync;
+    activePathFilterKey;
     readyResolved = false;
     readyInternal;
     resolveReady;
     rejectReady;
-    constructor(client, workspaceId, token, baseUrl) {
+    constructor(client, workspaceId, token, baseUrl, startOptions) {
         this.client = client;
         this.workspaceId = workspaceId;
         this.token = token;
         this.baseUrl = baseUrl;
+        this.startOptions = startOptions;
         this.readyInternal = new Promise((resolve, reject) => {
             this.resolveReady = resolve;
             this.rejectReady = reject;
@@ -376,22 +387,26 @@ class RelayFileChangeStreamManager {
     addSubscription(globs, onChange, options) {
         const subscription = new RelayFileChangeSubscription(this, globs, onChange, options);
         this.subscriptions.add(subscription);
+        this.restartIfPathScopeChanged();
         this.ensureStarted();
         return {
             unsubscribe: async () => {
                 this.subscriptions.delete(subscription);
                 await subscription.close();
+                this.restartIfPathScopeChanged();
                 await this.maybeStop();
             }
         };
     }
     open() {
         this.openHandleCount += 1;
+        this.restartIfPathScopeChanged();
         this.ensureStarted();
         return {
             ready: this.ready,
             unsubscribe: async () => {
                 this.openHandleCount = Math.max(0, this.openHandleCount - 1);
+                this.restartIfPathScopeChanged();
                 await this.maybeStop();
             }
         };
@@ -429,11 +444,16 @@ class RelayFileChangeStreamManager {
         if (this.sync) {
             return;
         }
+        const paths = this.serverPathFilters();
+        this.activePathFilterKey = paths.join("\n");
         const sync = new RelayFileSync({
             client: this.client,
             workspaceId: this.workspaceId,
             baseUrl: this.baseUrl,
             token: this.token,
+            from: this.startOptions.from,
+            cursor: this.startOptions.cursor,
+            paths,
             onPollingFallback: () => {
                 this.resolveReadyOnce();
             }
@@ -462,6 +482,34 @@ class RelayFileChangeStreamManager {
             this.resolveReadyOnce();
         }
     }
+    restartIfPathScopeChanged() {
+        if (!this.sync) {
+            return;
+        }
+        const nextKey = this.serverPathFilters().join("\n");
+        const currentKey = this.activePathFilterKey;
+        if (nextKey === currentKey) {
+            return;
+        }
+        const sync = this.sync;
+        this.sync = undefined;
+        void sync.stop();
+        if (this.openHandleCount > 0 || this.subscriptions.size > 0) {
+            this.ensureStarted();
+        }
+    }
+    serverPathFilters() {
+        if (this.openHandleCount > 0) {
+            return [];
+        }
+        const filters = new Set();
+        for (const subscription of this.subscriptions) {
+            for (const path of subscription.serverPathFilters()) {
+                filters.add(path);
+            }
+        }
+        return Array.from(filters).sort();
+    }
     resolveReadyOnce() {
         if (this.readyResolved) {
             return;
@@ -476,6 +524,7 @@ class RelayFileChangeStreamManager {
         if (this.sync) {
             const sync = this.sync;
             this.sync = undefined;
+            this.activePathFilterKey = undefined;
             await sync.stop();
         }
         const managers = changeStreamManagers.get(this.client);
@@ -489,18 +538,21 @@ class RelayFileChangeStreamManager {
         }
     }
 }
-function getStreamManager(client, workspaceId, token, baseUrl) {
+function getStreamManager(client, workspaceId, token, baseUrl, startOptions = {}) {
     let managers = changeStreamManagers.get(client);
     if (!managers) {
         managers = new Map();
         changeStreamManagers.set(client, managers);
     }
-    const key = `${workspaceId}:${token ?? CLIENT_TOKEN_STREAM_KEY}`;
+    const key = `${workspaceId}:${token ?? CLIENT_TOKEN_STREAM_KEY}:${startOptions.from ?? "now"}:${startOptions.cursor ?? ""}`;
     const existing = managers.get(key);
     if (existing) {
         return existing;
     }
-    const manager = new RelayFileChangeStreamManager(client, workspaceId, token, baseUrl);
+    const manager = new RelayFileChangeStreamManager(client, workspaceId, token, baseUrl, {
+        from: startOptions.from,
+        cursor: startOptions.cursor
+    });
     managers.set(key, manager);
     return manager;
 }
@@ -1125,7 +1177,7 @@ export class RelayFileClient {
     subscribe(globs, onChange, options) {
         const setup = this.resolveWorkspaceId(options?.aclToken)
             .then((workspaceId) => {
-            const manager = getStreamManager(this, workspaceId, options?.aclToken, this.baseUrl);
+            const manager = getStreamManager(this, workspaceId, options?.aclToken, this.baseUrl, options);
             return manager.addSubscription(globs, onChange, options);
         });
         return {
@@ -1136,7 +1188,7 @@ export class RelayFileClient {
         };
     }
     open(options) {
-        const manager = getStreamManager(this, options.workspaceId, options.aclToken, this.baseUrl);
+        const manager = getStreamManager(this, options.workspaceId, options.aclToken, this.baseUrl, options);
         const connection = manager.open();
         const replay = this.primeReplayCache(options).catch((error) => {
             if (typeof console !== "undefined" && typeof console.error === "function") {
@@ -1252,6 +1304,15 @@ export class RelayFileClient {
         const url = new URL(`${this.baseUrl}/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/ws`);
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
         url.searchParams.set("token", token);
+        if (options.cursor) {
+            url.searchParams.set("cursor", options.cursor);
+        }
+        else if ((options.from ?? "now") === "now") {
+            url.searchParams.set("from", "now");
+        }
+        for (const path of options.paths ?? []) {
+            url.searchParams.append("path", path);
+        }
         const socket = new WebSocket(url.toString());
         return new RelayFileWebSocketConnection(socket, options.onEvent);
     }

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, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 export { type EnsureMountedWorkspaceInput, WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type MountLauncher, type MountLauncherEvent, type MountLauncherInstance, type MountLauncherStart, type MountMode, type MountSessionRequest, type MountSessionResponse, type MountSessionResult, type MountedWorkspaceHandle, type MountedWorkspaceStatus, type MountWorkspaceInput, type ReadMountedWorkspaceStatusInput, 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, type RelayFileSyncTokenProvider } from "./sync.js";
+export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncStart, 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/sync.d.ts

@@ -9,6 +9,7 @@ import type { FilesystemEvent } from "./types.js";
  */
 export type RelayFileSyncTokenProvider = string | (() => string | undefined | Promise<string | undefined>);
 export type RelayFileSyncState = "idle" | "connecting" | "open" | "polling" | "reconnecting" | "closed";
+export type RelayFileSyncStart = "now" | "legacy";
 export interface RelayFileSyncPong {
     type: "pong";
     timestamp?: string;
@@ -32,7 +33,9 @@ export interface RelayFileSyncOptions {
      * normally NOT pass this and let it inherit from the client.
      */
     token?: RelayFileSyncTokenProvider;
+    from?: RelayFileSyncStart;
     cursor?: string;
+    paths?: string[];
     preferPolling?: boolean;
     pollIntervalMs?: number;
     pingIntervalMs?: number;
@@ -87,6 +90,8 @@ export declare class RelayFileSync {
     private readonly handlers;
     private state;
     private cursor?;
+    private readonly from;
+    private readonly paths;
     private readonly polledEventIds;
     private readonly polledEventOrder;
     private firstPollComplete;
@@ -116,6 +121,7 @@ export declare class RelayFileSync {
     private pollLoop;
     private rememberPolledEvent;
     private handleSocketMessage;
+    private emitFilesystemEvent;
     private startPingLoop;
     private forceReconnect;
     private scheduleReconnect;

package/dist/sync.js

@@ -1,3 +1,45 @@
+function normalizeWebSocketPathFilters(paths) {
+    const seen = new Set();
+    const normalized = [];
+    for (const value of paths ?? []) {
+        const path = typeof value === "string" ? value.trim() : "";
+        if (!path) {
+            continue;
+        }
+        const absolute = path.startsWith("/") ? path : `/${path}`;
+        if (seen.has(absolute)) {
+            continue;
+        }
+        seen.add(absolute);
+        normalized.push(absolute);
+    }
+    return normalized;
+}
+function pathMatchesAnyFilter(filters, path) {
+    if (filters.length === 0) {
+        return true;
+    }
+    const pathSegments = normalizePathSegments(path);
+    return filters.some((filter) => matchPathSegments(normalizePathSegments(filter), pathSegments));
+}
+function normalizePathSegments(path) {
+    const absolute = path.startsWith("/") ? path : `/${path}`;
+    const trimmed = absolute.replace(/\/+$/, "");
+    if (!trimmed) {
+        return [];
+    }
+    return trimmed.split("/").filter(Boolean);
+}
+function matchPathSegments(pattern, path) {
+    if (pattern.length > 0 && pattern[pattern.length - 1] === "**") {
+        const prefix = pattern.slice(0, -1);
+        return path.length >= prefix.length && prefix.every((segment, index) => segment === "*" || segment === path[index]);
+    }
+    if (pattern.length !== path.length) {
+        return false;
+    }
+    return pattern.every((segment, index) => segment === "*" || segment === path[index]);
+}
 const DEFAULT_POLL_INTERVAL_MS = 5000;
 const DEFAULT_PING_INTERVAL_MS = 30000;
 const DEFAULT_RECONNECT_MIN_DELAY_MS = 250;
@@ -131,6 +173,8 @@ export class RelayFileSync {
     };
     state = "idle";
     cursor;
+    from;
+    paths;
     polledEventIds = new Set();
     polledEventOrder = [];
     firstPollComplete = false;
@@ -176,7 +220,9 @@ export class RelayFileSync {
             const literal = options.token;
             this.tokenProvider = () => literal;
         }
+        this.from = options.from ?? "now";
         this.cursor = options.cursor;
+        this.paths = normalizeWebSocketPathFilters(options.paths);
         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));
@@ -327,6 +373,15 @@ export class RelayFileSync {
         if (token) {
             url.searchParams.set("token", token);
         }
+        if (this.cursor) {
+            url.searchParams.set("cursor", this.cursor);
+        }
+        else if (this.from === "now") {
+            url.searchParams.set("from", "now");
+        }
+        for (const path of this.paths) {
+            url.searchParams.append("path", path);
+        }
         let socket;
         try {
             socket = this.webSocketFactory(url.toString());
@@ -524,7 +579,7 @@ export class RelayFileSync {
                 }
                 else {
                     for (const event of pending) {
-                        this.emit("event", event);
+                        this.emitFilesystemEvent(event);
                     }
                 }
                 await this.sleep(this.pollIntervalMs);
@@ -594,8 +649,17 @@ export class RelayFileSync {
             return;
         }
         const normalized = normalizeFilesystemEvent(parsed);
+        if (parsed.eventId) {
+            this.cursor = parsed.eventId;
+        }
         debugLog("event", { type: normalized.type, path: normalized.path, revision: normalized.revision });
-        this.emit("event", normalized);
+        this.emitFilesystemEvent(normalized);
+    }
+    emitFilesystemEvent(event) {
+        if (!pathMatchesAnyFilter(this.paths, event.path)) {
+            return;
+        }
+        this.emit("event", event);
     }
     startPingLoop(socket) {
         this.clearPingTimer();

package/dist/types.d.ts

@@ -257,6 +257,8 @@ export interface SubscribeOptions {
     coalesce?: "none" | "fire-once";
     coalesceMs?: number;
     pathScope?: string[];
+    from?: "now" | "legacy";
+    cursor?: string;
     aclToken?: string;
     drainMs?: number;
 }
@@ -273,6 +275,8 @@ export type ReplayOptions = {
 export type ChangeStreamConnectionOptions = ReplayOptions & {
     workspaceId: string;
     aclToken?: string;
+    from?: "now" | "legacy";
+    cursor?: string;
 };
 export interface ChangeStreamConnection extends Subscription {
     readonly ready: Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,7 +55,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.8.8",
+    "@relayfile/core": "0.8.10",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },