@relayfile/sdk 0.6.3 → 0.6.4

package/dist/index.d.ts

@@ -4,12 +4,14 @@ export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type Rela
 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 { 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";
 export type { WebhookInput, ListProviderFilesOptions, WatchProviderEventsOptions } from "./provider.js";
 export type { ConnectionProvider, NormalizedWebhook, ProxyHeaders, ProxyMethod, ProxyQuery, ProxyRequest, ProxyResponse, } from "./connection.js";
 export type { AckResponse, AckWritebackInput, AckWritebackResponse, AdminIngressAlert, AdminIngressAlertProfile, AdminIngressEffectiveAlertProfile, AdminIngressAlertSeverity, AdminIngressAlertThresholds, AdminIngressAlertTotals, AdminIngressAlertType, AdminIngressStatusResponse, AdminSyncAlert, AdminSyncAlertSeverity, AdminSyncAlertThresholds, AdminSyncAlertTotals, AdminSyncAlertType, AdminSyncStatusResponse, BackendStatusResponse, BulkWriteFile, BulkWriteInput, BulkWriteResponse, CommitForkInput, CommitForkResponse, ConflictErrorResponse, CreateForkInput, ContentIdentity, DeleteFileInput, DeadLetterFeedResponse, DeadLetterItem, DiscardForkInput, ErrorResponse, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, FilesystemEventType, EventOrigin, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, IngestWebhookInput, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, RelayFileJwtClaims, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackState, WritebackItem, WriteFileInput, WriteQueuedResponse } from "./types.js";
 export type { ForkHandle, ForkOptions } from "@relayfile/core";
+export type { WriteEvent, WriteEventActor, WriteEventOperation, WriteEventSource } from "@relayfile/core";
 export { WritebackConsumer } from "./writeback-consumer.js";
 export type { WritebackHandler, WritebackConsumerOptions } from "./writeback-consumer.js";
 export * from "./integration-adapter.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.
 export { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 export { WORKSPACE_INTEGRATION_PROVIDERS } from "./setup-types.js";
 export { RelayFileSync } from "./sync.js";
+export { onWrite, pathMatches } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 // Integration providers
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";

package/dist/onWrite.d.ts

@@ -0,0 +1,24 @@
+import type { WriteEvent, WriteEventOperation } from "@relayfile/core";
+import { RelayFileClient } from "./client.js";
+import { type RelayFileSyncSocket } from "./sync.js";
+export type OnWriteHandler = (event: WriteEvent) => void | Promise<void>;
+export interface OnWriteHandlerError {
+    pattern: string;
+    path: string;
+    error: unknown;
+    retryable: false;
+}
+export type OnWriteClient = RelayFileClient & {
+    recordHandlerError?(error: OnWriteHandlerError): void | Promise<void>;
+};
+export interface OnWriteOptions {
+    client?: OnWriteClient;
+    workspaceId?: string;
+    operations?: WriteEventOperation[];
+    signal?: AbortSignal;
+    baseUrl?: string;
+    token?: string;
+    webSocketFactory?: (url: string) => RelayFileSyncSocket;
+}
+export declare function pathMatches(pattern: string, path: string): boolean;
+export declare function onWrite(pattern: string, handler: OnWriteHandler, options?: OnWriteOptions): () => void;

package/dist/onWrite.js

@@ -0,0 +1,268 @@
+import { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL } from "./client.js";
+import { RelayFileSync } from "./sync.js";
+const DEFAULT_OPERATIONS = ["create", "update"];
+const DEFAULT_RECONNECT_MIN_DELAY_MS = 1000;
+const DEFAULT_RECONNECT_MAX_DELAY_MS = 30000;
+const dispatchers = new WeakMap();
+let nextRegistrationId = 1;
+let defaultClient;
+export function pathMatches(pattern, path) {
+    const patternSegments = normalizePattern(pattern);
+    const pathSegments = normalizePath(path);
+    return matchSegments(patternSegments, pathSegments);
+}
+export function onWrite(pattern, handler, options = {}) {
+    const normalizedPattern = `/${normalizePattern(pattern).join("/")}`;
+    if (typeof handler !== "function") {
+        throw new Error("onWrite handler must be a function.");
+    }
+    const client = options.client ?? getDefaultClient();
+    const workspaceId = options.workspaceId ?? readEnv("RELAYFILE_WORKSPACE_ID");
+    if (!workspaceId) {
+        throw new Error("onWrite requires options.workspaceId or RELAYFILE_WORKSPACE_ID.");
+    }
+    const operations = new Set(options.operations ?? DEFAULT_OPERATIONS);
+    for (const operation of operations) {
+        if (operation !== "create" && operation !== "update" && operation !== "delete") {
+            throw new Error(`Invalid onWrite operation: ${operation}`);
+        }
+    }
+    // The dispatcher cache is keyed by client; a single shared WebSocket is
+    // bound to one workspace. v1 scopes a client to a single workspace per the
+    // design doc (Out-of-scope: "Cross-workspace subscriptions"). Reject
+    // mismatched workspaceId rather than silently attaching to the wrong feed.
+    let dispatcher = dispatchers.get(client);
+    if (dispatcher && dispatcher.workspaceId !== workspaceId) {
+        throw new Error(`onWrite registrations on the same client must use the same workspaceId. Existing="${dispatcher.workspaceId}", new="${workspaceId}". Construct a separate RelayFileClient per workspace.`);
+    }
+    if (!dispatcher) {
+        dispatcher = new OnWriteDispatcher(client, workspaceId);
+        dispatchers.set(client, dispatcher);
+    }
+    const registration = {
+        id: nextRegistrationId++,
+        pattern: normalizedPattern,
+        operations,
+        handler
+    };
+    dispatcher.register(registration, {
+        workspaceId,
+        signal: options.signal,
+        baseUrl: options.baseUrl,
+        token: options.token,
+        webSocketFactory: options.webSocketFactory
+    });
+    return () => {
+        dispatcher?.unregister(registration.id);
+    };
+}
+class OnWriteDispatcher {
+    client;
+    // Captured at construction. RelayFileSync normalizes the FilesystemEvent
+    // shape and does not surface workspaceId on emitted events, so we stamp the
+    // subscribed workspaceId onto every WriteEvent we hand to user handlers.
+    // It also gates registrations: see the cross-workspace check in onWrite().
+    workspaceId;
+    registrations = [];
+    patternChains = new Map();
+    sync;
+    constructor(client, workspaceId) {
+        this.client = client;
+        this.workspaceId = workspaceId;
+    }
+    register(registration, options) {
+        this.registrations.push(registration);
+        if (options.signal) {
+            if (options.signal.aborted) {
+                this.unregister(registration.id);
+                return;
+            }
+            options.signal.addEventListener("abort", () => this.unregister(registration.id), { once: true });
+        }
+        this.ensureSync(options);
+    }
+    unregister(id) {
+        const index = this.registrations.findIndex((registration) => registration.id === id);
+        if (index >= 0) {
+            this.registrations.splice(index, 1);
+        }
+        if (this.registrations.length === 0 && this.sync) {
+            void this.sync.stop();
+            this.sync = undefined;
+        }
+    }
+    ensureSync(options) {
+        if (this.sync) {
+            return;
+        }
+        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"),
+            reconnect: {
+                minDelayMs: DEFAULT_RECONNECT_MIN_DELAY_MS,
+                maxDelayMs: DEFAULT_RECONNECT_MAX_DELAY_MS
+            },
+            webSocketFactory: options.webSocketFactory,
+            onEvent: (event) => {
+                void this.dispatch(event);
+            }
+        });
+    }
+    async dispatch(event) {
+        const writeEvent = toWriteEvent(event, this.workspaceId);
+        if (!writeEvent) {
+            return;
+        }
+        for (const registration of [...this.registrations]) {
+            if (!registration.operations.has(writeEvent.operation) || !pathMatches(registration.pattern, writeEvent.path)) {
+                continue;
+            }
+            const previous = this.patternChains.get(registration.pattern) ?? Promise.resolve();
+            const next = previous
+                .catch(() => undefined)
+                .then(() => this.runHandler(registration, writeEvent));
+            this.patternChains.set(registration.pattern, next);
+            void next.finally(() => {
+                if (this.patternChains.get(registration.pattern) === next) {
+                    this.patternChains.delete(registration.pattern);
+                }
+            });
+        }
+    }
+    async runHandler(registration, event) {
+        try {
+            await registration.handler(event);
+        }
+        catch (error) {
+            await this.recordHandlerError({
+                pattern: registration.pattern,
+                path: event.path,
+                error,
+                retryable: false
+            });
+        }
+    }
+    // The "handler errors do not propagate" guarantee covers the recorder too:
+    // if the customer's recordHandlerError implementation throws or rejects, fall
+    // back to console.error rather than letting the rejection bubble up the
+    // dispatch chain (which would skip subsequent handlers for the same pattern).
+    async recordHandlerError(error) {
+        if (typeof this.client.recordHandlerError === "function") {
+            try {
+                await this.client.recordHandlerError(error);
+                return;
+            }
+            catch (reportingError) {
+                if (typeof console !== "undefined" && typeof console.error === "function") {
+                    console.error("Relayfile onWrite handler-error reporter failed", reportingError);
+                }
+            }
+        }
+        if (typeof console !== "undefined" && typeof console.error === "function") {
+            console.error("Relayfile onWrite handler error", error);
+        }
+    }
+}
+function normalizePattern(pattern) {
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new Error("onWrite pattern must be a non-empty string.");
+    }
+    if (!pattern.startsWith("/")) {
+        throw new Error("onWrite pattern must start with '/'.");
+    }
+    if (pattern.includes("//")) {
+        throw new Error("onWrite pattern cannot contain empty path segments.");
+    }
+    const segments = normalizePath(pattern);
+    const recursiveIndex = segments.indexOf("**");
+    if (recursiveIndex >= 0 && recursiveIndex !== segments.length - 1) {
+        throw new Error("onWrite pattern only supports '**' as the trailing segment.");
+    }
+    return segments;
+}
+function normalizePath(path) {
+    if (!path.startsWith("/")) {
+        return normalizePath(`/${path}`);
+    }
+    const trimmed = path.replace(/\/+$/, "");
+    if (trimmed === "") {
+        return [];
+    }
+    return trimmed.split("/").filter(Boolean);
+}
+// Trailing `**` matches **zero or more** trailing segments — same as gitignore
+// and standard glob conventions, and what the design doc specifies ("any
+// number of segments"). `/linear/issues/**` therefore matches both
+// `/linear/issues` (the collection root) and `/linear/issues/PROJ-1/comments`.
+// `*` matches exactly one segment; `**` is only valid as the last segment.
+function matchSegments(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]);
+}
+function toWriteEvent(event, workspaceId) {
+    const operation = operationFromEventType(event.type);
+    if (!operation) {
+        return null;
+    }
+    // RelayFileSync currently surfaces only:
+    //   eventId, type, path, revision, origin, provider, correlationId, timestamp
+    // Fields the wider WriteEvent contract advertises but the wire format does
+    // not yet preserve — previousRevision, value, actor — are intentionally
+    // omitted/null here. Wiring them through the wire format and
+    // normalizeFilesystemEvent is a follow-up; v1 callers should treat
+    // previousRevision/value/actor as not-yet-populated.
+    return {
+        workspaceId: workspaceId ?? "",
+        path: event.path,
+        operation,
+        revision: event.revision,
+        previousRevision: null,
+        timestamp: event.timestamp,
+        source: sourceFromOrigin(event.origin)
+    };
+}
+function operationFromEventType(type) {
+    if (type === "file.created") {
+        return "create";
+    }
+    if (type === "file.updated") {
+        return "update";
+    }
+    if (type === "file.deleted") {
+        return "delete";
+    }
+    return null;
+}
+function sourceFromOrigin(origin) {
+    if (origin === "agent_write") {
+        return "agent";
+    }
+    if (origin === "provider_sync") {
+        return "sync";
+    }
+    return "api";
+}
+function getDefaultClient() {
+    if (!defaultClient) {
+        const token = readEnv("RELAYFILE_TOKEN");
+        if (!token) {
+            throw new Error("onWrite requires options.client or RELAYFILE_TOKEN.");
+        }
+        defaultClient = new RelayFileClient({
+            baseUrl: readEnv("RELAYFILE_BASE_URL") ?? DEFAULT_RELAYFILE_BASE_URL,
+            token
+        });
+    }
+    return defaultClient;
+}
+function readEnv(name) {
+    return globalThis.process?.env?.[name];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "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.3"
+    "@relayfile/core": "0.6.4"
   },
   "devDependencies": {
     "typescript": "^5.7.3",