@relayfile/sdk 0.10.1 → 0.10.3

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-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 DeleteWebhookOptions, 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 GetWebhookDeadLettersOptions, type ListWebhooksOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type ResourceAtEventResult, type ReadFileInput, type QueryFilesOptions, type RegisterWebhookInput, type RegisterWebhookResponse, type RelayFileReadCacheOptions, type Subscription, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type WebhookDeliveryDeadLetterFeedResponse, type WebhookSubscription, type AckWritebackInput, type AckWritebackResponse, type SweepWritebackDraftsInput, type SweepWritebackDraftsResponse, type ChangeEvent, type ChangeLogQueryResult, type ChangeStreamConnection, type ChangeStreamConnectionOptions, type SubscribeOptions } 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 DeleteWebhookOptions, 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 GetWebhookDeadLettersOptions, type ListWebhooksOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type ResourceAtEventResult, type ReadFileInput, type QueryFilesOptions, type RegisterWebhookInput, type RegisterWebhookResponse, type RelayFileReadCacheOptions, type Subscription, type SyncIngressStatusResponse, type SyncProviderStatus, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type WebhookDeliveryDeadLetterFeedResponse, type WebhookSubscription, type AckWritebackInput, type AckWritebackResponse, type SweepWritebackDraftsInput, type SweepWritebackDraftsResponse, type ChangeEvent, type ChangeLogQueryResult, type ChangeStreamConnection, type ChangeStreamConnectionOptions, type SubscribeOptions, type WaitForDataOptions } from "./types.js";
 import type { ForkHandle } from "@relayfile/core";
 /**
  * Bearer token or token factory used for Relayfile API requests.
@@ -124,6 +124,18 @@ export declare class RelayFileClient {
     getAdminIngressStatus(optionsOrCorrelationId?: GetAdminIngressStatusOptions | string, signal?: AbortSignal): Promise<AdminIngressStatusResponse>;
     getAdminSyncStatus(optionsOrCorrelationId?: GetAdminSyncStatusOptions | string, signal?: AbortSignal): Promise<AdminSyncStatusResponse>;
     getSyncStatus(workspaceId: string, options?: GetSyncStatusOptions): Promise<SyncStatusResponse>;
+    /**
+     * Wait until a provider is safe to read from the data plane.
+     *
+     * Cloud-managed syncs report first-sync completion through `ready: true` or
+     * `status: "ready"`. OSS self-host `/sync/status` uses `healthy` for provider
+     * health, including empty freshly filtered provider rows, so this method only
+     * treats OSS `healthy` as data-ready after processed-ingest progress appears
+     * on the status row (`cursor` or `watermarkTs`). For custom OSS ingest flows,
+     * gate on your own ingest completion when you need stronger domain-specific
+     * proof than provider progress.
+     */
+    waitForData(workspaceId: string, provider: string, options?: WaitForDataOptions): Promise<SyncProviderStatus>;
     getSyncIngressStatus(workspaceId: string, options?: GetSyncIngressStatusOptions): Promise<SyncIngressStatusResponse>;
     getSyncDeadLetters(workspaceId: string, options?: GetSyncDeadLettersOptions): Promise<DeadLetterFeedResponse>;
     getSyncDeadLetter(workspaceId: string, envelopeId: string, correlationId?: string, signal?: AbortSignal): Promise<DeadLetterItem>;

package/dist/client.js

@@ -186,6 +186,32 @@ function normalizeErrorDetails(data, explicitDetails) {
     }
     return Object.keys(details).length > 0 ? details : undefined;
 }
+function normalizeProviderId(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+        throw new Error("provider is required.");
+    }
+    return normalized;
+}
+function normalizeProviderIdOrNull(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized || null;
+}
+function normalizePositiveInteger(value, field) {
+    const normalized = Math.floor(value);
+    if (!Number.isFinite(normalized) || normalized <= 0) {
+        throw new Error(`${field} must be a positive integer.`);
+    }
+    return normalized;
+}
+function providerDataReady(status) {
+    return (status.ready === true ||
+        status.status === "ready" ||
+        (status.status === "healthy" && providerHasProgress(status)));
+}
+function providerHasProgress(status) {
+    return Boolean(status.cursor || status.watermarkTs);
+}
 class RelayFileWebSocketConnection {
     socket;
     handlers = {
@@ -1585,6 +1611,44 @@ export class RelayFileClient {
             signal: options.signal
         });
     }
+    /**
+     * Wait until a provider is safe to read from the data plane.
+     *
+     * Cloud-managed syncs report first-sync completion through `ready: true` or
+     * `status: "ready"`. OSS self-host `/sync/status` uses `healthy` for provider
+     * health, including empty freshly filtered provider rows, so this method only
+     * treats OSS `healthy` as data-ready after processed-ingest progress appears
+     * on the status row (`cursor` or `watermarkTs`). For custom OSS ingest flows,
+     * gate on your own ingest completion when you need stronger domain-specific
+     * proof than provider progress.
+     */
+    async waitForData(workspaceId, provider, options = {}) {
+        const providerKey = normalizeProviderId(provider);
+        const pollIntervalMs = normalizePositiveInteger(options.pollIntervalMs ?? 1_000, "pollIntervalMs");
+        const timeoutMs = normalizePositiveInteger(options.timeoutMs ?? 5 * 60_000, "timeoutMs");
+        const startedAt = Date.now();
+        for (;;) {
+            if (options.signal?.aborted) {
+                throw createAbortError();
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs >= timeoutMs) {
+                throw new Error(`Timed out waiting for ${providerKey} data after ${elapsedMs}ms.`);
+            }
+            const status = await this.getSyncStatus(workspaceId, {
+                provider: providerKey,
+                correlationId: options.correlationId,
+                signal: options.signal
+            });
+            const providerStatus = status.providers.find((entry) => normalizeProviderIdOrNull(entry.provider) === providerKey);
+            options.onPoll?.(elapsedMs, providerStatus);
+            if (providerStatus && providerDataReady(providerStatus)) {
+                return providerStatus;
+            }
+            const remainingMs = Math.max(0, timeoutMs - (Date.now() - startedAt));
+            await this.sleep(Math.min(pollIntervalMs, remainingMs), options.signal);
+        }
+    }
     async getSyncIngressStatus(workspaceId, options = {}) {
         const query = buildQuery({
             provider: options.provider

package/dist/connection.d.ts

@@ -41,3 +41,39 @@ export interface ConnectionProvider {
     getConnection?(connectionId: string): Promise<Record<string, unknown>>;
     listConnections?(): Promise<Array<Record<string, unknown>>>;
 }
+/**
+ * Maps a relayfile provider slug (e.g. "github", "linear") to the provider
+ * config key it is registered under in your credential backend (e.g. the Nango
+ * `providerConfigKey`). The relayfile slug is NOT guaranteed to equal the
+ * upstream config key, so self-host callers supply this mapping explicitly.
+ */
+export type ProviderConfigKeyMap = Record<string, string>;
+export interface CreateConnectSessionInput {
+    relayfileProvider: string;
+    providerConfigKey: string;
+    endUserId: string;
+    connectionId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ConnectSession {
+    connectLink: string | null;
+    sessionToken: string | null;
+    expiresAt: string | null;
+    connectionId: string;
+}
+export interface GetConnectConnectionStatusInput {
+    relayfileProvider: string;
+    providerConfigKey: string;
+    connectionId: string;
+}
+export interface ConnectConnectionStatus {
+    connectionId: string;
+    state: string;
+    ready?: boolean;
+    raw?: unknown;
+}
+export interface ConnectCapableProvider extends ConnectionProvider {
+    createConnectSession(input: CreateConnectSessionInput): Promise<ConnectSession>;
+    getConnectionStatus(input: GetConnectConnectionStatusInput): Promise<ConnectConnectionStatus>;
+}
+export declare function supportsConnect(provider: ConnectionProvider): provider is ConnectCapableProvider;

package/dist/connection.js

@@ -3,4 +3,8 @@
  *
  * These types are the contract every provider package must implement.
  */
-export {};
+export function supportsConnect(provider) {
+    const candidate = provider;
+    return (typeof candidate.createConnectSession === "function" &&
+        typeof candidate.getConnectionStatus === "function");
+}

package/dist/index.d.ts

@@ -9,8 +9,11 @@ export { onWrite, pathMatches, type OnWriteClient, type OnWriteHandler, type OnW
 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, AckWritebackDraftDisposition, AckWritebackResponse, AdminIngressAlert, AdminIngressAlertProfile, AdminIngressEffectiveAlertProfile, AdminIngressAlertSeverity, AdminIngressAlertThresholds, AdminIngressAlertTotals, AdminIngressAlertType, AdminIngressStatusResponse, AdminSyncAlert, AdminSyncAlertSeverity, AdminSyncAlertThresholds, AdminSyncAlertTotals, AdminSyncAlertType, AdminSyncStatusResponse, BackendStatusResponse, BulkWriteFile, BulkWriteInput, BulkWriteResponse, ChangeLogQueryResult, ChangeEvent, ChangeEventActor, ChangeEventResource, ChangeEventSummary, ChangeStreamConnection, ChangeStreamConnectionOptions, CommitForkInput, CommitForkResponse, ConflictErrorResponse, CreateForkInput, ContentIdentity, DeleteFileInput, DeleteWebhookOptions, DeadLetterFeedResponse, DeadLetterItem, DigestBullet, DigestContext, DigestHandler, DigestSection, DigestWindow, DiscardForkInput, ErrorResponse, EventSummary, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, FilesystemEventType, EventOrigin, Expansion, ExpansionLevel, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, GetWebhookDeadLettersOptions, IngestWebhookInput, LayoutManifest, LayoutManifestAlias, LayoutManifestResource, ListWebhooksOptions, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, RegisterWebhookInput, RegisterWebhookResponse, ReplayOptions, ResourceAtEventResult, SummaryExpansion, FullExpansion, DiffExpansion, ThreadExpansion, RelayFileJwtClaims, SubscribeOptions, Subscription, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, SweepWritebackDraftsInput, SweepWritebackDraftsResponse, TreeEntry, TreeResponse, WebhookDeliveryDeadLetterFeedResponse, WebhookDeliveryDeadLetterItem, WebhookSubscription, WebhookSubscriptionHealth, WritebackActionType, WritebackDeadLetterError, WritebackDeadLetterErrorCode, WritebackListState, WritebackState, WritebackItem, WritebackItemDetail, WritebackSchemaRef, WriteFileInput, WriteQueuedResponse } from "./types.js";
+export type { ConnectCapableProvider, ConnectConnectionStatus, ConnectSession, ConnectionProvider, CreateConnectSessionInput, GetConnectConnectionStatusInput, NormalizedWebhook, ProviderConfigKeyMap, ProxyHeaders, ProxyMethod, ProxyQuery, ProxyRequest, ProxyResponse, } from "./connection.js";
+export { supportsConnect } from "./connection.js";
+export { SelfHostConnect } from "./self-host-connect.js";
+export type { SelfHostConnectOptions, SelfHostConnectResult, StartSelfHostConnectOptions, WaitForSelfHostConnectionOptions } from "./self-host-connect.js";
+export type { AckResponse, AckWritebackInput, AckWritebackDraftDisposition, AckWritebackResponse, AdminIngressAlert, AdminIngressAlertProfile, AdminIngressEffectiveAlertProfile, AdminIngressAlertSeverity, AdminIngressAlertThresholds, AdminIngressAlertTotals, AdminIngressAlertType, AdminIngressStatusResponse, AdminSyncAlert, AdminSyncAlertSeverity, AdminSyncAlertThresholds, AdminSyncAlertTotals, AdminSyncAlertType, AdminSyncStatusResponse, BackendStatusResponse, BulkWriteFile, BulkWriteInput, BulkWriteResponse, ChangeLogQueryResult, ChangeEvent, ChangeEventActor, ChangeEventResource, ChangeEventSummary, ChangeStreamConnection, ChangeStreamConnectionOptions, CommitForkInput, CommitForkResponse, ConflictErrorResponse, CreateForkInput, ContentIdentity, DeleteFileInput, DeleteWebhookOptions, DeadLetterFeedResponse, DeadLetterItem, DigestBullet, DigestContext, DigestHandler, DigestSection, DigestWindow, DiscardForkInput, ErrorResponse, EventSummary, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, FilesystemEventType, EventOrigin, Expansion, ExpansionLevel, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, WaitForDataOptions, GetWebhookDeadLettersOptions, IngestWebhookInput, LayoutManifest, LayoutManifestAlias, LayoutManifestResource, ListWebhooksOptions, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, RegisterWebhookInput, RegisterWebhookResponse, ReplayOptions, ResourceAtEventResult, SummaryExpansion, FullExpansion, DiffExpansion, ThreadExpansion, RelayFileJwtClaims, SubscribeOptions, Subscription, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, SweepWritebackDraftsInput, SweepWritebackDraftsResponse, TreeEntry, TreeResponse, WebhookDeliveryDeadLetterFeedResponse, WebhookDeliveryDeadLetterItem, WebhookSubscription, WebhookSubscriptionHealth, WritebackActionType, WritebackDeadLetterError, WritebackDeadLetterErrorCode, WritebackListState, WritebackState, WritebackItem, WritebackItemDetail, WritebackSchemaRef, WriteFileInput, WriteQueuedResponse } from "./types.js";
 export type { ForkHandle, ForkOptions } from "@relayfile/core";
 export type { WriteEvent, WriteEventActor, WriteEventOperation, WriteEventSource } from "@relayfile/core";
 export { WritebackConsumer } from "./writeback-consumer.js";

package/dist/index.js

@@ -7,6 +7,8 @@ export { onWrite, pathMatches } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 // Integration providers
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";
+export { supportsConnect } from "./connection.js";
+export { SelfHostConnect } from "./self-host-connect.js";
 export { WritebackConsumer } from "./writeback-consumer.js";
 export * from "./integration-adapter.js";
 // Agent workspace provisioning helpers (`seedWorkspace`, `seedAclRules`,

package/dist/self-host-connect.d.ts

@@ -0,0 +1,38 @@
+import type { ConnectConnectionStatus, ConnectionProvider, ProviderConfigKeyMap } from "./connection.js";
+export interface SelfHostConnectOptions {
+    provider: ConnectionProvider;
+    providerConfigKeys: ProviderConfigKeyMap;
+    defaultPollIntervalMs?: number;
+    defaultTimeoutMs?: number;
+}
+export interface StartSelfHostConnectOptions {
+    endUserId: string;
+    connectionId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SelfHostConnectResult {
+    relayfileProvider: string;
+    providerConfigKey: string;
+    connectLink: string | null;
+    sessionToken: string | null;
+    expiresAt: string | null;
+    connectionId: string;
+}
+export interface WaitForSelfHostConnectionOptions {
+    connectionId: string;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onPoll?: (elapsedMs: number, status?: ConnectConnectionStatus) => void;
+}
+export declare class SelfHostConnect {
+    private readonly provider;
+    private readonly providerConfigKeys;
+    private readonly defaultPollIntervalMs;
+    private readonly defaultTimeoutMs;
+    constructor(options: SelfHostConnectOptions);
+    startConnect(relayfileProvider: string, options: StartSelfHostConnectOptions): Promise<SelfHostConnectResult>;
+    waitForConnection(relayfileProvider: string, options: WaitForSelfHostConnectionOptions): Promise<ConnectConnectionStatus>;
+    private resolveProviderConfigKey;
+    private requireConnectProvider;
+}

package/dist/self-host-connect.js

@@ -0,0 +1,141 @@
+import { supportsConnect } from "./connection.js";
+const DEFAULT_WAIT_INTERVAL_MS = 2_000;
+const DEFAULT_WAIT_TIMEOUT_MS = 5 * 60_000;
+const AUTH_READY_STATE = "oauth_connected";
+export class SelfHostConnect {
+    provider;
+    providerConfigKeys;
+    defaultPollIntervalMs;
+    defaultTimeoutMs;
+    constructor(options) {
+        this.provider = options.provider;
+        this.providerConfigKeys = { ...options.providerConfigKeys };
+        this.defaultPollIntervalMs = normalizePositiveInteger(options.defaultPollIntervalMs, DEFAULT_WAIT_INTERVAL_MS);
+        this.defaultTimeoutMs = normalizePositiveInteger(options.defaultTimeoutMs, DEFAULT_WAIT_TIMEOUT_MS);
+    }
+    async startConnect(relayfileProvider, options) {
+        const normalizedProvider = normalizeRelayfileProvider(relayfileProvider);
+        const providerConfigKey = this.resolveProviderConfigKey(normalizedProvider);
+        const connectProvider = this.requireConnectProvider();
+        const endUserId = options.endUserId?.trim();
+        if (!endUserId) {
+            throw new Error("endUserId is required to start a self-host connect session");
+        }
+        const input = {
+            relayfileProvider: normalizedProvider,
+            providerConfigKey,
+            endUserId
+        };
+        const connectionId = options.connectionId?.trim();
+        if (connectionId) {
+            input.connectionId = connectionId;
+        }
+        if (options.metadata) {
+            input.metadata = { ...options.metadata };
+        }
+        const session = await connectProvider.createConnectSession(input);
+        return {
+            relayfileProvider: normalizedProvider,
+            providerConfigKey,
+            connectLink: session.connectLink,
+            sessionToken: session.sessionToken,
+            expiresAt: session.expiresAt,
+            connectionId: session.connectionId
+        };
+    }
+    async waitForConnection(relayfileProvider, options) {
+        const normalizedProvider = normalizeRelayfileProvider(relayfileProvider);
+        const providerConfigKey = this.resolveProviderConfigKey(normalizedProvider);
+        const connectProvider = this.requireConnectProvider();
+        const connectionId = options.connectionId?.trim();
+        if (!connectionId) {
+            throw new Error("connectionId is required to wait for a self-host connection");
+        }
+        const pollIntervalMs = normalizeNonNegativeInteger(options.pollIntervalMs, this.defaultPollIntervalMs);
+        const timeoutMs = normalizePositiveInteger(options.timeoutMs, this.defaultTimeoutMs);
+        const startedAt = Date.now();
+        for (;;) {
+            throwIfAborted(options.signal);
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs >= timeoutMs) {
+                throw new Error(`Timed out waiting for ${normalizedProvider} connection "${connectionId}" after ${elapsedMs}ms.`);
+            }
+            const status = await connectProvider.getConnectionStatus({
+                relayfileProvider: normalizedProvider,
+                providerConfigKey,
+                connectionId
+            });
+            options.onPoll?.(Date.now() - startedAt, status);
+            if (isAuthReady(status)) {
+                return status;
+            }
+            const sleepMs = Math.min(pollIntervalMs, Math.max(0, timeoutMs - (Date.now() - startedAt)));
+            await sleep(sleepMs, options.signal);
+        }
+    }
+    resolveProviderConfigKey(relayfileProvider) {
+        const providerConfigKey = this.providerConfigKeys[relayfileProvider]?.trim();
+        if (!providerConfigKey) {
+            throw new Error(`No providerConfigKey mapping configured for relayfile provider "${relayfileProvider}".`);
+        }
+        return providerConfigKey;
+    }
+    requireConnectProvider() {
+        if (!supportsConnect(this.provider)) {
+            throw new Error(`Provider "${this.provider.name}" does not support self-host Connect.`);
+        }
+        return this.provider;
+    }
+}
+function isAuthReady(status) {
+    return status.state === AUTH_READY_STATE || status.ready === true;
+}
+function normalizeRelayfileProvider(provider) {
+    const normalized = provider?.trim();
+    if (!normalized) {
+        throw new Error("relayfileProvider is required");
+    }
+    return normalized;
+}
+function normalizePositiveInteger(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    return Math.max(1, Math.floor(value));
+}
+function normalizeNonNegativeInteger(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    return Math.max(0, Math.floor(value));
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw createAbortError();
+    }
+}
+function sleep(ms, signal) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    if (signal?.aborted) {
+        return Promise.reject(createAbortError());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener("abort", onAbort);
+            reject(createAbortError());
+        };
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function createAbortError() {
+    const error = new Error("Aborted while waiting for self-host connection.");
+    error.name = "AbortError";
+    return error;
+}

package/dist/types.d.ts

@@ -357,10 +357,11 @@ export interface SyncRefreshRequest {
     provider: string;
     reason?: string;
 }
-export type SyncProviderStatusState = "healthy" | "lagging" | "error" | "paused";
+export type SyncProviderStatusState = "connected" | "oauth_connected" | "sync_queued" | "syncing" | "ready" | "healthy" | "lagging" | "error" | "paused";
 export interface SyncProviderStatus {
     provider: string;
     status: SyncProviderStatusState;
+    ready?: boolean;
     cursor?: string | null;
     watermarkTs?: string | null;
     lagSeconds?: number;
@@ -534,6 +535,11 @@ export interface GetSyncStatusOptions {
     correlationId?: string;
     signal?: AbortSignal;
 }
+export interface WaitForDataOptions extends GetSyncStatusOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    onPoll?: (elapsedMs: number, status?: SyncProviderStatus) => void;
+}
 export interface GetSyncIngressStatusOptions {
     provider?: string;
     correlationId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,15 +59,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.10.1",
+    "@relayfile/core": "0.10.3",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
   "optionalDependencies": {
-    "@relayfile/mount-darwin-arm64": "0.10.1",
-    "@relayfile/mount-darwin-x64": "0.10.1",
-    "@relayfile/mount-linux-arm64": "0.10.1",
-    "@relayfile/mount-linux-x64": "0.10.1"
+    "@relayfile/mount-darwin-arm64": "0.10.3",
+    "@relayfile/mount-darwin-x64": "0.10.3",
+    "@relayfile/mount-linux-arm64": "0.10.3",
+    "@relayfile/mount-linux-x64": "0.10.3"
   },
   "devDependencies": {
     "typescript": "^5.7.3",