@relayfile/sdk 0.3.0 → 0.3.2

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-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";
+import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type CommitForkInput, type CommitForkResponse, type CreateForkInput, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type DiscardForkInput, 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 ReadFileInput, type QueryFilesOptions, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type AckWritebackInput, type AckWritebackResponse } from "./types.js";
+import type { ForkHandle } from "@relayfile/core";
 /**
  * Bearer token or token factory used for Relayfile API requests.
  *
@@ -52,10 +53,14 @@ export declare class RelayFileClient {
     constructor(options: RelayFileClientOptions);
     listTree(workspaceId: string, options?: ListTreeOptions): Promise<TreeResponse>;
     readFile(workspaceId: string, path: string, correlationId?: string, signal?: AbortSignal): Promise<FileReadResponse>;
+    readFile(input: ReadFileInput): Promise<FileReadResponse>;
     queryFiles(workspaceId: string, options?: QueryFilesOptions): Promise<FileQueryResponse>;
     writeFile(input: WriteFileInput): Promise<WriteQueuedResponse>;
     bulkWrite(input: BulkWriteInput): Promise<BulkWriteResponse>;
     deleteFile(input: DeleteFileInput): Promise<WriteQueuedResponse>;
+    createFork(input: CreateForkInput): Promise<ForkHandle>;
+    discardFork(input: DiscardForkInput): Promise<void>;
+    commitFork(input: CommitForkInput): Promise<CommitForkResponse>;
     getEvents(workspaceId: string, options?: GetEventsOptions): Promise<EventFeedResponse>;
     exportWorkspace(options: ExportOptions): Promise<ExportJsonResponse | Blob>;
     connectWebSocket(workspaceId: string, options?: ConnectWebSocketOptions): WebSocketConnection;

package/dist/client.js

@@ -80,6 +80,18 @@ function normalizeExportJsonResponse(payload) {
         files: Array.isArray(data.files) ? data.files : []
     };
 }
+function normalizeErrorDetails(data, explicitDetails) {
+    if (explicitDetails && typeof explicitDetails === "object" && !Array.isArray(explicitDetails)) {
+        return explicitDetails;
+    }
+    const details = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (key !== "code" && key !== "message" && key !== "correlationId") {
+            details[key] = value;
+        }
+    }
+    return Object.keys(details).length > 0 ? details : undefined;
+}
 class RelayFileWebSocketConnection {
     socket;
     handlers = {
@@ -163,7 +175,8 @@ export class RelayFileClient {
         const query = buildQuery({
             path: options.path ?? "/",
             depth: options.depth,
-            cursor: options.cursor
+            cursor: options.cursor,
+            forkId: options.forkId
         });
         return this.request({
             method: "GET",
@@ -172,13 +185,21 @@ export class RelayFileClient {
             signal: options.signal
         });
     }
-    async readFile(workspaceId, path, correlationId, signal) {
-        const query = buildQuery({ path });
+    async readFile(workspaceOrInput, path, correlationId, signal) {
+        const input = typeof workspaceOrInput === "string"
+            ? {
+                workspaceId: workspaceOrInput,
+                path: path ?? "",
+                correlationId,
+                signal
+            }
+            : workspaceOrInput;
+        const query = buildQuery({ path: input.path, forkId: input.forkId });
         return this.request({
             method: "GET",
-            path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/file${query}`,
-            correlationId,
-            signal
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/file${query}`,
+            correlationId: input.correlationId,
+            signal: input.signal
         });
     }
     async queryFiles(workspaceId, options = {}) {
@@ -197,6 +218,8 @@ export class RelayFileClient {
             params.set("cursor", options.cursor);
         if (options.limit !== undefined)
             params.set("limit", String(options.limit));
+        if (options.forkId !== undefined)
+            params.set("forkId", options.forkId);
         if (options.properties !== undefined) {
             for (const [key, value] of Object.entries(options.properties)) {
                 if (key !== "" && value !== undefined) {
@@ -214,8 +237,8 @@ export class RelayFileClient {
         });
     }
     async writeFile(input) {
-        const { workspaceId, path, correlationId, baseRevision, content, contentType, encoding, semantics, signal } = input;
-        const query = buildQuery({ path });
+        const { workspaceId, path, correlationId, baseRevision, content, contentType, encoding, contentIdentity, signal } = input;
+        const query = buildQuery({ path, forkId: input.forkId });
         return this.request({
             method: "PUT",
             path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/file${query}`,
@@ -228,15 +251,17 @@ export class RelayFileClient {
                 contentType: contentType ?? "text/markdown",
                 content,
                 encoding,
-                semantics: input.semantics
+                semantics: input.semantics,
+                ...(contentIdentity ? { contentIdentity } : {})
             },
             signal
         });
     }
     async bulkWrite(input) {
+        const query = buildQuery({ forkId: input.forkId });
         const response = await this.performRequest({
             method: "POST",
-            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/bulk`,
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/bulk${query}`,
             correlationId: input.correlationId,
             body: {
                 files: input.files
@@ -246,7 +271,7 @@ export class RelayFileClient {
         return this.readPayload(response);
     }
     async deleteFile(input) {
-        const query = buildQuery({ path: input.path });
+        const query = buildQuery({ path: input.path, forkId: input.forkId });
         return this.request({
             method: "DELETE",
             path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/file${query}`,
@@ -257,6 +282,37 @@ export class RelayFileClient {
             signal: input.signal
         });
     }
+    async createFork(input) {
+        const body = {
+            proposalId: input.proposalId
+        };
+        if (input.ttlSeconds !== undefined) {
+            body.ttlSeconds = input.ttlSeconds;
+        }
+        return this.request({
+            method: "POST",
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/forks`,
+            correlationId: input.correlationId,
+            body,
+            signal: input.signal
+        });
+    }
+    async discardFork(input) {
+        await this.performRequest({
+            method: "DELETE",
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/forks/${encodeURIComponent(input.forkId)}`,
+            correlationId: input.correlationId,
+            signal: input.signal
+        });
+    }
+    async commitFork(input) {
+        return this.request({
+            method: "POST",
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/forks/${encodeURIComponent(input.forkId)}/commit`,
+            correlationId: input.correlationId,
+            signal: input.signal
+        });
+    }
     async getEvents(workspaceId, options = {}) {
         const query = buildQuery({
             provider: options.provider,
@@ -648,7 +704,9 @@ export class RelayFileClient {
         };
     }
     throwForError(status, payload, headers) {
-        const data = (payload ?? {});
+        const rawData = (payload ?? {});
+        const data = rawData;
+        const details = normalizeErrorDetails(rawData, data.details);
         if (status === 409 &&
             typeof data.expectedRevision === "string" &&
             typeof data.currentRevision === "string") {
@@ -656,7 +714,7 @@ export class RelayFileClient {
                 code: data.code ?? "revision_conflict",
                 message: data.message ?? "Revision conflict",
                 correlationId: data.correlationId ?? "",
-                details: data.details,
+                details,
                 expectedRevision: data.expectedRevision,
                 currentRevision: data.currentRevision,
                 currentContentPreview: data.currentContentPreview
@@ -667,7 +725,7 @@ export class RelayFileClient {
                 code: data.code,
                 message: data.message ?? "Invalid resource state",
                 correlationId: data.correlationId,
-                details: data.details
+                details
             });
         }
         if (status === 429 && data.code === "queue_full") {
@@ -683,7 +741,7 @@ export class RelayFileClient {
                 code: data.code,
                 message: data.message ?? "Ingress queue full",
                 correlationId: data.correlationId,
-                details: data.details
+                details
             }, retryAfterSeconds);
         }
         if (status === 413) {
@@ -691,14 +749,14 @@ export class RelayFileClient {
                 code: data.code ?? "payload_too_large",
                 message: data.message ?? "Request payload exceeds configured limit",
                 correlationId: data.correlationId,
-                details: data.details
+                details
             });
         }
         throw new RelayFileApiError(status, {
             code: data.code ?? "api_error",
             message: data.message ?? `HTTP ${status}`,
             correlationId: data.correlationId,
-            details: data.details
+            details
         });
     }
 }

package/dist/index.d.ts

@@ -4,7 +4,8 @@ export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiEr
 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 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 { WritebackConsumer } from "./writeback-consumer.js";
 export type { WritebackHandler, WritebackConsumerOptions } from "./writeback-consumer.js";
 export * from "./integration-adapter.js";

package/dist/types.d.ts

@@ -44,6 +44,17 @@ export interface FileSemantics {
     permissions?: string[];
     comments?: string[];
 }
+/**
+ * Stable identity for an idempotent write, used by the server to coalesce
+ * duplicate deliveries (webhook retries, cross-product fan-in). Two writes
+ * with equal `(kind, key)` in the same workspace within the dedup window
+ * resolve to the same op. Callers typically derive `key` from the upstream
+ * event id, e.g. `github:push:<sha>`.
+ */
+export interface ContentIdentity {
+    kind: string;
+    key: string;
+}
 export interface FileReadResponse {
     path: string;
     revision: string;
@@ -60,16 +71,19 @@ export interface FileWriteRequest {
     content: string;
     encoding?: "utf-8" | "base64";
     semantics?: FileSemantics;
+    contentIdentity?: ContentIdentity;
 }
 export interface BulkWriteFile {
     path: string;
     contentType?: string;
     content: string;
     encoding?: "utf-8" | "base64";
+    contentIdentity?: ContentIdentity;
 }
 export interface BulkWriteInput {
     workspaceId: string;
     files: BulkWriteFile[];
+    forkId?: string;
     correlationId?: string;
     signal?: AbortSignal;
 }
@@ -311,6 +325,7 @@ export interface ListTreeOptions {
     path?: string;
     depth?: number;
     cursor?: string;
+    forkId?: string;
     correlationId?: string;
     signal?: AbortSignal;
 }
@@ -323,6 +338,14 @@ export interface QueryFilesOptions {
     properties?: Record<string, string>;
     cursor?: string;
     limit?: number;
+    forkId?: string;
+    correlationId?: string;
+    signal?: AbortSignal;
+}
+export interface ReadFileInput {
+    workspaceId: string;
+    path: string;
+    forkId?: string;
     correlationId?: string;
     signal?: AbortSignal;
 }
@@ -435,6 +458,8 @@ export interface WriteFileInput {
     contentType?: string;
     encoding?: "utf-8" | "base64";
     semantics?: FileSemantics;
+    forkId?: string;
+    contentIdentity?: ContentIdentity;
     correlationId?: string;
     signal?: AbortSignal;
 }
@@ -442,9 +467,34 @@ export interface DeleteFileInput {
     workspaceId: string;
     path: string;
     baseRevision: string;
+    forkId?: string;
+    correlationId?: string;
+    signal?: AbortSignal;
+}
+export interface CreateForkInput {
+    workspaceId: string;
+    proposalId: string;
+    ttlSeconds?: number;
+    correlationId?: string;
+    signal?: AbortSignal;
+}
+export interface DiscardForkInput {
+    workspaceId: string;
+    forkId: string;
     correlationId?: string;
     signal?: AbortSignal;
 }
+export interface CommitForkInput {
+    workspaceId: string;
+    forkId: string;
+    correlationId?: string;
+    signal?: AbortSignal;
+}
+export interface CommitForkResponse {
+    revision: string;
+    writtenCount: number;
+    deletedCount: number;
+}
 export interface IngestWebhookInput {
     workspaceId: string;
     provider: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,9 @@
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
+  "dependencies": {
+    "@relayfile/core": "0.3.2"
+  },
   "devDependencies": {
     "typescript": "^5.7.3",
     "vitest": "^3.0.0"