@relayfile/sdk 0.5.2 → 0.6.0

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayfileSetup, WorkspaceHandle } from "./setup.js";
+export { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
+export { WORKSPACE_INTEGRATION_PROVIDERS, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspacePermissions } from "./setup-types.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";

package/dist/index.js

@@ -1,4 +1,7 @@
 export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL } from "./client.js";
+export { RelayfileSetup, WorkspaceHandle } from "./setup.js";
+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 { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 // Integration providers

package/dist/setup-errors.d.ts

@@ -0,0 +1,44 @@
+import type { WorkspaceIntegrationProvider } from "./setup-types.js";
+export declare class RelayfileSetupError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class CloudApiError extends RelayfileSetupError {
+    readonly httpStatus: number;
+    readonly httpBody: unknown;
+    constructor(httpStatus: number, httpBody: unknown, message?: string);
+}
+export declare class MalformedCloudResponseError extends RelayfileSetupError {
+    readonly field: string;
+    readonly response: unknown;
+    constructor(field: string, response: unknown);
+}
+export declare class CloudTimeoutError extends RelayfileSetupError {
+    readonly operation: string;
+    readonly timeoutMs: number;
+    constructor(operation: string, timeoutMs: number);
+}
+export declare class IntegrationConnectionTimeoutError extends RelayfileSetupError {
+    readonly provider: WorkspaceIntegrationProvider;
+    readonly connectionId: string;
+    readonly elapsedMs: number;
+    readonly timeoutMs: number;
+    constructor(input: {
+        provider: WorkspaceIntegrationProvider;
+        connectionId: string;
+        elapsedMs: number;
+        timeoutMs: number;
+    });
+}
+export declare class CloudAbortError extends RelayfileSetupError {
+    readonly operation: string;
+    constructor(operation: string);
+}
+export declare class UnknownProviderError extends RelayfileSetupError {
+    readonly provider: string;
+    constructor(provider: string);
+}
+export declare class MissingConnectionIdError extends RelayfileSetupError {
+    readonly provider: WorkspaceIntegrationProvider;
+    constructor(provider: WorkspaceIntegrationProvider);
+}

package/dist/setup-errors.js

@@ -0,0 +1,79 @@
+export class RelayfileSetupError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+export class CloudApiError extends RelayfileSetupError {
+    httpStatus;
+    httpBody;
+    constructor(httpStatus, httpBody, message) {
+        super(message ??
+            readCloudErrorMessage(httpBody) ??
+            `Cloud API request failed with status ${httpStatus}.`, "cloud_api_error");
+        this.httpStatus = httpStatus;
+        this.httpBody = httpBody;
+    }
+}
+export class MalformedCloudResponseError extends RelayfileSetupError {
+    field;
+    response;
+    constructor(field, response) {
+        super(`Cloud API response is missing required field "${field}".`, "malformed_cloud_response");
+        this.field = field;
+        this.response = response;
+    }
+}
+export class CloudTimeoutError extends RelayfileSetupError {
+    operation;
+    timeoutMs;
+    constructor(operation, timeoutMs) {
+        super(`Timed out while waiting for ${operation} after ${timeoutMs}ms.`, "cloud_timeout_error");
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class IntegrationConnectionTimeoutError extends RelayfileSetupError {
+    provider;
+    connectionId;
+    elapsedMs;
+    timeoutMs;
+    constructor(input) {
+        super(`Timed out waiting for ${input.provider} connection "${input.connectionId}" after ${input.elapsedMs}ms.`, "integration_connection_timeout");
+        this.provider = input.provider;
+        this.connectionId = input.connectionId;
+        this.elapsedMs = input.elapsedMs;
+        this.timeoutMs = input.timeoutMs;
+    }
+}
+export class CloudAbortError extends RelayfileSetupError {
+    operation;
+    constructor(operation) {
+        super(`Aborted while waiting for ${operation}.`, "cloud_abort_error");
+        this.operation = operation;
+    }
+}
+export class UnknownProviderError extends RelayfileSetupError {
+    provider;
+    constructor(provider) {
+        super(`Unknown workspace integration provider "${provider}".`, "unknown_provider");
+        this.provider = provider;
+    }
+}
+export class MissingConnectionIdError extends RelayfileSetupError {
+    provider;
+    constructor(provider) {
+        super(`No connectionId is available for provider "${provider}".`, "missing_connection_id");
+        this.provider = provider;
+    }
+}
+function readCloudErrorMessage(httpBody) {
+    if (!httpBody || typeof httpBody !== "object" || Array.isArray(httpBody)) {
+        return undefined;
+    }
+    const data = httpBody;
+    const message = data.message ?? data.error;
+    return typeof message === "string" && message.trim() !== "" ? message : undefined;
+}

package/dist/setup-types.d.ts

@@ -0,0 +1,54 @@
+import type { AccessTokenProvider } from "./client.js";
+export declare const WORKSPACE_INTEGRATION_PROVIDERS: readonly ["github", "slack-sage", "slack-my-senior-dev", "slack-nightcto", "notion", "linear"];
+export type WorkspaceIntegrationProvider = (typeof WORKSPACE_INTEGRATION_PROVIDERS)[number];
+export interface WorkspacePermissions {
+    readonly?: string[];
+    ignored?: string[];
+}
+export interface RelayfileSetupRetryOptions {
+    maxRetries: number;
+    baseDelayMs: number;
+}
+export interface RelayfileSetupOptions {
+    cloudApiUrl?: string;
+    accessToken?: AccessTokenProvider;
+    requestTimeoutMs?: number;
+    retry?: RelayfileSetupRetryOptions;
+}
+export interface CreateWorkspaceOptions {
+    name?: string;
+    permissions?: WorkspacePermissions;
+    agentName?: string;
+    scopes?: string[];
+}
+export interface JoinWorkspaceOptions {
+    agentName?: string;
+    scopes?: string[];
+    permissions?: WorkspacePermissions;
+}
+export interface WorkspaceInfo {
+    workspaceId: string;
+    relayfileUrl: string;
+    relaycastApiKey: string;
+    createdAt?: string;
+    name?: string;
+    wsUrl?: string;
+}
+export interface ConnectIntegrationOptions {
+    connectionId?: string;
+    allowedIntegrations?: string[];
+}
+export interface ConnectIntegrationResult {
+    connectLink: string | null;
+    sessionToken: string | null;
+    expiresAt: string | null;
+    alreadyConnected: boolean;
+    connectionId: string;
+}
+export interface WaitForConnectionOptions {
+    connectionId?: string;
+    intervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onPoll?: (attempt: number, ready: boolean) => void;
+}

package/dist/setup-types.js

@@ -0,0 +1,8 @@
+export const WORKSPACE_INTEGRATION_PROVIDERS = [
+    "github",
+    "slack-sage",
+    "slack-my-senior-dev",
+    "slack-nightcto",
+    "notion",
+    "linear"
+];

package/dist/setup.d.ts

@@ -0,0 +1,64 @@
+import { RelayFileClient, type AccessTokenProvider } from "./client.js";
+import { type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspacePermissions } from "./setup-types.js";
+interface JoinWorkspaceResponse {
+    workspaceId?: string;
+    token?: string;
+    relayfileUrl?: string;
+    wsUrl?: string;
+    relaycastApiKey?: string;
+}
+interface NormalizedJoinWorkspaceOptions {
+    agentName: string;
+    scopes: string[];
+    permissions?: WorkspacePermissions;
+}
+interface CloudRequestOptions {
+    operation: string;
+    method: string;
+    path: string;
+    body?: unknown;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    tokenProvider?: AccessTokenProvider;
+}
+interface WorkspaceHandleOptions {
+    setup: RelayfileSetup;
+    info: WorkspaceInfo;
+    token: string;
+    joinOptions: NormalizedJoinWorkspaceOptions;
+}
+export declare class RelayfileSetup {
+    private readonly cloudApiUrl;
+    private readonly accessToken?;
+    private readonly requestTimeoutMs;
+    private readonly retryOptions;
+    constructor(options?: RelayfileSetupOptions);
+    createWorkspace(options?: CreateWorkspaceOptions): Promise<WorkspaceHandle>;
+    joinWorkspace(workspaceId: string, options?: JoinWorkspaceOptions): Promise<WorkspaceHandle>;
+    joinWorkspaceResponse(workspaceId: string, options: NormalizedJoinWorkspaceOptions): Promise<Required<JoinWorkspaceResponse>>;
+    requestJson(options: CloudRequestOptions): Promise<unknown>;
+}
+export declare class WorkspaceHandle {
+    readonly info: WorkspaceInfo;
+    readonly workspaceId: string;
+    private readonly _setup;
+    private readonly _joinOptions;
+    private readonly _pendingConnections;
+    private _token;
+    private _tokenIssuedAt;
+    private _client?;
+    private _refreshPromise?;
+    constructor(options: WorkspaceHandleOptions);
+    client(): RelayFileClient;
+    connectIntegration(provider: WorkspaceIntegrationProvider, options?: ConnectIntegrationOptions): Promise<ConnectIntegrationResult>;
+    waitForConnection(provider: WorkspaceIntegrationProvider, options?: WaitForConnectionOptions): Promise<void>;
+    isConnected(provider: WorkspaceIntegrationProvider, connectionId: string): Promise<boolean>;
+    disconnectIntegration(provider: WorkspaceIntegrationProvider, _connectionId?: string): Promise<void>;
+    getToken(): string;
+    refreshToken(): Promise<void>;
+    private performRefreshToken;
+    private getOrRefreshToken;
+    private resolveConnectionId;
+    private getConnectionStatus;
+}
+export {};

package/dist/setup.js

@@ -0,0 +1,524 @@
+import { RelayFileClient } from "./client.js";
+import { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, UnknownProviderError } from "./setup-errors.js";
+import { WORKSPACE_INTEGRATION_PROVIDERS } from "./setup-types.js";
+const DEFAULT_CLOUD_API_URL = "https://agentrelay.com/cloud";
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+const DEFAULT_RETRY_MAX_DELAY_MS = 5_000;
+const DEFAULT_RETRY_MAX_RETRIES = 3;
+const DEFAULT_AGENT_NAME = "sdk-agent";
+const DEFAULT_SCOPES = ["fs:read", "fs:write"];
+const DEFAULT_WAIT_INTERVAL_MS = 2_000;
+const DEFAULT_WAIT_TIMEOUT_MS = 300_000;
+const TOKEN_REFRESH_AGE_MS = 55 * 60 * 1000;
+export class RelayfileSetup {
+    cloudApiUrl;
+    accessToken;
+    requestTimeoutMs;
+    retryOptions;
+    constructor(options = {}) {
+        this.cloudApiUrl = options.cloudApiUrl ?? DEFAULT_CLOUD_API_URL;
+        this.accessToken = options.accessToken;
+        this.requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS));
+        this.retryOptions = normalizeRetryOptions(options.retry);
+    }
+    async createWorkspace(options = {}) {
+        const createResponse = validateCreateWorkspaceResponse(await this.requestJson({
+            operation: "createWorkspace",
+            method: "POST",
+            path: "api/v1/workspaces",
+            body: compactObject({
+                name: options.name,
+                permissions: clonePermissions(options.permissions)
+            })
+        }));
+        const joinOptions = normalizeJoinWorkspaceOptions({
+            agentName: options.agentName,
+            scopes: options.scopes,
+            permissions: options.permissions
+        });
+        const joinResponse = await this.joinWorkspaceResponse(createResponse.workspaceId, joinOptions);
+        return new WorkspaceHandle({
+            setup: this,
+            info: {
+                workspaceId: createResponse.workspaceId,
+                relayfileUrl: joinResponse.relayfileUrl,
+                relaycastApiKey: joinResponse.relaycastApiKey,
+                createdAt: createResponse.createdAt,
+                name: createResponse.name,
+                wsUrl: joinResponse.wsUrl
+            },
+            token: joinResponse.token,
+            joinOptions
+        });
+    }
+    async joinWorkspace(workspaceId, options = {}) {
+        const joinOptions = normalizeJoinWorkspaceOptions(options);
+        const joinResponse = await this.joinWorkspaceResponse(workspaceId, joinOptions);
+        return new WorkspaceHandle({
+            setup: this,
+            info: {
+                workspaceId: joinResponse.workspaceId,
+                relayfileUrl: joinResponse.relayfileUrl,
+                relaycastApiKey: joinResponse.relaycastApiKey,
+                wsUrl: joinResponse.wsUrl
+            },
+            token: joinResponse.token,
+            joinOptions
+        });
+    }
+    async joinWorkspaceResponse(workspaceId, options) {
+        return validateJoinWorkspaceResponse(await this.requestJson({
+            operation: "joinWorkspace",
+            method: "POST",
+            path: `api/v1/workspaces/${encodeURIComponent(workspaceId)}/join`,
+            body: compactObject({
+                agentName: options.agentName,
+                scopes: [...options.scopes],
+                permissions: clonePermissions(options.permissions)
+            })
+        }));
+    }
+    async requestJson(options) {
+        const url = buildCloudUrl(this.cloudApiUrl, options.path);
+        const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+        let retries = 0;
+        for (;;) {
+            const token = await resolveToken(options.tokenProvider ?? this.accessToken);
+            const headers = {};
+            if (token) {
+                headers.Authorization = `Bearer ${token}`;
+            }
+            if (body !== undefined) {
+                headers["Content-Type"] = "application/json";
+            }
+            let response;
+            try {
+                response = await fetchWithTimeout(url, {
+                    method: options.method,
+                    headers,
+                    body,
+                    signal: options.signal
+                }, options.timeoutMs ?? this.requestTimeoutMs, options.operation);
+            }
+            catch (error) {
+                if (error instanceof CloudAbortError ||
+                    error instanceof CloudTimeoutError) {
+                    throw error;
+                }
+                if (!shouldRetryError(error, retries, this.retryOptions.maxRetries, options.signal)) {
+                    throw error;
+                }
+                retries += 1;
+                await sleep(computeRetryDelayMs(this.retryOptions, retries, null), options.signal, options.operation);
+                continue;
+            }
+            const payload = await readResponseBody(response);
+            if (response.ok) {
+                return payload;
+            }
+            if (shouldRetryStatus(response.status, retries, this.retryOptions.maxRetries, options.signal)) {
+                retries += 1;
+                await sleep(computeRetryDelayMs(this.retryOptions, retries, response.headers.get("retry-after")), options.signal, options.operation);
+                continue;
+            }
+            throw new CloudApiError(response.status, payload);
+        }
+    }
+}
+export class WorkspaceHandle {
+    info;
+    workspaceId;
+    _setup;
+    _joinOptions;
+    _pendingConnections = new Map();
+    _token;
+    _tokenIssuedAt;
+    _client;
+    _refreshPromise;
+    constructor(options) {
+        this.info = options.info;
+        this.workspaceId = options.info.workspaceId;
+        this._setup = options.setup;
+        this._joinOptions = {
+            agentName: options.joinOptions.agentName,
+            scopes: [...options.joinOptions.scopes],
+            permissions: clonePermissions(options.joinOptions.permissions)
+        };
+        this._token = options.token;
+        this._tokenIssuedAt = Date.now();
+    }
+    client() {
+        if (!this._client) {
+            this._client = new RelayFileClient({
+                baseUrl: this.info.relayfileUrl,
+                token: async () => this.getOrRefreshToken()
+            });
+        }
+        return this._client;
+    }
+    async connectIntegration(provider, options = {}) {
+        assertProvider(provider);
+        const requestedConnectionId = normalizeConnectionId(options.connectionId);
+        if (requestedConnectionId) {
+            const alreadyConnected = await this.isConnected(provider, requestedConnectionId);
+            if (alreadyConnected) {
+                this._pendingConnections.set(provider, requestedConnectionId);
+                return {
+                    alreadyConnected: true,
+                    connectLink: null,
+                    sessionToken: null,
+                    expiresAt: null,
+                    connectionId: requestedConnectionId
+                };
+            }
+        }
+        const response = validateConnectSessionResponse(await this._setup.requestJson({
+            operation: "connectIntegration",
+            method: "POST",
+            path: `api/v1/workspaces/${encodeURIComponent(this.workspaceId)}/integrations/connect-session`,
+            body: {
+                allowedIntegrations: options.allowedIntegrations && options.allowedIntegrations.length > 0
+                    ? [...options.allowedIntegrations]
+                    : [provider]
+            },
+            tokenProvider: async () => this.getOrRefreshToken()
+        }));
+        const connectionId = normalizeConnectionId(response.connectionId) ?? this.workspaceId;
+        this._pendingConnections.set(provider, connectionId);
+        return {
+            alreadyConnected: false,
+            connectLink: response.connectLink,
+            sessionToken: response.token,
+            expiresAt: response.expiresAt,
+            connectionId
+        };
+    }
+    async waitForConnection(provider, options = {}) {
+        assertProvider(provider);
+        const connectionId = this.resolveConnectionId(provider, options.connectionId);
+        const intervalMs = Math.max(0, Math.floor(options.intervalMs ?? DEFAULT_WAIT_INTERVAL_MS));
+        const timeoutMs = Math.max(1, Math.floor(options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS));
+        const startedAt = Date.now();
+        let attempt = 0;
+        for (;;) {
+            throwIfAborted(options.signal, "waitForConnection");
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs >= timeoutMs) {
+                throw new IntegrationConnectionTimeoutError({
+                    provider,
+                    connectionId,
+                    elapsedMs,
+                    timeoutMs
+                });
+            }
+            attempt += 1;
+            const remainingMs = timeoutMs - elapsedMs;
+            let ready;
+            try {
+                ready = await this.getConnectionStatus(provider, connectionId, {
+                    signal: options.signal,
+                    timeoutMs: remainingMs
+                });
+            }
+            catch (error) {
+                if (error instanceof CloudTimeoutError) {
+                    throw new IntegrationConnectionTimeoutError({
+                        provider,
+                        connectionId,
+                        elapsedMs: Date.now() - startedAt,
+                        timeoutMs
+                    });
+                }
+                throw error;
+            }
+            options.onPoll?.(attempt, ready);
+            if (ready) {
+                return;
+            }
+            const sleepMs = Math.min(intervalMs, Math.max(0, timeoutMs - (Date.now() - startedAt)));
+            await sleep(sleepMs, options.signal, "waitForConnection");
+        }
+    }
+    async isConnected(provider, connectionId) {
+        assertProvider(provider);
+        return this.getConnectionStatus(provider, this.resolveConnectionId(provider, connectionId));
+    }
+    async disconnectIntegration(provider, _connectionId) {
+        assertProvider(provider);
+        await this._setup.requestJson({
+            operation: "disconnectIntegration",
+            method: "DELETE",
+            path: `api/v1/workspaces/${encodeURIComponent(this.workspaceId)}/integrations/${encodeURIComponent(provider)}/status`,
+            tokenProvider: async () => this.getOrRefreshToken()
+        });
+        this._pendingConnections.delete(provider);
+    }
+    getToken() {
+        return this._token;
+    }
+    async refreshToken() {
+        if (!this._refreshPromise) {
+            this._refreshPromise = this.performRefreshToken();
+        }
+        try {
+            await this._refreshPromise;
+        }
+        finally {
+            this._refreshPromise = undefined;
+        }
+    }
+    async performRefreshToken() {
+        const response = await this._setup.joinWorkspaceResponse(this.workspaceId, this._joinOptions);
+        this._token = response.token;
+        this._tokenIssuedAt = Date.now();
+    }
+    async getOrRefreshToken() {
+        if (Date.now() - this._tokenIssuedAt >= TOKEN_REFRESH_AGE_MS) {
+            await this.refreshToken();
+        }
+        return this._token;
+    }
+    resolveConnectionId(provider, connectionId) {
+        const resolved = normalizeConnectionId(connectionId) ?? this._pendingConnections.get(provider);
+        if (!resolved) {
+            throw new MissingConnectionIdError(provider);
+        }
+        return resolved;
+    }
+    async getConnectionStatus(provider, connectionId, options = {}) {
+        const query = new URLSearchParams({ connectionId });
+        const response = validateIntegrationStatusResponse(await this._setup.requestJson({
+            operation: "getIntegrationStatus",
+            method: "GET",
+            path: `api/v1/workspaces/${encodeURIComponent(this.workspaceId)}/integrations/${encodeURIComponent(provider)}/status?${query.toString()}`,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+            tokenProvider: async () => this.getOrRefreshToken()
+        }));
+        return response.ready;
+    }
+}
+function assertProvider(provider) {
+    if (!WORKSPACE_INTEGRATION_PROVIDERS.includes(provider)) {
+        throw new UnknownProviderError(provider);
+    }
+}
+function normalizeJoinWorkspaceOptions(options = {}) {
+    return {
+        agentName: normalizeNonEmptyString(options.agentName) ?? DEFAULT_AGENT_NAME,
+        scopes: options.scopes && options.scopes.length > 0
+            ? [...options.scopes]
+            : [...DEFAULT_SCOPES],
+        permissions: clonePermissions(options.permissions)
+    };
+}
+function normalizeRetryOptions(options) {
+    const maxRetries = Math.max(0, Math.floor(options?.maxRetries ?? DEFAULT_RETRY_MAX_RETRIES));
+    const baseDelayMs = Math.max(1, Math.floor(options?.baseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS));
+    return {
+        maxRetries,
+        baseDelayMs,
+        maxDelayMs: DEFAULT_RETRY_MAX_DELAY_MS
+    };
+}
+function validateCreateWorkspaceResponse(payload) {
+    return {
+        workspaceId: requireStringField(payload, "workspaceId"),
+        relayfileUrl: requireStringField(payload, "relayfileUrl"),
+        relaycastApiKey: requireStringField(payload, "relaycastApiKey"),
+        createdAt: requireStringField(payload, "createdAt"),
+        name: readOptionalStringField(payload, "name")
+    };
+}
+function validateJoinWorkspaceResponse(payload) {
+    return {
+        workspaceId: requireStringField(payload, "workspaceId"),
+        token: requireStringField(payload, "token"),
+        relayfileUrl: requireStringField(payload, "relayfileUrl"),
+        wsUrl: requireStringField(payload, "wsUrl"),
+        relaycastApiKey: requireStringField(payload, "relaycastApiKey")
+    };
+}
+function validateConnectSessionResponse(payload) {
+    return {
+        token: requireStringField(payload, "token"),
+        expiresAt: requireStringField(payload, "expiresAt"),
+        connectLink: requireStringField(payload, "connectLink"),
+        connectionId: readOptionalStringField(payload, "connectionId")
+    };
+}
+function validateIntegrationStatusResponse(payload) {
+    return {
+        ready: requireBooleanField(payload, "ready")
+    };
+}
+function requireStringField(payload, field) {
+    const value = readField(payload, field);
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return value;
+}
+function readOptionalStringField(payload, field) {
+    const value = readField(payload, field);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return value;
+}
+function requireBooleanField(payload, field) {
+    const value = readField(payload, field);
+    if (typeof value !== "boolean") {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return value;
+}
+function readField(payload, field) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return undefined;
+    }
+    return payload[field];
+}
+function normalizeConnectionId(connectionId) {
+    return normalizeNonEmptyString(connectionId);
+}
+function normalizeNonEmptyString(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}
+function clonePermissions(permissions) {
+    if (!permissions) {
+        return undefined;
+    }
+    return compactObject({
+        readonly: permissions.readonly ? [...permissions.readonly] : undefined,
+        ignored: permissions.ignored ? [...permissions.ignored] : undefined
+    });
+}
+function compactObject(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function buildCloudUrl(baseUrl, path) {
+    const base = new URL(baseUrl);
+    if (!base.pathname.endsWith("/")) {
+        base.pathname = `${base.pathname}/`;
+    }
+    return new URL(path.replace(/^\/+/, ""), base).toString();
+}
+async function resolveToken(provider) {
+    if (!provider) {
+        return undefined;
+    }
+    return typeof provider === "function" ? provider() : provider;
+}
+async function fetchWithTimeout(url, init, timeoutMs, operation) {
+    if (init.signal?.aborted) {
+        throw new CloudAbortError(operation);
+    }
+    let didTimeout = false;
+    let didAbort = false;
+    const controller = new AbortController();
+    const onAbort = () => {
+        didAbort = true;
+        controller.abort();
+    };
+    const timer = setTimeout(() => {
+        didTimeout = true;
+        controller.abort();
+    }, timeoutMs);
+    init.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (didTimeout) {
+            throw new CloudTimeoutError(operation, timeoutMs);
+        }
+        if (didAbort || init.signal?.aborted) {
+            throw new CloudAbortError(operation);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        init.signal?.removeEventListener("abort", onAbort);
+    }
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (text === "") {
+        return null;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function shouldRetryStatus(status, retries, maxRetries, signal) {
+    if (signal?.aborted || retries >= maxRetries) {
+        return false;
+    }
+    return status === 429 || (status >= 500 && status <= 599);
+}
+function shouldRetryError(error, retries, maxRetries, signal) {
+    if (signal?.aborted || retries >= maxRetries) {
+        return false;
+    }
+    return !(error instanceof Error && error.name === "AbortError");
+}
+function computeRetryDelayMs(options, retryAttempt, retryAfterHeader) {
+    const retryAfterMs = parseRetryAfterMs(retryAfterHeader);
+    if (retryAfterMs !== null) {
+        return Math.min(options.maxDelayMs, retryAfterMs);
+    }
+    const backoff = options.baseDelayMs * Math.pow(2, Math.max(0, retryAttempt - 1));
+    return Math.min(options.maxDelayMs, backoff);
+}
+function parseRetryAfterMs(retryAfterHeader) {
+    if (!retryAfterHeader) {
+        return null;
+    }
+    const seconds = Number.parseInt(retryAfterHeader, 10);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    const timestamp = Date.parse(retryAfterHeader);
+    if (!Number.isNaN(timestamp)) {
+        return Math.max(0, timestamp - Date.now());
+    }
+    return null;
+}
+async function sleep(delayMs, signal, operation) {
+    if (delayMs <= 0) {
+        throwIfAborted(signal, operation);
+        return;
+    }
+    throwIfAborted(signal, operation);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, delayMs);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            reject(new CloudAbortError(operation));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function throwIfAborted(signal, operation) {
+    if (signal?.aborted) {
+        throw new CloudAbortError(operation);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,10 +12,11 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "setup:e2e": "node scripts/setup-e2e.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.5.2"
+    "@relayfile/core": "0.6.0"
   },
   "devDependencies": {
     "typescript": "^5.7.3",