@relayfile/sdk 0.1.4 → 0.1.6

package/README.md

@@ -40,6 +40,8 @@ await client.writeFile({
 });
 ```
 
+Use a relayfile JWT whose claims include `workspace_id`, `agent_name`, and `aud: ["relayfile"]`. The SDK adds `X-Correlation-Id` automatically for API calls.
+
 ## Full Docs
 
 Full documentation is available in the [relayfile docs](https://github.com/AgentWorkforce/relayfile/tree/main/docs).

package/dist/client.d.ts

@@ -1,4 +1,10 @@
 import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type EventFeedResponse, type ExportJsonResponse, type ExportOptions, type FileQueryResponse, type FileReadResponse, type FilesystemEvent, type GetEventsOptions, type GetAdminIngressStatusOptions, type GetAdminSyncStatusOptions, type GetOperationsOptions, type GetSyncDeadLettersOptions, type GetSyncIngressStatusOptions, type GetSyncStatusOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type QueryFilesOptions, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type AckWritebackInput, type AckWritebackResponse } from "./types.js";
+/**
+ * Bearer token or token factory used for Relayfile API requests.
+ *
+ * When you mint JWTs for Relayfile, the server expects claims like:
+ * `{ workspace_id: "ws_123", agent_name: "review-bot", aud: ["relayfile"] }`
+ */
 export type AccessTokenProvider = string | (() => string | Promise<string>);
 export interface RelayFileRetryOptions {
     maxRetries?: number;
@@ -11,6 +17,12 @@ export declare const DEFAULT_RELAYFILE_BASE_URL = "https://api.relayfile.dev";
 export interface RelayFileClientOptions {
     /** API base URL. Defaults to https://api.relayfile.dev */
     baseUrl?: string;
+    /**
+     * Bearer token or token factory for SDK requests.
+     *
+     * Relayfile-authenticated JWTs should include `workspace_id`, `agent_name`,
+     * and `aud` containing `relayfile`.
+     */
     token: AccessTokenProvider;
     fetchImpl?: typeof fetch;
     userAgent?: string;

package/dist/client.js

@@ -30,7 +30,19 @@ function buildQuery(params) {
     return encoded ? `?${encoded}` : "";
 }
 function generateCorrelationId() {
-    return `rf_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`;
+    return `rf_${crypto.randomUUID()}`;
+}
+function getHeaderValue(headers, name) {
+    if (!headers) {
+        return undefined;
+    }
+    const target = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === target) {
+            return value;
+        }
+    }
+    return undefined;
 }
 async function resolveToken(tokenProvider) {
     if (typeof tokenProvider === "function") {
@@ -202,21 +214,23 @@ export class RelayFileClient {
         });
     }
     async writeFile(input) {
-        const query = buildQuery({ path: input.path });
+        const { workspaceId, path, correlationId, baseRevision, content, contentType, encoding, semantics, signal } = input;
+        const query = buildQuery({ path });
         return this.request({
             method: "PUT",
-            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/file${query}`,
-            correlationId: input.correlationId,
+            path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/file${query}`,
+            correlationId,
             headers: {
-                "If-Match": input.baseRevision
+                "If-Match": baseRevision
             },
+            // Single-file PUT expects the target path in the query string, not the JSON body.
             body: {
-                contentType: input.contentType ?? "text/markdown",
-                content: input.content,
-                encoding: input.encoding,
+                contentType: contentType ?? "text/markdown",
+                content,
+                encoding,
                 semantics: input.semantics
             },
-            signal: input.signal
+            signal
         });
     }
     async bulkWrite(input) {
@@ -498,11 +512,14 @@ export class RelayFileClient {
         return payload;
     }
     async performRequest(params) {
-        const correlationId = params.correlationId ?? generateCorrelationId();
+        const existingCorrelationId = getHeaderValue(params.headers, "X-Correlation-Id");
+        const correlationId = existingCorrelationId ?? params.correlationId ?? generateCorrelationId();
         const baseHeaders = {
-            "X-Correlation-Id": correlationId,
-            ...params.headers
+            ...(params.headers ?? {})
         };
+        if (!existingCorrelationId) {
+            baseHeaders["X-Correlation-Id"] = correlationId;
+        }
         if (params.body !== undefined) {
             baseHeaders["Content-Type"] = "application/json";
         }

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type ConnectWebSocketOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
 export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState } from "./sync.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, 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, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackState, WritebackItem, WriteFileInput, WriteQueuedResponse } from "./types.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/types.d.ts

@@ -1,4 +1,25 @@
 export type FileNodeType = "file" | "dir";
+/**
+ * JWT claims expected by the Relayfile Go API when your token provider mints
+ * bearer tokens for SDK requests.
+ *
+ * Example minting payload:
+ * `const claims: RelayFileJwtClaims = { workspace_id: "ws_123", agent_name: "review-bot", aud: ["relayfile"] };`
+ */
+export interface RelayFileJwtClaims {
+    /** Workspace id the token is scoped to, for example `ws_123`. */
+    workspace_id: string;
+    /** Stable agent name presented to the Relayfile server, for example `review-bot`. */
+    agent_name: string;
+    /** Audience must contain `relayfile`. */
+    aud: "relayfile" | string[];
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    iss?: string;
+    sub?: string;
+    [claim: string]: unknown;
+}
 export interface TreeEntry {
     path: string;
     type: FileNodeType;

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.4",
+  "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"
   },