@relayfile/sdk 0.1.0 → 0.1.2

package/dist/provider.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Abstract integration provider interface.
+ *
+ * Relayfile supports multiple integration providers (Nango, Composio, etc.)
+ * for syncing external service data into the Relayfile filesystem.
+ *
+ * Each provider maps its own webhook/event format into Relayfile's canonical
+ * path + semantics model.
+ */
+import type { RelayFileClient } from "./client.js";
+import type { FileQueryItem, FilesystemEvent, QueuedResponse } from "./types.js";
+/** Normalized webhook input from any provider */
+export interface WebhookInput {
+    /** Provider name (e.g., "github", "slack", "zendesk") */
+    provider: string;
+    /** Object type / model (e.g., "tickets", "commits", "messages") */
+    objectType: string;
+    /** Unique object ID within the provider */
+    objectId: string;
+    /** Event type (e.g., "created", "updated", "deleted") */
+    eventType: string;
+    /** Raw payload data */
+    payload: Record<string, unknown>;
+    /** Optional relations to other objects */
+    relations?: string[];
+    /** Provider-specific metadata (connection IDs, user IDs, etc.) */
+    metadata?: Record<string, string>;
+}
+/** Options for listing files from a specific provider */
+export interface ListProviderFilesOptions {
+    provider: string;
+    objectType?: string;
+    status?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+/** Options for watching provider events */
+export interface WatchProviderEventsOptions {
+    provider: string;
+    pollIntervalMs?: number;
+    cursor?: string;
+    signal?: AbortSignal;
+}
+export declare function computeCanonicalPath(provider: string, objectType: string, objectId: string): string;
+export declare abstract class IntegrationProvider {
+    protected readonly client: RelayFileClient;
+    abstract readonly name: string;
+    constructor(client: RelayFileClient);
+    /**
+     * Ingest a webhook event from this provider into Relayfile.
+     * Each provider implementation normalizes its event format to WebhookInput,
+     * then writes it to the canonical path.
+     */
+    abstract ingestWebhook(workspaceId: string, rawInput: unknown, signal?: AbortSignal): Promise<QueuedResponse>;
+    /**
+     * Query files from a specific provider.
+     */
+    getProviderFiles(workspaceId: string, options: ListProviderFilesOptions): Promise<FileQueryItem[]>;
+    /**
+     * Watch for file events from a specific provider.
+     */
+    watchProviderEvents(workspaceId: string, options: WatchProviderEventsOptions): AsyncGenerator<FilesystemEvent, void, unknown>;
+}

package/dist/provider.js

@@ -0,0 +1,115 @@
+/**
+ * Abstract integration provider interface.
+ *
+ * Relayfile supports multiple integration providers (Nango, Composio, etc.)
+ * for syncing external service data into the Relayfile filesystem.
+ *
+ * Each provider maps its own webhook/event format into Relayfile's canonical
+ * path + semantics model.
+ */
+// ---------------------------------------------------------------------------
+// Provider path mapping
+// ---------------------------------------------------------------------------
+const DEFAULT_PATH_PREFIXES = {
+    zendesk: "/zendesk",
+    shopify: "/shopify",
+    github: "/github",
+    stripe: "/stripe",
+    slack: "/slack",
+    linear: "/linear",
+    jira: "/jira",
+    hubspot: "/hubspot",
+    salesforce: "/salesforce",
+    gmail: "/gmail",
+    notion: "/notion",
+    asana: "/asana",
+    trello: "/trello",
+    intercom: "/intercom",
+    freshdesk: "/freshdesk",
+    discord: "/discord",
+    twilio: "/twilio",
+};
+export function computeCanonicalPath(provider, objectType, objectId) {
+    const prefix = DEFAULT_PATH_PREFIXES[provider] ?? `/${provider}`;
+    return `${prefix}/${objectType}/${objectId}.json`;
+}
+// ---------------------------------------------------------------------------
+// Abstract provider
+// ---------------------------------------------------------------------------
+export class IntegrationProvider {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Query files from a specific provider.
+     */
+    async getProviderFiles(workspaceId, options) {
+        const prefix = DEFAULT_PATH_PREFIXES[options.provider] ?? `/${options.provider}`;
+        const pathFilter = options.objectType
+            ? `${prefix}/${options.objectType}/`
+            : `${prefix}/`;
+        const properties = {
+            provider: options.provider,
+        };
+        if (options.objectType) {
+            properties["provider.object_type"] = options.objectType;
+        }
+        if (options.status) {
+            properties["provider.status"] = options.status;
+        }
+        const allItems = [];
+        let cursor;
+        for (;;) {
+            const response = await this.client.queryFiles(workspaceId, {
+                path: pathFilter,
+                properties,
+                cursor,
+                limit: options.limit,
+                signal: options.signal,
+            });
+            allItems.push(...response.items);
+            if (!response.nextCursor ||
+                (options.limit && allItems.length >= options.limit)) {
+                break;
+            }
+            cursor = response.nextCursor;
+        }
+        return options.limit ? allItems.slice(0, options.limit) : allItems;
+    }
+    /**
+     * Watch for file events from a specific provider.
+     */
+    async *watchProviderEvents(workspaceId, options) {
+        const pollIntervalMs = options.pollIntervalMs ?? 5000;
+        let cursor = options.cursor;
+        for (;;) {
+            if (options.signal?.aborted)
+                return;
+            const response = await this.client.getEvents(workspaceId, {
+                provider: options.provider,
+                cursor,
+                signal: options.signal,
+            });
+            for (const event of response.events) {
+                yield event;
+            }
+            if (response.nextCursor) {
+                cursor = response.nextCursor;
+            }
+            if (options.signal?.aborted)
+                return;
+            await new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    options.signal?.removeEventListener("abort", onAbort);
+                    resolve();
+                }, pollIntervalMs);
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+                options.signal?.addEventListener("abort", onAbort, { once: true });
+            });
+        }
+    }
+}

package/dist/sync.d.ts

@@ -0,0 +1,87 @@
+import type { RelayFileClient } from "./client.js";
+import type { FilesystemEvent } from "./types.js";
+export type RelayFileSyncState = "idle" | "connecting" | "open" | "polling" | "reconnecting" | "closed";
+export interface RelayFileSyncPong {
+    type: "pong";
+    timestamp?: string;
+}
+export interface RelayFileSyncReconnectOptions {
+    enabled?: boolean;
+    minDelayMs?: number;
+    maxDelayMs?: number;
+}
+export interface RelayFileSyncOptions {
+    client: RelayFileClient;
+    workspaceId: string;
+    baseUrl?: string;
+    token?: string;
+    cursor?: string;
+    preferPolling?: boolean;
+    pollIntervalMs?: number;
+    pingIntervalMs?: number;
+    reconnect?: boolean | RelayFileSyncReconnectOptions;
+    signal?: AbortSignal;
+    webSocketFactory?: (url: string) => RelayFileSyncSocket;
+    onEvent?: (event: FilesystemEvent) => void;
+}
+export interface RelayFileSyncSocket {
+    addEventListener(type: "open", handler: (event: Event) => void): void;
+    addEventListener(type: "message", handler: (event: MessageEvent) => void): void;
+    addEventListener(type: "error", handler: (event: Event | ErrorEvent) => void): void;
+    addEventListener(type: "close", handler: (event: CloseEvent) => void): void;
+    close(code?: number, reason?: string): void;
+    send(data: string): void;
+}
+type RelayFileSyncEventName = "event" | "error" | "state" | "open" | "close" | "pong";
+type RelayFileSyncHandlerMap = {
+    event: (event: FilesystemEvent) => void;
+    error: (error: Event | Error) => void;
+    state: (state: RelayFileSyncState) => void;
+    open: (event: Event) => void;
+    close: (event: CloseEvent) => void;
+    pong: (event: RelayFileSyncPong) => void;
+};
+export declare class RelayFileSync {
+    private readonly client;
+    private readonly workspaceId;
+    private readonly baseUrl?;
+    private readonly token?;
+    private readonly pollIntervalMs;
+    private readonly pingIntervalMs;
+    private readonly reconnect;
+    private readonly preferPolling;
+    private readonly signal?;
+    private readonly webSocketFactory;
+    private readonly handlers;
+    private state;
+    private cursor?;
+    private socket?;
+    private started;
+    private stopped;
+    private pollingPromise?;
+    private reconnectTimer?;
+    private pingTimer?;
+    private reconnectAttempts;
+    private readonly abortHandler?;
+    constructor(options: RelayFileSyncOptions);
+    static connect(options: RelayFileSyncOptions): RelayFileSync;
+    getState(): RelayFileSyncState;
+    start(): void;
+    stop(): Promise<void>;
+    on<TEventName extends RelayFileSyncEventName>(event: TEventName, handler: RelayFileSyncHandlerMap[TEventName]): () => void;
+    private shouldUsePolling;
+    private openWebSocket;
+    private startPolling;
+    private pollLoop;
+    private handleSocketMessage;
+    private startPingLoop;
+    private scheduleReconnect;
+    private computeReconnectDelayMs;
+    private sleep;
+    private isAbortError;
+    private setState;
+    private clearReconnectTimer;
+    private clearPingTimer;
+    private emit;
+}
+export {};

package/dist/sync.js

@@ -0,0 +1,394 @@
+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;
+function normalizeReconnectOptions(reconnect) {
+    if (reconnect === false) {
+        return {
+            enabled: false,
+            minDelayMs: DEFAULT_RECONNECT_MIN_DELAY_MS,
+            maxDelayMs: DEFAULT_RECONNECT_MAX_DELAY_MS
+        };
+    }
+    if (reconnect === true || reconnect === undefined) {
+        return {
+            enabled: true,
+            minDelayMs: DEFAULT_RECONNECT_MIN_DELAY_MS,
+            maxDelayMs: DEFAULT_RECONNECT_MAX_DELAY_MS
+        };
+    }
+    const minDelayMs = Math.max(1, Math.floor(reconnect.minDelayMs ?? DEFAULT_RECONNECT_MIN_DELAY_MS));
+    const maxDelayMs = Math.max(minDelayMs, Math.floor(reconnect.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS));
+    return {
+        enabled: reconnect.enabled ?? true,
+        minDelayMs,
+        maxDelayMs
+    };
+}
+function createAbortError() {
+    const err = new Error("The operation was aborted.");
+    err.name = "AbortError";
+    return err;
+}
+function buildEventId(message) {
+    return [
+        "ws",
+        message.type,
+        message.path ?? "",
+        message.revision ?? "",
+        message.timestamp ?? message.ts ?? ""
+    ].join(":");
+}
+function normalizeFilesystemEvent(message) {
+    return {
+        eventId: message.eventId ?? buildEventId(message),
+        type: message.type,
+        path: message.path ?? "",
+        revision: message.revision ?? "",
+        origin: message.origin,
+        provider: message.provider,
+        correlationId: message.correlationId,
+        timestamp: message.timestamp ?? message.ts ?? new Date().toISOString()
+    };
+}
+function normalizeError(event) {
+    return event instanceof ErrorEvent && event.error instanceof Error ? event.error : event;
+}
+export class RelayFileSync {
+    client;
+    workspaceId;
+    baseUrl;
+    token;
+    pollIntervalMs;
+    pingIntervalMs;
+    reconnect;
+    preferPolling;
+    signal;
+    webSocketFactory;
+    handlers = {
+        event: new Set(),
+        error: new Set(),
+        state: new Set(),
+        open: new Set(),
+        close: new Set(),
+        pong: new Set()
+    };
+    state = "idle";
+    cursor;
+    socket;
+    started = false;
+    stopped = false;
+    pollingPromise;
+    reconnectTimer;
+    pingTimer;
+    reconnectAttempts = 0;
+    abortHandler;
+    constructor(options) {
+        this.client = options.client;
+        this.workspaceId = options.workspaceId;
+        this.baseUrl = options.baseUrl?.replace(/\/+$/, "");
+        this.token = options.token;
+        this.cursor = options.cursor;
+        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));
+        this.reconnect = normalizeReconnectOptions(options.reconnect);
+        this.preferPolling = options.preferPolling ?? false;
+        this.signal = options.signal;
+        this.webSocketFactory =
+            options.webSocketFactory ??
+                ((url) => {
+                    if (typeof WebSocket !== "function") {
+                        throw new Error("WebSocket is not available in this environment.");
+                    }
+                    return new WebSocket(url);
+                });
+        if (options.onEvent) {
+            this.handlers.event.add(options.onEvent);
+        }
+        if (this.signal) {
+            this.abortHandler = () => {
+                this.stop();
+            };
+            if (this.signal.aborted) {
+                this.stopped = true;
+                this.state = "closed";
+            }
+            else {
+                this.signal.addEventListener("abort", this.abortHandler, { once: true });
+            }
+        }
+    }
+    static connect(options) {
+        const sync = new RelayFileSync(options);
+        sync.start();
+        return sync;
+    }
+    getState() {
+        return this.state;
+    }
+    start() {
+        if (this.started || this.stopped) {
+            return;
+        }
+        this.started = true;
+        if (this.shouldUsePolling()) {
+            this.startPolling();
+            return;
+        }
+        this.openWebSocket(false);
+    }
+    async stop() {
+        if (this.stopped) {
+            return;
+        }
+        this.stopped = true;
+        this.clearReconnectTimer();
+        this.clearPingTimer();
+        const socket = this.socket;
+        this.socket = undefined;
+        if (socket) {
+            socket.close(1000, "client stopped");
+        }
+        if (this.abortHandler && this.signal) {
+            this.signal.removeEventListener("abort", this.abortHandler);
+        }
+        if (this.pollingPromise) {
+            await this.pollingPromise.catch(() => undefined);
+        }
+        this.setState("closed");
+    }
+    on(event, handler) {
+        this.handlers[event].add(handler);
+        return () => {
+            this.handlers[event].delete(handler);
+        };
+    }
+    shouldUsePolling() {
+        return this.preferPolling || !this.baseUrl || !this.token;
+    }
+    openWebSocket(isReconnect) {
+        if (this.stopped) {
+            return;
+        }
+        const url = new URL(`${this.baseUrl}/v1/workspaces/${encodeURIComponent(this.workspaceId)}/fs/ws`);
+        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);
+        }
+        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();
+            return;
+        }
+        this.socket = socket;
+        socket.addEventListener("open", (event) => {
+            if (this.socket !== socket || this.stopped) {
+                return;
+            }
+            this.reconnectAttempts = 0;
+            this.setState("open");
+            this.startPingLoop(socket);
+            this.emit("open", event);
+        });
+        socket.addEventListener("message", (event) => {
+            if (this.socket !== socket || this.stopped) {
+                return;
+            }
+            this.handleSocketMessage(event);
+        });
+        socket.addEventListener("error", (event) => {
+            if (this.socket !== socket || this.stopped) {
+                return;
+            }
+            this.emit("error", normalizeError(event));
+        });
+        socket.addEventListener("close", (event) => {
+            if (this.socket === socket) {
+                this.socket = undefined;
+            }
+            this.clearPingTimer();
+            this.emit("close", event);
+            if (this.stopped) {
+                this.setState("closed");
+                return;
+            }
+            if (!this.reconnect.enabled) {
+                this.startPolling();
+                return;
+            }
+            this.scheduleReconnect();
+        });
+    }
+    startPolling() {
+        if (this.pollingPromise || this.stopped) {
+            return;
+        }
+        this.setState("polling");
+        this.pollingPromise = this.pollLoop().finally(() => {
+            this.pollingPromise = undefined;
+            if (!this.stopped && !this.shouldUsePolling()) {
+                this.scheduleReconnect();
+            }
+        });
+    }
+    async pollLoop() {
+        let retryAttempt = 0;
+        while (!this.stopped) {
+            if (this.signal?.aborted) {
+                throw createAbortError();
+            }
+            try {
+                const response = await this.client.getEvents(this.workspaceId, {
+                    cursor: this.cursor,
+                    signal: this.signal
+                });
+                retryAttempt = 0;
+                for (const event of response.events) {
+                    this.emit("event", event);
+                }
+                if (response.nextCursor) {
+                    this.cursor = response.nextCursor;
+                }
+                await this.sleep(this.pollIntervalMs);
+            }
+            catch (error) {
+                if (this.isAbortError(error)) {
+                    return;
+                }
+                retryAttempt += 1;
+                this.emit("error", error instanceof Error ? error : new Error("Polling failed."));
+                const delayMs = this.computeReconnectDelayMs(retryAttempt);
+                await this.sleep(delayMs);
+            }
+        }
+    }
+    handleSocketMessage(event) {
+        if (typeof event.data !== "string") {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(event.data);
+        }
+        catch (error) {
+            this.emit("error", error instanceof Error ? error : new Error("Failed to parse WebSocket payload."));
+            return;
+        }
+        if (typeof parsed !== "object" || parsed === null || typeof parsed.type !== "string") {
+            this.emit("error", new Error("Invalid WebSocket payload: missing required 'type' field."));
+            return;
+        }
+        if (parsed.path !== undefined && typeof parsed.path !== "string") {
+            this.emit("error", new Error("Invalid WebSocket payload: 'path' must be a string."));
+            return;
+        }
+        if (parsed.revision !== undefined && typeof parsed.revision !== "string") {
+            this.emit("error", new Error("Invalid WebSocket payload: 'revision' must be a string."));
+            return;
+        }
+        if (parsed.timestamp !== undefined && typeof parsed.timestamp !== "string") {
+            this.emit("error", new Error("Invalid WebSocket payload: 'timestamp' must be a string."));
+            return;
+        }
+        if (parsed.ts !== undefined && typeof parsed.ts !== "string") {
+            this.emit("error", new Error("Invalid WebSocket payload: 'ts' must be a string."));
+            return;
+        }
+        if (parsed.type === "pong") {
+            this.emit("pong", {
+                type: "pong",
+                timestamp: parsed.timestamp ?? parsed.ts
+            });
+            return;
+        }
+        this.emit("event", normalizeFilesystemEvent(parsed));
+    }
+    startPingLoop(socket) {
+        this.clearPingTimer();
+        this.pingTimer = setInterval(() => {
+            if (this.socket !== socket || this.stopped) {
+                this.clearPingTimer();
+                return;
+            }
+            try {
+                socket.send(JSON.stringify({ type: "ping" }));
+            }
+            catch (error) {
+                this.emit("error", error instanceof Error ? error : new Error("Failed to send WebSocket ping."));
+            }
+        }, this.pingIntervalMs);
+    }
+    scheduleReconnect() {
+        if (this.stopped || this.reconnectTimer) {
+            return;
+        }
+        this.reconnectAttempts += 1;
+        this.setState("reconnecting");
+        const delayMs = this.computeReconnectDelayMs(this.reconnectAttempts);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (this.stopped) {
+                return;
+            }
+            if (this.pollingPromise) {
+                return;
+            }
+            this.openWebSocket(true);
+        }, delayMs);
+    }
+    computeReconnectDelayMs(attempt) {
+        const uncapped = this.reconnect.minDelayMs * Math.pow(2, Math.max(0, attempt - 1));
+        return Math.min(this.reconnect.maxDelayMs, uncapped);
+    }
+    async sleep(delayMs) {
+        if (delayMs <= 0) {
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, delayMs);
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(createAbortError());
+            };
+            this.signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    isAbortError(error) {
+        return this.signal?.aborted || (error instanceof Error && error.name === "AbortError");
+    }
+    setState(state) {
+        if (this.state === state) {
+            return;
+        }
+        this.state = state;
+        this.emit("state", state);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
+    clearPingTimer() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = undefined;
+        }
+    }
+    emit(event, payload) {
+        const handlers = this.handlers[event];
+        for (const handler of handlers) {
+            handler(payload);
+        }
+    }
+}