@relayfile/sdk 0.7.9 → 0.7.11

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type RelayFileChangeLogOptions, 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, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
@@ -10,7 +10,7 @@ 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, 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 { AckResponse, AckWritebackInput, 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, DeadLetterFeedResponse, DeadLetterItem, DiscardForkInput, ErrorResponse, EventSummary, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, FilesystemEventType, EventOrigin, Expansion, ExpansionLevel, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, IngestWebhookInput, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, ReplayOptions, ResourceAtEventResult, SummaryExpansion, FullExpansion, DiffExpansion, ThreadExpansion, RelayFileJwtClaims, SubscribeOptions, Subscription, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackState, WritebackItem, 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/setup.d.ts

@@ -102,6 +102,63 @@ export declare class WorkspaceHandle {
         connectionId: string;
         replacedConnectionId?: string;
     }>;
+    /**
+     * List the upstream resources the current connection's OAuth grant
+     * covers. Today only Atlassian-family providers (`jira`, `confluence`)
+     * have meaningful entries here — every Atlassian OAuth grant can cover
+     * multiple sites (cloudIds), and the operator needs to bind one of them
+     * to this workspace via {@link setIntegrationMetadata} before sync can
+     * run.
+     *
+     * Cloud returns 400 `provider_has_no_accessible_resources` for providers
+     * that don't model this concept (currently everything non-Atlassian);
+     * that error surfaces here as a `CloudApiError` so callers can handle
+     * it explicitly rather than treating an empty list as ambiguous.
+     *
+     * @example
+     * ```ts
+     * const sites = await workspace.listAccessibleResources("jira")
+     * if (sites.length > 1) {
+     *   const choice = await promptOperator(sites)
+     *   await workspace.setIntegrationMetadata("jira", {
+     *     cloudId: choice.id,
+     *     baseUrl: choice.url
+     *   })
+     * }
+     * ```
+     */
+    listAccessibleResources(provider: WorkspaceIntegrationProvider | string): Promise<Array<{
+        id: string;
+        url: string;
+        name?: string;
+        scopes?: string[];
+        avatarUrl?: string;
+    }>>;
+    /**
+     * Set the operator-controlled metadata namespace on the workspace's
+     * connection for `provider`. The cloud route forwards the payload to
+     * Nango's `setMetadata` (full-replacement, not merge), so the value
+     * passed here becomes the connection's metadata wholesale. Callers that
+     * want merge semantics should read existing metadata first.
+     *
+     * This is the second half of the post-OAuth picker flow for Jira /
+     * Confluence (see {@link listAccessibleResources}), but is intentionally
+     * general-purpose — any provider whose sync requires operator-supplied
+     * connection-level config (e.g. a non-default API host) can use this.
+     *
+     * The cloud side rejects top-level keys that look like Nango plumbing
+     * (`_*`, `connection_*`, `auth_*`, `provider_config_key`, `connection_id`)
+     * with `code: "invalid_metadata"` so a typo can't clobber the connection.
+     *
+     * @example
+     * ```ts
+     * await workspace.setIntegrationMetadata("jira", {
+     *   cloudId: "abc-123",
+     *   baseUrl: "https://foo.atlassian.net"
+     * })
+     * ```
+     */
+    setIntegrationMetadata(provider: WorkspaceIntegrationProvider | string, metadata: Record<string, unknown>): Promise<Record<string, unknown>>;
     getToken(): string;
     requestJson(options: Omit<CloudRequestOptions, "tokenProvider">): Promise<unknown>;
     mountEnv(options?: WorkspaceMountEnvOptions): WorkspaceMountEnv;

package/dist/setup.js

@@ -440,6 +440,95 @@ export class WorkspaceHandle {
             ? { connectionId: boundConnectionId, replacedConnectionId }
             : { connectionId: boundConnectionId };
     }
+    /**
+     * List the upstream resources the current connection's OAuth grant
+     * covers. Today only Atlassian-family providers (`jira`, `confluence`)
+     * have meaningful entries here — every Atlassian OAuth grant can cover
+     * multiple sites (cloudIds), and the operator needs to bind one of them
+     * to this workspace via {@link setIntegrationMetadata} before sync can
+     * run.
+     *
+     * Cloud returns 400 `provider_has_no_accessible_resources` for providers
+     * that don't model this concept (currently everything non-Atlassian);
+     * that error surfaces here as a `CloudApiError` so callers can handle
+     * it explicitly rather than treating an empty list as ambiguous.
+     *
+     * @example
+     * ```ts
+     * const sites = await workspace.listAccessibleResources("jira")
+     * if (sites.length > 1) {
+     *   const choice = await promptOperator(sites)
+     *   await workspace.setIntegrationMetadata("jira", {
+     *     cloudId: choice.id,
+     *     baseUrl: choice.url
+     *   })
+     * }
+     * ```
+     */
+    async listAccessibleResources(provider) {
+        const normalized = normalizeProviderId(provider);
+        const response = (await this._setup.requestJson({
+            operation: "listAccessibleResources",
+            method: "GET",
+            path: `api/v1/workspaces/${encodeURIComponent(this.workspaceId)}/integrations/${encodeURIComponent(normalized)}/accessible-resources`,
+            tokenProvider: async () => this.getOrRefreshToken()
+        }));
+        if (!response || !Array.isArray(response.resources)) {
+            return [];
+        }
+        return response.resources
+            .filter((entry) => {
+            if (!entry || typeof entry !== "object")
+                return false;
+            const record = entry;
+            return (typeof record.id === "string" &&
+                record.id.length > 0 &&
+                typeof record.url === "string" &&
+                record.url.length > 0);
+        })
+            .map((entry) => ({ ...entry }));
+    }
+    /**
+     * Set the operator-controlled metadata namespace on the workspace's
+     * connection for `provider`. The cloud route forwards the payload to
+     * Nango's `setMetadata` (full-replacement, not merge), so the value
+     * passed here becomes the connection's metadata wholesale. Callers that
+     * want merge semantics should read existing metadata first.
+     *
+     * This is the second half of the post-OAuth picker flow for Jira /
+     * Confluence (see {@link listAccessibleResources}), but is intentionally
+     * general-purpose — any provider whose sync requires operator-supplied
+     * connection-level config (e.g. a non-default API host) can use this.
+     *
+     * The cloud side rejects top-level keys that look like Nango plumbing
+     * (`_*`, `connection_*`, `auth_*`, `provider_config_key`, `connection_id`)
+     * with `code: "invalid_metadata"` so a typo can't clobber the connection.
+     *
+     * @example
+     * ```ts
+     * await workspace.setIntegrationMetadata("jira", {
+     *   cloudId: "abc-123",
+     *   baseUrl: "https://foo.atlassian.net"
+     * })
+     * ```
+     */
+    async setIntegrationMetadata(provider, metadata) {
+        const normalized = normalizeProviderId(provider);
+        if (!isPlainRecord(metadata)) {
+            throw new Error("metadata must be a plain object");
+        }
+        const response = (await this._setup.requestJson({
+            operation: "setIntegrationMetadata",
+            method: "PUT",
+            path: `api/v1/workspaces/${encodeURIComponent(this.workspaceId)}/integrations/${encodeURIComponent(normalized)}/metadata`,
+            body: { metadata },
+            tokenProvider: async () => this.getOrRefreshToken()
+        }));
+        if (isPlainRecord(response?.metadata)) {
+            return { ...response.metadata };
+        }
+        throw new Error("invalid cloud response: expected metadata to be a plain object");
+    }
     getToken() {
         return this._token;
     }
@@ -644,6 +733,24 @@ class MountedWorkspaceHandleImpl {
         await safeStopLauncher(this.launcherInstance);
     }
 }
+// The metadata + accessible-resources verbs accept `WorkspaceIntegrationProvider | string`
+// so operators can target dynamically-discovered providers (Composio toolkit
+// slugs, future Atlassian-family additions) without an SDK release. We still
+// strip trailing whitespace and lower-case so consumers don't have to.
+function normalizeProviderId(provider) {
+    const trimmed = typeof provider === "string" ? provider.trim() : "";
+    if (!trimmed) {
+        throw new Error("provider is required");
+    }
+    return trimmed.toLowerCase();
+}
+function isPlainRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 function assertProvider(provider) {
     if (!WORKSPACE_INTEGRATION_PROVIDERS.includes(provider)) {
         throw new UnknownProviderError(provider);

package/dist/types.d.ts

@@ -136,6 +136,106 @@ export interface FilesystemEvent {
     correlationId?: string;
     timestamp: string;
 }
+export interface ChangeEventResource {
+    path: string;
+    kind: string;
+    id: string;
+    provider: string;
+}
+export interface ChangeEventActor {
+    id: string;
+    displayName?: string;
+}
+export interface ChangeEventSummary {
+    title?: string;
+    status?: string;
+    priority?: string;
+    labels?: string[];
+    actor?: ChangeEventActor;
+    fieldsChanged?: string[];
+    /** Optional compact tag list. Producers must cap this at 8 entries. */
+    tags?: string[];
+}
+/**
+ * Canonical lightweight event summary shape exported for proactive-runtime
+ * adapters. `buildSummary(payload)` should return this exact structure.
+ */
+export type EventSummary = ChangeEventSummary;
+export type ExpansionLevel = "summary" | "full" | "diff" | "thread";
+export interface SummaryExpansion {
+    level: "summary";
+    path: string;
+    summary: ChangeEventSummary;
+}
+export interface FullExpansion<TData = unknown> {
+    level: "full";
+    path: string;
+    data: TData;
+}
+export interface DiffExpansion {
+    level: "diff";
+    path: string;
+    diff: Record<string, unknown>;
+}
+export interface ThreadExpansion {
+    level: "thread";
+    path: string;
+    thread: Record<string, unknown>;
+}
+export type Expansion<L extends ExpansionLevel = ExpansionLevel> = L extends "summary" ? SummaryExpansion : L extends "full" ? FullExpansion : L extends "diff" ? DiffExpansion : ThreadExpansion;
+/**
+ * Proactive runtime relayfile notification envelope.
+ *
+ * This differs from the lower-level FilesystemEvent feed above. The proactive
+ * runtime consumes a small, stable notification that points at the canonical
+ * payload in VFS instead of inlining provider payloads directly.
+ *
+ * M1 exposes the type so downstream packages can compile against the final
+ * shape before M2 wires live delivery.
+ */
+export interface ChangeEvent {
+    id: string;
+    workspace: string;
+    agentId?: string;
+    type: "relayfile.changed";
+    occurredAt: string;
+    resource: ChangeEventResource;
+    summary: ChangeEventSummary;
+    expand<L extends ExpansionLevel = "summary">(level?: L): Promise<Expansion<L>>;
+    digest?: string;
+}
+export interface SubscribeOptions {
+    coalesce?: "none" | "fire-once";
+    coalesceMs?: number;
+    pathScope?: string[];
+    aclToken?: string;
+    drainMs?: number;
+}
+export interface Subscription {
+    unsubscribe(): Promise<void>;
+}
+export type ReplayOptions = {
+    replayOnStart?: "none";
+} | {
+    replayOnStart: `since:${string}`;
+} | {
+    replayOnStart: `last:${number}`;
+};
+export type ChangeStreamConnectionOptions = ReplayOptions & {
+    workspaceId: string;
+    aclToken?: string;
+};
+export interface ChangeStreamConnection extends Subscription {
+    readonly ready: Promise<void>;
+}
+export interface ResourceAtEventResult {
+    path: string;
+    data: unknown;
+    digest: string;
+}
+export interface ChangeLogQueryResult {
+    events: ChangeEvent[];
+}
 export interface EventFeedResponse {
     events: FilesystemEvent[];
     nextCursor: string | null;

package/package.json

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