@relayfile/sdk 0.1.5 → 0.1.6

package/dist/index.d.ts

@@ -5,3 +5,5 @@ 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, ConflictErrorResponse, DeleteFileInput, DeadLetterFeedResponse, DeadLetterItem, 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, RelayFileJwtClaims, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackState, WritebackItem, WriteFileInput, WriteQueuedResponse } from "./types.js";
+export { WritebackConsumer } from "./writeback-consumer.js";
+export type { WritebackHandler, WritebackConsumerOptions } from "./writeback-consumer.js";

package/dist/index.js

@@ -3,3 +3,4 @@ export { RelayFileSync } from "./sync.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 // Integration providers
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";
+export { WritebackConsumer } from "./writeback-consumer.js";

package/dist/writeback-consumer.d.ts

@@ -0,0 +1,31 @@
+import type { RelayFileClient } from "./client.js";
+import type { ConnectionProvider } from "./connection.js";
+import type { WritebackItem } from "./types.js";
+export interface WritebackHandler {
+    canHandle(path: string): boolean;
+    execute(item: WritebackItem, provider: ConnectionProvider): Promise<void>;
+}
+export interface WritebackConsumerOptions {
+    client: RelayFileClient;
+    workspaceId: string;
+    handlers: WritebackHandler[];
+    provider: ConnectionProvider;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+}
+export declare class WritebackConsumer {
+    private readonly client;
+    private readonly workspaceId;
+    private readonly handlers;
+    private readonly provider;
+    private readonly pollIntervalMs;
+    private readonly signal?;
+    private loopPromise?;
+    private stopped;
+    constructor(opts: WritebackConsumerOptions);
+    start(): Promise<void>;
+    stop(): void;
+    pollOnce(signal?: AbortSignal): Promise<void>;
+    private runLoop;
+    private ackFailure;
+}

package/dist/writeback-consumer.js

@@ -0,0 +1,139 @@
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+export class WritebackConsumer {
+    client;
+    workspaceId;
+    handlers;
+    provider;
+    pollIntervalMs;
+    signal;
+    loopPromise;
+    stopped = false;
+    constructor(opts) {
+        this.client = opts.client;
+        this.workspaceId = opts.workspaceId;
+        this.handlers = opts.handlers;
+        this.provider = opts.provider;
+        this.pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.signal = opts.signal;
+        if (this.pollIntervalMs < 0) {
+            throw new RangeError("pollIntervalMs must be greater than or equal to 0");
+        }
+    }
+    async start() {
+        if (this.loopPromise) {
+            if (this.stopped) {
+                // Previous run was stopped — reset and start fresh
+                this.stopped = false;
+                this.loopPromise = undefined;
+            }
+            else {
+                return this.loopPromise;
+            }
+        }
+        this.loopPromise = this.runLoop();
+        return this.loopPromise;
+    }
+    stop() {
+        this.stopped = true;
+    }
+    async pollOnce(signal = this.signal) {
+        const items = await this.client.listPendingWritebacks(this.workspaceId, undefined, signal);
+        for (const item of items) {
+            if (signal?.aborted || this.stopped) {
+                return;
+            }
+            const handler = this.handlers.find((candidate) => candidate.canHandle(item.path));
+            if (!handler) {
+                await this.ackFailure(item, new Error(`No writeback handler found for path: ${item.path}`), signal);
+                continue;
+            }
+            let executed = false;
+            try {
+                await handler.execute(item, this.provider);
+                executed = true;
+            }
+            catch (error) {
+                if (isAbortError(error) || signal?.aborted) {
+                    throw error;
+                }
+                await this.ackFailure(item, error, signal);
+            }
+            if (executed) {
+                try {
+                    await this.client.ackWriteback({
+                        workspaceId: this.workspaceId,
+                        itemId: item.id,
+                        success: true,
+                        correlationId: item.correlationId,
+                        signal
+                    });
+                }
+                catch (ackError) {
+                    if (isAbortError(ackError) || signal?.aborted) {
+                        throw ackError;
+                    }
+                    // Handler succeeded — do NOT send failure ack (would cause duplicate writes on retry).
+                    // Log and move on; server will eventually time out and retry the ack.
+                }
+            }
+        }
+    }
+    async runLoop() {
+        while (!this.stopped && !this.signal?.aborted) {
+            try {
+                await this.pollOnce(this.signal);
+                if (this.stopped || this.signal?.aborted) {
+                    return;
+                }
+                await sleep(this.pollIntervalMs, this.signal);
+            }
+            catch (error) {
+                if (isAbortError(error) || this.signal?.aborted || this.stopped) {
+                    return;
+                }
+                throw error;
+            }
+        }
+    }
+    async ackFailure(item, error, signal) {
+        await this.client.ackWriteback({
+            workspaceId: this.workspaceId,
+            itemId: item.id,
+            success: false,
+            error: toErrorMessage(error),
+            correlationId: item.correlationId,
+            signal
+        });
+    }
+}
+async function sleep(ms, signal) {
+    if (ms === 0) {
+        return;
+    }
+    if (signal?.aborted) {
+        throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+    }
+    await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new DOMException("The operation was aborted", "AbortError"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        if (!signal) {
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function isAbortError(error) {
+    return error instanceof DOMException && error.name === "AbortError";
+}
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },