@relayfile/sdk 0.5.3 → 0.6.1

package/README.md

@@ -8,7 +8,68 @@ TypeScript SDK for relayfile — real-time filesystem for humans and agents.
 npm install @relayfile/sdk
 ```
 
-## Quick Example
+## Agent Workspace — Golden Path
+
+The recommended way to use `@relayfile/sdk` in an agent workflow is through
+`RelayfileSetup`. This handles workspace creation, Notion authorization,
+environment variable generation for `relayfile-mount`, and agent invites.
+
+```ts
+import { RelayfileSetup } from '@relayfile/sdk'
+
+const setup = await RelayfileSetup.login({
+  onLoginUrl: (url) => console.log(`Sign in to Relayfile Cloud: ${url}`),
+})
+
+// Create or resume a workspace
+const workspace = await setup.createWorkspace({
+  name: 'notion-research-room',
+  agentName: 'lead-agent',
+})
+
+// Connect Notion — returns a link for the human to open
+const notion = await workspace.connectNotion()
+if (notion.connectLink) {
+  console.log(`Connect Notion: ${notion.connectLink}`)
+  await workspace.waitForNotion({ timeoutMs: 5 * 60_000 })
+}
+
+// Env vars for relayfile-mount (local dir or cloud sandbox)
+const mountEnv = workspace.mountEnv({
+  localDir: '/workspace/notion',
+  remotePath: '/notion',
+})
+
+// Secret invite payload for a trusted co-worker agent
+const invite = workspace.agentInvite({
+  agentName: 'review-agent',
+  scopes: ['fs:read', 'relaycast:write'],
+})
+// Never log invite — it contains credential material
+```
+
+For the full end-to-end journey, failure modes, and acceptance criteria see
+[`docs/agent-workspace-golden-path.md`](../../../docs/agent-workspace-golden-path.md).
+
+Run the demo locally:
+
+```bash
+npm run demo:agent-workspace --workspace=packages/sdk/typescript
+```
+
+The demo defaults to in-process mock cloud and relayfile servers, seeds a `/notion`
+file, mounts it through the deterministic harness, and proves read-only invited-agent
+behavior without requiring real Notion, Relaycast, or cloud credentials. For a real
+deployment, use `RelayfileSetup.login()` to send the human one Cloud sign-in URL,
+or use `RelayfileSetup.fromCloudTokens()` with previously persisted Cloud tokens.
+You can still pass `accessToken` directly to `new RelayfileSetup()` in CI or
+advanced hosts that already provide a valid Cloud bearer token. After Cloud auth,
+complete the Notion OAuth flow as described in
+[`docs/agent-workspace-golden-path.md`](../../../docs/agent-workspace-golden-path.md).
+
+---
+
+## Low-Level Client Example
 
 ```ts
 import { RelayFileClient } from "@relayfile/sdk";

package/dist/cloud-login.d.ts

@@ -0,0 +1,27 @@
+import type { AccessTokenProvider } from "./client.js";
+import type { RelayfileSetupOptions } from "./setup-types.js";
+export interface RelayfileCloudTokenSet {
+    apiUrl?: string;
+    accessToken: string;
+    refreshToken: string;
+    accessTokenExpiresAt: string;
+    refreshTokenExpiresAt?: string;
+}
+export interface RelayfileCloudTokenSetupOptions extends Omit<RelayfileSetupOptions, "accessToken" | "cloudApiUrl"> {
+    cloudApiUrl?: string;
+    refreshWindowMs?: number;
+    onTokens?: (tokens: RelayfileCloudTokenSet) => void | Promise<void>;
+}
+export interface RelayfileCloudLoginOptions extends RelayfileCloudTokenSetupOptions {
+    redirectHost?: string;
+    redirectPort?: number;
+    redirectPath?: string;
+    timeoutMs?: number;
+    state?: string;
+    signal?: AbortSignal;
+    openBrowser?: boolean;
+    onLoginUrl?: (url: string) => void | Promise<void>;
+    successMessage?: string;
+}
+export declare function runRelayfileCloudLogin(options?: RelayfileCloudLoginOptions): Promise<RelayfileCloudTokenSet>;
+export declare function createRelayfileCloudAccessTokenProvider(initialTokens: RelayfileCloudTokenSet, options?: RelayfileCloudTokenSetupOptions): AccessTokenProvider;

package/dist/cloud-login.js

@@ -0,0 +1,290 @@
+import { CloudAbortError, CloudApiError, CloudTimeoutError, MalformedCloudResponseError } from "./setup-errors.js";
+import { RELAYFILE_SDK_VERSION } from "./version.js";
+const DEFAULT_CLOUD_API_URL = "https://agentrelay.com/cloud";
+const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_REDIRECT_HOST = "127.0.0.1";
+const DEFAULT_REDIRECT_PATH = "/callback";
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_REFRESH_WINDOW_MS = 60_000;
+export async function runRelayfileCloudLogin(options = {}) {
+    const cloudApiUrl = normalizeNonEmptyString(options.cloudApiUrl) ?? DEFAULT_CLOUD_API_URL;
+    const redirectHost = normalizeNonEmptyString(options.redirectHost) ?? DEFAULT_REDIRECT_HOST;
+    const redirectPort = Math.max(0, Math.floor(options.redirectPort ?? 0));
+    const redirectPath = normalizeRedirectPath(options.redirectPath);
+    const timeoutMs = Math.max(1, Math.floor(options.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS));
+    const state = normalizeNonEmptyString(options.state) ?? await createRandomState();
+    const http = await import("node:http");
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let loginUrlSent = false;
+        let timer;
+        const server = http.createServer((request, response) => {
+            if (!request.url) {
+                response.writeHead(400, { "content-type": "text/plain" });
+                response.end("Missing callback URL");
+                return;
+            }
+            const callbackUrl = new URL(request.url, `http://${redirectHost}:${readServerPort(server, redirectPort)}`);
+            if (callbackUrl.pathname !== redirectPath) {
+                response.writeHead(404, { "content-type": "text/plain" });
+                response.end("Not found");
+                return;
+            }
+            const error = callbackUrl.searchParams.get("error");
+            if (error) {
+                response.writeHead(400, { "content-type": "text/plain" });
+                response.end("Relayfile Cloud login failed");
+                finish(reject, new Error(`Relayfile Cloud login failed: ${error}`));
+                return;
+            }
+            const returnedState = callbackUrl.searchParams.get("state");
+            if (returnedState !== state) {
+                response.writeHead(400, { "content-type": "text/plain" });
+                response.end("Relayfile Cloud login state mismatch");
+                finish(reject, new Error("Relayfile Cloud login state mismatch"));
+                return;
+            }
+            let tokens;
+            try {
+                tokens = readTokenSetFromSearchParams(callbackUrl.searchParams, cloudApiUrl);
+            }
+            catch (error) {
+                response.writeHead(400, { "content-type": "text/plain" });
+                response.end("Relayfile Cloud login callback was missing token fields");
+                finish(reject, error);
+                return;
+            }
+            response.writeHead(200, { "content-type": "text/plain" });
+            response.end(options.successMessage ?? "Relayfile Cloud login complete. You can close this tab.");
+            finish(resolve, tokens);
+        });
+        const abort = () => {
+            finish(reject, new CloudAbortError("cloudLogin"));
+        };
+        const finish = (settle, value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            options.signal?.removeEventListener("abort", abort);
+            server.close();
+            settle(value);
+        };
+        if (options.signal?.aborted) {
+            finish(reject, new CloudAbortError("cloudLogin"));
+            return;
+        }
+        timer = setTimeout(() => {
+            finish(reject, new CloudTimeoutError("cloudLogin", timeoutMs));
+        }, timeoutMs);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        server.once("error", (error) => {
+            finish(reject, error);
+        });
+        server.listen(redirectPort, redirectHost, () => {
+            const port = readServerPort(server, redirectPort);
+            const redirectUri = `http://${redirectHost}:${port}${redirectPath}`;
+            const loginUrl = buildCloudUrl(cloudApiUrl, "api/v1/cli/login");
+            loginUrl.searchParams.set("redirect_uri", redirectUri);
+            loginUrl.searchParams.set("state", state);
+            Promise.resolve(deliverLoginUrl(loginUrl.toString(), options.onLoginUrl))
+                .then(async () => {
+                loginUrlSent = true;
+                if (options.openBrowser) {
+                    await openBrowser(loginUrl.toString());
+                }
+            })
+                .catch((error) => {
+                finish(reject, error);
+            });
+        });
+        server.once("close", () => {
+            if (!settled && !loginUrlSent) {
+                finish(reject, new Error("Relayfile Cloud login server closed before login URL was delivered"));
+            }
+        });
+    });
+}
+export function createRelayfileCloudAccessTokenProvider(initialTokens, options = {}) {
+    const cloudApiUrl = normalizeNonEmptyString(options.cloudApiUrl) ??
+        normalizeNonEmptyString(initialTokens.apiUrl) ??
+        DEFAULT_CLOUD_API_URL;
+    const requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS));
+    const refreshWindowMs = Math.max(0, Math.floor(options.refreshWindowMs ?? DEFAULT_REFRESH_WINDOW_MS));
+    let tokens = {
+        ...initialTokens,
+        apiUrl: normalizeNonEmptyString(initialTokens.apiUrl) ?? cloudApiUrl
+    };
+    let refreshPromise;
+    return async () => {
+        if (shouldRefresh(tokens, refreshWindowMs)) {
+            if (!refreshPromise) {
+                refreshPromise = refresh();
+            }
+            try {
+                await refreshPromise;
+            }
+            finally {
+                refreshPromise = undefined;
+            }
+        }
+        return tokens.accessToken;
+    };
+    async function refresh() {
+        const response = await fetchWithTimeout(buildCloudUrl(cloudApiUrl, "api/v1/auth/token/refresh").toString(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Relayfile-SDK-Version": RELAYFILE_SDK_VERSION
+            },
+            body: JSON.stringify({ refreshToken: tokens.refreshToken })
+        }, requestTimeoutMs);
+        const payload = await readResponseBody(response);
+        if (!response.ok) {
+            throw new CloudApiError(response.status, payload);
+        }
+        tokens = readTokenSetFromPayload(payload, cloudApiUrl);
+        await options.onTokens?.({ ...tokens });
+    }
+}
+function shouldRefresh(tokens, refreshWindowMs) {
+    const expiresAt = Date.parse(tokens.accessTokenExpiresAt);
+    if (Number.isNaN(expiresAt)) {
+        return true;
+    }
+    return expiresAt - Date.now() <= refreshWindowMs;
+}
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw new CloudTimeoutError("refreshCloudAccessToken", timeoutMs);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function readTokenSetFromSearchParams(params, fallbackApiUrl) {
+    return {
+        apiUrl: normalizeNonEmptyString(params.get("api_url") ?? undefined) ?? fallbackApiUrl,
+        accessToken: requireSearchParam(params, "access_token"),
+        refreshToken: requireSearchParam(params, "refresh_token"),
+        accessTokenExpiresAt: requireSearchParam(params, "access_token_expires_at"),
+        refreshTokenExpiresAt: normalizeNonEmptyString(params.get("refresh_token_expires_at") ?? undefined)
+    };
+}
+function readTokenSetFromPayload(payload, fallbackApiUrl) {
+    return {
+        apiUrl: readOptionalStringField(payload, "apiUrl") ?? fallbackApiUrl,
+        accessToken: requireStringField(payload, "accessToken"),
+        refreshToken: requireStringField(payload, "refreshToken"),
+        accessTokenExpiresAt: requireStringField(payload, "accessTokenExpiresAt"),
+        refreshTokenExpiresAt: readOptionalStringField(payload, "refreshTokenExpiresAt")
+    };
+}
+function requireSearchParam(params, field) {
+    const value = normalizeNonEmptyString(params.get(field) ?? undefined);
+    if (!value) {
+        throw new MalformedCloudResponseError(field, Object.fromEntries(params));
+    }
+    return value;
+}
+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 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 readField(payload, field) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return undefined;
+    }
+    return payload[field];
+}
+function buildCloudUrl(baseUrl, path) {
+    const base = new URL(baseUrl);
+    if (!base.pathname.endsWith("/")) {
+        base.pathname = `${base.pathname}/`;
+    }
+    return new URL(path.replace(/^\/+/, ""), base);
+}
+function normalizeRedirectPath(path) {
+    const normalized = normalizeNonEmptyString(path) ?? DEFAULT_REDIRECT_PATH;
+    return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}
+function normalizeNonEmptyString(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}
+async function createRandomState() {
+    const crypto = await import("node:crypto");
+    return crypto.randomBytes(24).toString("base64url");
+}
+function readServerPort(server, fallback) {
+    const address = server.address();
+    return typeof address === "object" && address !== null ? address.port : fallback;
+}
+async function openBrowser(url) {
+    const childProcess = await import("node:child_process");
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32"
+        ? ["/c", "start", "", url]
+        : [url];
+    await new Promise((resolve) => {
+        const child = childProcess.spawn(command, args, {
+            detached: true,
+            stdio: "ignore"
+        });
+        child.once("error", () => resolve());
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+function deliverLoginUrl(url, onLoginUrl) {
+    if (onLoginUrl) {
+        return onLoginUrl(url);
+    }
+    console.log(`Sign in to Relayfile Cloud: ${url}`);
+}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
+export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
+export { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
+export { WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, 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, RELAYFILE_SDK_VERSION, 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/mount-harness.d.ts

@@ -0,0 +1,52 @@
+import { RelayFileClient } from "./client.js";
+export interface RelayfileMountHarnessConfig {
+    baseUrl: string;
+    token: string;
+    workspaceId: string;
+    remotePath: string;
+    localDir: string;
+    mode: "poll" | "fuse";
+}
+export interface RelayfileMountHarnessOptions {
+    env?: NodeJS.ProcessEnv | Record<string, string>;
+    pollIntervalMs?: number;
+    scopes?: string[];
+    onEvent?: (event: RelayfileMountHarnessEvent) => void;
+    client?: RelayFileClient;
+}
+export type RelayfileMountHarnessEvent = {
+    type: "started";
+    localDir: string;
+    remotePath: string;
+    workspaceId: string;
+} | {
+    type: "sync.completed";
+    localDir: string;
+    remotePath: string;
+    files: number;
+    directories: number;
+} | {
+    type: "permission.denied";
+    path: string;
+    scopes: string[];
+} | {
+    type: "stopped";
+    localDir: string;
+    remotePath: string;
+};
+export interface RelayfileMountHarnessHandle {
+    readonly config: RelayfileMountHarnessConfig;
+    readonly localDir: string;
+    syncOnce(): Promise<void>;
+    writeLocalFile(relativePath: string, content: string): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class MountHarnessPermissionError extends Error {
+    readonly code = "permission_denied";
+    readonly path: string;
+    readonly scopes: string[];
+    constructor(targetPath: string, scopes: string[]);
+}
+export declare function readMountHarnessConfig(env?: NodeJS.ProcessEnv | Record<string, string>): RelayfileMountHarnessConfig;
+export declare function startMountHarness(options?: RelayfileMountHarnessOptions): Promise<RelayfileMountHarnessHandle>;
+export declare function runMountHarnessCli(argv?: string[], env?: NodeJS.ProcessEnv | Record<string, string>): Promise<void>;