@relayfile/sdk 0.1.3 → 0.1.4

package/dist/client.d.ts

@@ -6,8 +6,11 @@ export interface RelayFileRetryOptions {
     maxDelayMs?: number;
     jitterRatio?: number;
 }
+/** Default base URL for the hosted Relayfile API */
+export declare const DEFAULT_RELAYFILE_BASE_URL = "https://api.relayfile.dev";
 export interface RelayFileClientOptions {
-    baseUrl: string;
+    /** API base URL. Defaults to https://api.relayfile.dev */
+    baseUrl?: string;
     token: AccessTokenProvider;
     fetchImpl?: typeof fetch;
     userAgent?: string;

package/dist/client.js

@@ -1,4 +1,6 @@
 import { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
+/** Default base URL for the hosted Relayfile API */
+export const DEFAULT_RELAYFILE_BASE_URL = "https://api.relayfile.dev";
 const DEFAULT_RETRY_OPTIONS = {
     maxRetries: 3,
     baseDelayMs: 100,
@@ -139,7 +141,7 @@ export class RelayFileClient {
     userAgent;
     retryOptions;
     constructor(options) {
-        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.baseUrl = (options.baseUrl ?? DEFAULT_RELAYFILE_BASE_URL).replace(/\/+$/, "");
         this.tokenProvider = options.token;
         this.fetchImpl = options.fetchImpl ?? fetch;
         this.userAgent = options.userAgent;

package/dist/connection.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared ConnectionProvider interface and related types.
+ *
+ * These types are the contract every provider package must implement.
+ */
+export type ProxyMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type ProxyHeaders = Record<string, string>;
+export type ProxyQuery = Record<string, string>;
+/** Request sent through a connection provider's proxy. */
+export interface ProxyRequest {
+    method: ProxyMethod;
+    /** Base API URL for the upstream service. */
+    baseUrl: string;
+    endpoint: string;
+    connectionId: string;
+    headers?: ProxyHeaders;
+    body?: unknown;
+    query?: ProxyQuery;
+}
+/** Response returned from a proxied request. */
+export interface ProxyResponse<T = unknown> {
+    status: number;
+    headers: ProxyHeaders;
+    data: T;
+}
+/** Webhook normalized into a provider-agnostic shape. */
+export interface NormalizedWebhook {
+    provider: string;
+    connectionId: string;
+    eventType: string;
+    objectType: string;
+    objectId: string;
+    payload: Record<string, unknown>;
+}
+/** Interface every connection provider must implement. */
+export interface ConnectionProvider {
+    readonly name: string;
+    proxy<T = unknown>(request: ProxyRequest): Promise<ProxyResponse<T>>;
+    healthCheck(connectionId: string): Promise<boolean>;
+    handleWebhook?(rawPayload: unknown): Promise<NormalizedWebhook>;
+    getConnection?(connectionId: string): Promise<Record<string, unknown>>;
+    listConnections?(): Promise<Array<Record<string, unknown>>>;
+}

package/dist/connection.js

@@ -0,0 +1,6 @@
+/**
+ * Shared ConnectionProvider interface and related types.
+ *
+ * These types are the contract every provider package must implement.
+ */
+export {};

package/dist/index.d.ts

@@ -1,10 +1,7 @@
-export { RelayFileClient, type ConnectWebSocketOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, 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 { 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 { 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, 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,9 +1,5 @@
-export { RelayFileClient } from "./client.js";
+export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL } from "./client.js";
 export { RelayFileSync } from "./sync.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 // Integration providers
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";
-// Nango bridge
-export { NangoHelpers } from "./nango.js";
-// Composio bridge
-export { ComposioHelpers } from "./composio.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/composio.d.ts

@@ -1,63 +0,0 @@
-/**
- * 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

@@ -1,233 +0,0 @@
-/**
- * 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/nango.d.ts

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,91 +0,0 @@
-/**
- * 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 }
-                    : {}),
-            },
-        };
-    }
-}