@relayfile/sdk 0.1.0 → 0.1.2

package/README.md

@@ -20,10 +20,15 @@ const client = new RelayFileClient({
 
 const workspaceId = "workspace_123";
 
-const tree = await client.listTree(workspaceId, { path: "/", depth: 2 });
+const tree = await client.listTree(workspaceId, {
+  path: "/",
+  depth: 2
+});
+
 console.log(tree.entries.map((entry) => entry.path));
 
 const file = await client.readFile(workspaceId, "/notes/todo.md");
+
 console.log(file.content);
 
 await client.writeFile({
@@ -37,4 +42,4 @@ await client.writeFile({
 
 ## Full Docs
 
-Full documentation is available at https://github.com/AgentWorkforce/relayfile
+Full documentation is available in the [relayfile docs](https://github.com/AgentWorkforce/relayfile/tree/main/docs).

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type EventFeedResponse, type ExportJsonResponse, type ExportOptions, type FileQueryResponse, type FileReadResponse, type FilesystemEvent, type GetEventsOptions, type GetAdminIngressStatusOptions, type GetAdminSyncStatusOptions, type GetOperationsOptions, type GetSyncDeadLettersOptions, type GetSyncIngressStatusOptions, type GetSyncStatusOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type QueryFilesOptions, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse } from "./types.js";
+import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type EventFeedResponse, type ExportJsonResponse, type ExportOptions, type FileQueryResponse, type FileReadResponse, type FilesystemEvent, type GetEventsOptions, type GetAdminIngressStatusOptions, type GetAdminSyncStatusOptions, type GetOperationsOptions, type GetSyncDeadLettersOptions, type GetSyncIngressStatusOptions, type GetSyncStatusOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type QueryFilesOptions, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type AckWritebackInput, type AckWritebackResponse } from "./types.js";
 export type AccessTokenProvider = string | (() => string | Promise<string>);
 export interface RelayFileRetryOptions {
     maxRetries?: number;
@@ -59,6 +59,9 @@ export declare class RelayFileClient {
     replaySyncDeadLetter(workspaceId: string, envelopeId: string, correlationId?: string, signal?: AbortSignal): Promise<QueuedResponse>;
     ackSyncDeadLetter(workspaceId: string, envelopeId: string, correlationId?: string, signal?: AbortSignal): Promise<AckResponse>;
     triggerSyncRefresh(workspaceId: string, provider: string, reason?: string, correlationId?: string, signal?: AbortSignal): Promise<QueuedResponse>;
+    ingestWebhook(input: IngestWebhookInput): Promise<QueuedResponse>;
+    listPendingWritebacks(workspaceId: string, correlationId?: string, signal?: AbortSignal): Promise<WritebackItem[]>;
+    ackWriteback(input: AckWritebackInput): Promise<AckWritebackResponse>;
     private request;
     private performRequest;
     private shouldRetryStatus;
@@ -70,4 +73,3 @@ export declare class RelayFileClient {
     private throwForError;
 }
 export {};
-//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -57,6 +57,15 @@ function createBlobFromResponse(response) {
     }
     return response.arrayBuffer().then((buffer) => new Blob([buffer], { type: response.headers.get("content-type") ?? undefined }));
 }
+function normalizeExportJsonResponse(payload) {
+    if (Array.isArray(payload)) {
+        return { files: payload };
+    }
+    const data = (payload ?? {});
+    return {
+        files: Array.isArray(data.files) ? data.files : []
+    };
+}
 class RelayFileWebSocketConnection {
     socket;
     handlers = {
@@ -92,7 +101,14 @@ class RelayFileWebSocketConnection {
             }
             let parsed;
             try {
-                parsed = JSON.parse(event.data);
+                const raw = JSON.parse(event.data);
+                if (typeof raw !== "object" || raw === null || typeof raw.type !== "string") {
+                    throw new Error("Invalid WebSocket event: missing required 'type' field.");
+                }
+                if (raw.path !== undefined && typeof raw.path !== "string") {
+                    throw new Error("Invalid WebSocket event: 'path' must be a string.");
+                }
+                parsed = raw;
             }
             catch (error) {
                 const parseError = error instanceof Error ? error : new Error("Failed to parse WebSocket event payload.");
@@ -202,7 +218,7 @@ export class RelayFileClient {
         });
     }
     async bulkWrite(input) {
-        return this.request({
+        const response = await this.performRequest({
             method: "POST",
             path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/bulk`,
             correlationId: input.correlationId,
@@ -211,6 +227,7 @@ export class RelayFileClient {
             },
             signal: input.signal
         });
+        return this.readPayload(response);
     }
     async deleteFile(input) {
         const query = buildQuery({ path: input.path });
@@ -249,7 +266,7 @@ export class RelayFileClient {
             accept: format === "json" ? "application/json" : "*/*"
         });
         if (format === "json") {
-            return this.readPayload(response);
+            return normalizeExportJsonResponse(await this.readPayload(response));
         }
         return createBlobFromResponse(response);
     }
@@ -436,9 +453,47 @@ export class RelayFileClient {
             signal
         });
     }
+    async ingestWebhook(input) {
+        return this.request({
+            method: "POST",
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/webhooks/ingest`,
+            correlationId: input.correlationId,
+            body: {
+                provider: input.provider,
+                event_type: input.event_type,
+                path: input.path,
+                data: input.data,
+                delivery_id: input.delivery_id,
+                timestamp: input.timestamp,
+                headers: input.headers
+            },
+            signal: input.signal
+        });
+    }
+    async listPendingWritebacks(workspaceId, correlationId, signal) {
+        return this.request({
+            method: "GET",
+            path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/writeback/pending`,
+            correlationId,
+            signal
+        });
+    }
+    async ackWriteback(input) {
+        return this.request({
+            method: "POST",
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/writeback/${encodeURIComponent(input.itemId)}/ack`,
+            correlationId: input.correlationId,
+            body: {
+                success: input.success,
+                error: input.error
+            },
+            signal: input.signal
+        });
+    }
     async request(params) {
         const response = await this.performRequest(params);
-        return this.readPayload(response);
+        const payload = await this.readPayload(response);
+        return payload;
     }
     async performRequest(params) {
         const correlationId = params.correlationId ?? generateCorrelationId();
@@ -628,4 +683,3 @@ export class RelayFileClient {
         });
     }
 }
-//# sourceMappingURL=client.js.map

package/dist/composio.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Composio integration bridge for Relayfile.
+ *
+ * Maps Composio trigger webhook events → Relayfile filesystem paths + semantics.
+ *
+ * Composio webhook payload format (V3):
+ * {
+ *   "type": "composio.trigger.message",
+ *   "metadata": {
+ *     "trigger_slug": "GITHUB_COMMIT_EVENT",
+ *     "trigger_id": "trig_abc123",
+ *     "connected_account_id": "ca_xyz789",
+ *     "user_id": "user_123",
+ *     "toolkit": "github"
+ *   },
+ *   "data": {
+ *     // trigger-specific payload (e.g., commit author, message, url)
+ *   }
+ * }
+ *
+ * @see https://docs.composio.dev/docs/triggers
+ * @see https://docs.composio.dev/docs/setting-up-triggers/subscribing-to-events
+ */
+import type { QueuedResponse } from "./types.js";
+import { IntegrationProvider, type WebhookInput } from "./provider.js";
+/** Raw webhook payload from Composio (V3 format) */
+export interface ComposioWebhookPayload {
+    type: "composio.trigger.message" | "composio.connected_account.expired";
+    metadata: {
+        trigger_slug: string;
+        trigger_id: string;
+        connected_account_id: string;
+        user_id?: string;
+        toolkit: string;
+    };
+    data: Record<string, unknown>;
+}
+/** Options for creating Composio trigger subscriptions */
+export interface ComposioTriggerOptions {
+    /** Composio API key */
+    apiKey: string;
+    /** Webhook URL to receive events */
+    webhookUrl: string;
+    /** Base URL for Composio API (default: https://backend.composio.dev) */
+    baseUrl?: string;
+}
+export declare class ComposioHelpers extends IntegrationProvider {
+    readonly name = "composio";
+    /**
+     * Ingest a Composio webhook payload into Relayfile.
+     *
+     * @param workspaceId - Relayfile workspace ID
+     * @param rawInput - Raw Composio webhook payload (ComposioWebhookPayload)
+     * @param signal - Optional abort signal
+     */
+    ingestWebhook(workspaceId: string, rawInput: unknown, signal?: AbortSignal): Promise<QueuedResponse>;
+    /**
+     * Normalize a Composio webhook payload to the generic WebhookInput format.
+     * Useful for custom processing pipelines.
+     */
+    normalize(input: ComposioWebhookPayload): WebhookInput;
+    private buildSemanticProperties;
+}

package/dist/composio.js

@@ -0,0 +1,233 @@
+/**
+ * Composio integration bridge for Relayfile.
+ *
+ * Maps Composio trigger webhook events → Relayfile filesystem paths + semantics.
+ *
+ * Composio webhook payload format (V3):
+ * {
+ *   "type": "composio.trigger.message",
+ *   "metadata": {
+ *     "trigger_slug": "GITHUB_COMMIT_EVENT",
+ *     "trigger_id": "trig_abc123",
+ *     "connected_account_id": "ca_xyz789",
+ *     "user_id": "user_123",
+ *     "toolkit": "github"
+ *   },
+ *   "data": {
+ *     // trigger-specific payload (e.g., commit author, message, url)
+ *   }
+ * }
+ *
+ * @see https://docs.composio.dev/docs/triggers
+ * @see https://docs.composio.dev/docs/setting-up-triggers/subscribing-to-events
+ */
+import { IntegrationProvider, computeCanonicalPath, } from "./provider.js";
+// ---------------------------------------------------------------------------
+// Trigger slug → Relayfile object type mapping
+// ---------------------------------------------------------------------------
+/**
+ * Maps Composio trigger slugs to Relayfile object types.
+ * The trigger slug format is usually: {TOOLKIT}_{EVENT_NAME}
+ * e.g., GITHUB_COMMIT_EVENT → "commits", SLACK_NEW_MESSAGE → "messages"
+ */
+const TRIGGER_OBJECT_TYPE = {
+    // GitHub
+    GITHUB_COMMIT_EVENT: "commits",
+    GITHUB_PULL_REQUEST_EVENT: "pull_requests",
+    GITHUB_ISSUE_EVENT: "issues",
+    GITHUB_STAR_EVENT: "stars",
+    GITHUB_PUSH_EVENT: "pushes",
+    // Slack
+    SLACK_NEW_MESSAGE: "messages",
+    SLACK_CHANNEL_CREATED: "channels",
+    SLACK_REACTION_ADDED: "reactions",
+    // Gmail
+    GMAIL_NEW_EMAIL: "emails",
+    // Zendesk
+    ZENDESK_NEW_TICKET: "tickets",
+    ZENDESK_TICKET_UPDATED: "tickets",
+    // Shopify
+    SHOPIFY_NEW_ORDER: "orders",
+    SHOPIFY_ORDER_UPDATED: "orders",
+    // Stripe
+    STRIPE_PAYMENT_RECEIVED: "payments",
+    STRIPE_INVOICE_CREATED: "invoices",
+    // Jira
+    JIRA_ISSUE_CREATED: "issues",
+    JIRA_ISSUE_UPDATED: "issues",
+    // HubSpot
+    HUBSPOT_CONTACT_CREATED: "contacts",
+    HUBSPOT_DEAL_CREATED: "deals",
+    // Notion
+    NOTION_PAGE_UPDATED: "pages",
+    // Linear
+    LINEAR_ISSUE_CREATED: "issues",
+    LINEAR_ISSUE_UPDATED: "issues",
+    // Intercom
+    INTERCOM_NEW_CONVERSATION: "conversations",
+    // Freshdesk
+    FRESHDESK_TICKET_CREATED: "tickets",
+    FRESHDESK_TICKET_UPDATED: "tickets",
+};
+/**
+ * Extract event type (created/updated/deleted) from trigger slug.
+ */
+function extractEventType(triggerSlug) {
+    const slug = triggerSlug.toUpperCase();
+    if (slug.includes("CREATED") || slug.includes("NEW"))
+        return "created";
+    if (slug.includes("UPDATED") || slug.includes("CHANGED"))
+        return "updated";
+    if (slug.includes("DELETED") || slug.includes("REMOVED"))
+        return "deleted";
+    return "event";
+}
+/**
+ * Extract a stable object ID from Composio event data.
+ * Different triggers have different ID fields.
+ */
+function extractObjectId(data) {
+    // Common ID fields across various providers
+    const idFields = ["id", "objectId", "object_id", "ticketId", "issueId", "messageId", "orderId", "commitId"];
+    for (const field of idFields) {
+        const val = data[field];
+        if (typeof val === "string" || typeof val === "number") {
+            return String(val);
+        }
+    }
+    // Nested ID patterns
+    if (typeof data.issue === "object" && data.issue !== null && "id" in data.issue) {
+        return String(data.issue.id);
+    }
+    if (typeof data.pull_request === "object" && data.pull_request !== null && "id" in data.pull_request) {
+        return String(data.pull_request.id);
+    }
+    // Fallback: hash from trigger_id + timestamp
+    return `auto-${Date.now().toString(36)}`;
+}
+/**
+ * Infer the object type from trigger slug when not in the mapping table.
+ * Format: TOOLKIT_OBJECT_EVENT → "objects" (pluralized)
+ */
+function inferObjectType(triggerSlug) {
+    // Remove toolkit prefix and event suffix
+    const parts = triggerSlug.toLowerCase().split("_");
+    if (parts.length >= 3) {
+        // e.g., GITHUB_COMMIT_EVENT → "commit" → "commits"
+        const objectPart = parts.slice(1, -1).join("_");
+        return objectPart.endsWith("s") ? objectPart : `${objectPart}s`;
+    }
+    return "events";
+}
+// ---------------------------------------------------------------------------
+// Composio provider implementation
+// ---------------------------------------------------------------------------
+export class ComposioHelpers extends IntegrationProvider {
+    name = "composio";
+    /**
+     * Ingest a Composio webhook payload into Relayfile.
+     *
+     * @param workspaceId - Relayfile workspace ID
+     * @param rawInput - Raw Composio webhook payload (ComposioWebhookPayload)
+     * @param signal - Optional abort signal
+     */
+    async ingestWebhook(workspaceId, rawInput, signal) {
+        const input = rawInput;
+        if (input.type === "composio.connected_account.expired") {
+            // Handle account expiry as a system event
+            return this.client.ingestWebhook({
+                workspaceId,
+                provider: input.metadata.toolkit || "composio",
+                event_type: "account_expired",
+                path: `/.system/composio/expired/${input.metadata.connected_account_id}.json`,
+                data: {
+                    connected_account_id: input.metadata.connected_account_id,
+                    user_id: input.metadata.user_id,
+                    toolkit: input.metadata.toolkit,
+                    expired_at: new Date().toISOString(),
+                },
+                headers: {},
+                signal,
+            });
+        }
+        const toolkit = input.metadata.toolkit;
+        const triggerSlug = input.metadata.trigger_slug;
+        const objectType = TRIGGER_OBJECT_TYPE[triggerSlug] ?? inferObjectType(triggerSlug);
+        const objectId = extractObjectId(input.data);
+        const eventType = extractEventType(triggerSlug);
+        const path = computeCanonicalPath(toolkit, objectType, objectId);
+        const properties = this.buildSemanticProperties(input);
+        const semantics = {
+            properties,
+            relations: [],
+        };
+        return this.client.ingestWebhook({
+            workspaceId,
+            provider: toolkit,
+            event_type: eventType,
+            path,
+            data: {
+                ...input.data,
+                semantics,
+            },
+            headers: {
+                "X-Composio-Trigger-Id": input.metadata.trigger_id,
+                "X-Composio-Trigger-Slug": triggerSlug,
+                "X-Composio-Connected-Account": input.metadata.connected_account_id,
+                ...(input.metadata.user_id
+                    ? { "X-Composio-User-Id": input.metadata.user_id }
+                    : {}),
+            },
+            signal,
+        });
+    }
+    /**
+     * Normalize a Composio webhook payload to the generic WebhookInput format.
+     * Useful for custom processing pipelines.
+     */
+    normalize(input) {
+        const toolkit = input.metadata.toolkit;
+        const triggerSlug = input.metadata.trigger_slug;
+        return {
+            provider: toolkit,
+            objectType: TRIGGER_OBJECT_TYPE[triggerSlug] ?? inferObjectType(triggerSlug),
+            objectId: extractObjectId(input.data),
+            eventType: extractEventType(triggerSlug),
+            payload: input.data,
+            metadata: {
+                "composio.trigger_id": input.metadata.trigger_id,
+                "composio.trigger_slug": triggerSlug,
+                "composio.connected_account_id": input.metadata.connected_account_id,
+                ...(input.metadata.user_id
+                    ? { "composio.user_id": input.metadata.user_id }
+                    : {}),
+            },
+        };
+    }
+    buildSemanticProperties(input) {
+        const properties = {
+            "composio.trigger_id": input.metadata.trigger_id,
+            "composio.trigger_slug": input.metadata.trigger_slug,
+            "composio.connected_account_id": input.metadata.connected_account_id,
+            provider: input.metadata.toolkit,
+            "provider.object_type": TRIGGER_OBJECT_TYPE[input.metadata.trigger_slug] ??
+                inferObjectType(input.metadata.trigger_slug),
+            "provider.object_id": extractObjectId(input.data),
+        };
+        if (input.metadata.user_id) {
+            properties["composio.user_id"] = input.metadata.user_id;
+        }
+        // Extract common fields from data
+        const data = input.data;
+        if (typeof data.status === "string") {
+            properties["provider.status"] = data.status;
+        }
+        if (typeof data.updated_at === "string") {
+            properties["provider.updated_at"] = data.updated_at;
+        }
+        if (typeof data.created_at === "string") {
+            properties["provider.created_at"] = data.created_at;
+        }
+        return properties;
+    }
+}

package/dist/errors.d.ts

@@ -22,4 +22,3 @@ export declare class InvalidStateError extends RelayFileApiError {
 export declare class PayloadTooLargeError extends RelayFileApiError {
     constructor(status: number, payload?: Partial<ErrorResponse>);
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -44,4 +44,3 @@ export class PayloadTooLargeError extends RelayFileApiError {
         this.name = "PayloadTooLargeError";
     }
 }
-//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -1,4 +1,10 @@
 export { RelayFileClient, type ConnectWebSocketOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.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 type { AckResponse, AdminIngressAlert, AdminIngressAlertProfile, AdminIngressEffectiveAlertProfile, AdminIngressAlertSeverity, AdminIngressAlertThresholds, AdminIngressAlertTotals, AdminIngressAlertType, AdminIngressStatusResponse, AdminSyncAlert, AdminSyncAlertSeverity, AdminSyncAlertThresholds, AdminSyncAlertTotals, AdminSyncAlertType, AdminSyncStatusResponse, BackendStatusResponse, BulkWriteFile, BulkWriteInput, BulkWriteResponse, ConflictErrorResponse, DeleteFileInput, DeadLetterFeedResponse, DeadLetterItem, ErrorResponse, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, ListTreeOptions, OperationFeedResponse, OperationStatusResponse, QueuedResponse, QueryFilesOptions, SyncIngressStatusResponse, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WriteFileInput, WriteQueuedResponse } from "./types.js";
-//# sourceMappingURL=index.d.ts.map
+export { IntegrationProvider, computeCanonicalPath } from "./provider.js";
+export type { WebhookInput, ListProviderFilesOptions, WatchProviderEventsOptions } from "./provider.js";
+export { NangoHelpers } from "./nango.js";
+export type { NangoWebhookInput } from "./nango.js";
+export { ComposioHelpers } from "./composio.js";
+export type { ComposioWebhookPayload, ComposioTriggerOptions } from "./composio.js";
+export type { AckResponse, AckWritebackInput, AckWritebackResponse, AdminIngressAlert, AdminIngressAlertProfile, AdminIngressEffectiveAlertProfile, AdminIngressAlertSeverity, AdminIngressAlertThresholds, AdminIngressAlertTotals, AdminIngressAlertType, AdminIngressStatusResponse, AdminSyncAlert, AdminSyncAlertSeverity, AdminSyncAlertThresholds, AdminSyncAlertTotals, AdminSyncAlertType, AdminSyncStatusResponse, BackendStatusResponse, BulkWriteFile, BulkWriteInput, BulkWriteResponse, ConflictErrorResponse, DeleteFileInput, DeadLetterFeedResponse, DeadLetterItem, ErrorResponse, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, FilesystemEventType, EventOrigin, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, IngestWebhookInput, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackState, WritebackItem, WriteFileInput, WriteQueuedResponse } from "./types.js";

package/dist/index.js

@@ -1,3 +1,9 @@
 export { RelayFileClient } from "./client.js";
+export { RelayFileSync } from "./sync.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
-//# sourceMappingURL=index.js.map
+// Integration providers
+export { IntegrationProvider, computeCanonicalPath } from "./provider.js";
+// Nango bridge
+export { NangoHelpers } from "./nango.js";
+// Composio bridge
+export { ComposioHelpers } from "./composio.js";

package/dist/nango.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Nango integration bridge for Relayfile.
+ *
+ * Maps Nango sync webhook events → Relayfile filesystem paths + semantics.
+ *
+ * @see https://docs.nango.dev/integrate/guides/receive-webhooks-from-nango
+ */
+import type { QueuedResponse } from "./types.js";
+import { IntegrationProvider, type WebhookInput } from "./provider.js";
+export interface NangoWebhookInput {
+    connectionId: string;
+    integrationId: string;
+    providerConfigKey?: string;
+    model: string;
+    objectId: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    relations?: string[];
+}
+export interface GetProviderFilesOptions {
+    provider: string;
+    objectType?: string;
+    status?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+export interface WatchProviderEventsOptions {
+    provider: string;
+    pollIntervalMs?: number;
+    cursor?: string;
+    signal?: AbortSignal;
+}
+export declare class NangoHelpers extends IntegrationProvider {
+    readonly name = "nango";
+    /**
+     * Ingest a Nango webhook event into Relayfile.
+     *
+     * @param workspaceId - Relayfile workspace ID
+     * @param rawInput - NangoWebhookInput
+     * @param signal - Optional abort signal
+     */
+    ingestWebhook(workspaceId: string, rawInput: unknown, signal?: AbortSignal): Promise<QueuedResponse>;
+    /**
+     * Normalize a Nango webhook input to the generic WebhookInput format.
+     */
+    normalize(input: NangoWebhookInput): WebhookInput;
+}

package/dist/nango.js

@@ -0,0 +1,91 @@
+/**
+ * Nango integration bridge for Relayfile.
+ *
+ * Maps Nango sync webhook events → Relayfile filesystem paths + semantics.
+ *
+ * @see https://docs.nango.dev/integrate/guides/receive-webhooks-from-nango
+ */
+import { IntegrationProvider, computeCanonicalPath, } from "./provider.js";
+// ---------------------------------------------------------------------------
+// Nango provider implementation
+// ---------------------------------------------------------------------------
+function buildSemanticProperties(provider, input, payload) {
+    const properties = {
+        "nango.connection_id": input.connectionId,
+        "nango.integration_id": input.integrationId,
+        "provider": provider,
+        "provider.object_type": input.model,
+        "provider.object_id": input.objectId
+    };
+    if (input.providerConfigKey) {
+        properties["nango.provider_config_key"] = input.providerConfigKey;
+    }
+    if (typeof payload.status === "string") {
+        properties["provider.status"] = payload.status;
+    }
+    if (typeof payload.updated_at === "string") {
+        properties["provider.updated_at"] = payload.updated_at;
+    }
+    if (typeof payload.created_at === "string") {
+        properties["provider.created_at"] = payload.created_at;
+    }
+    return properties;
+}
+export class NangoHelpers extends IntegrationProvider {
+    name = "nango";
+    /**
+     * Ingest a Nango webhook event into Relayfile.
+     *
+     * @param workspaceId - Relayfile workspace ID
+     * @param rawInput - NangoWebhookInput
+     * @param signal - Optional abort signal
+     */
+    async ingestWebhook(workspaceId, rawInput, signal) {
+        const input = rawInput;
+        const provider = input.integrationId.split("-")[0] ?? input.integrationId;
+        const path = computeCanonicalPath(provider, input.model, input.objectId);
+        const properties = buildSemanticProperties(provider, input, input.payload);
+        return this.client.ingestWebhook({
+            workspaceId,
+            provider: provider,
+            event_type: input.eventType,
+            path,
+            data: {
+                ...input.payload,
+                semantics: {
+                    properties,
+                    relations: input.relations ?? []
+                }
+            },
+            headers: {
+                "X-Nango-Connection-Id": input.connectionId,
+                "X-Nango-Integration-Id": input.integrationId,
+                ...(input.providerConfigKey
+                    ? { "X-Nango-Provider-Config-Key": input.providerConfigKey }
+                    : {})
+            },
+            signal
+        });
+    }
+    /**
+     * Normalize a Nango webhook input to the generic WebhookInput format.
+     */
+    normalize(input) {
+        const provider = input.integrationId.split("-")[0] ?? input.integrationId;
+        return {
+            provider,
+            objectType: input.model,
+            objectId: input.objectId,
+            eventType: input.eventType,
+            payload: input.payload,
+            relations: input.relations,
+            metadata: {
+                "nango.connection_id": input.connectionId,
+                "nango.integration_id": input.integrationId,
+                ...(input.providerConfigKey
+                    ? { "nango.provider_config_key": input.providerConfigKey }
+                    : {}),
+            },
+        };
+    }
+}