@dataferry/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,534 @@
+/**
+ * DataFerry SDK types
+ *
+ * These types are inlined from @dataferry/common so the SDK
+ * has zero runtime and type-level dependencies.
+ */
+type ExportStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'expired';
+type ExportFormat = 'csv';
+interface ExportMetadata {
+    requestIp?: string;
+    userAgent?: string;
+    portalSessionId?: string;
+    custom?: Record<string, unknown>;
+}
+interface ExportJob {
+    id: string;
+    organizationId: string;
+    scopeId: string;
+    connectionId?: string;
+    status: ExportStatus;
+    format: ExportFormat;
+    selectedTables: string[];
+    storageKey: string | null;
+    downloadUrl: string | null;
+    downloadUrlExpiresAt: Date | null;
+    fileSizeBytes: number | null;
+    totalRows: number | null;
+    errorMessage: string | null;
+    errorCode: string | null;
+    createdAt: Date;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    metadata: ExportMetadata;
+}
+interface CreateExportRequest {
+    scopeId: string;
+    connectionId?: string;
+    format?: ExportFormat;
+    tables?: string[];
+    webhookUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface PortalSession {
+    id: string;
+    organizationId: string;
+    scopeId: string;
+    profileId: string;
+    token: string;
+    expiresAt: Date;
+    createdAt: Date;
+    metadata?: Record<string, unknown>;
+}
+interface CreatePortalSessionRequest {
+    profile: string;
+    scopeId?: string;
+    expiresIn?: number;
+    returnUrl?: string;
+    email?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreatePortalSessionResponse {
+    id: string;
+    url: string;
+    expiresAt: Date;
+}
+interface DatabaseConnection {
+    id: string;
+    organizationId: string;
+    name: string;
+    host: string;
+    port: string;
+    database: string;
+    user: string;
+    ssl: boolean;
+    lastTestedAt: Date | null;
+    lastTestSuccess: boolean | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CreateConnectionRequest {
+    name: string;
+    host: string;
+    port?: string;
+    database: string;
+    user: string;
+    password: string;
+    ssl?: boolean;
+}
+interface UpdateConnectionRequest {
+    name?: string;
+    host?: string;
+    port?: string;
+    database?: string;
+    user?: string;
+    password?: string;
+    ssl?: boolean;
+}
+interface TestConnectionResult {
+    connected: boolean;
+    database?: string;
+    user?: string;
+    error?: string;
+    responseTimeMs?: number;
+}
+type OwnershipMode = 'direct_column' | 'fk_chain';
+interface OwnershipEdge {
+    fromTable: string;
+    fromColumn: string;
+    toTable: string;
+    toColumn: string;
+    direction: 'direct' | 'inverse';
+}
+interface IncludedTable {
+    tableName: string;
+    label: string;
+    ownershipMode: OwnershipMode | null;
+    userColumn?: string;
+    ownershipPath?: OwnershipEdge[];
+    depth: number;
+    confidence: number;
+    includedColumns: string[] | null;
+    excludedColumns: string[];
+}
+interface TableGroup {
+    id: string;
+    label: string;
+    tableNames: string[];
+}
+interface SchemaConfig {
+    id: string;
+    organizationId: string;
+    anchorTable?: string;
+    anchorColumn?: string;
+    includedTables: IncludedTable[];
+    excludedTables: string[];
+    maxDepth: number;
+    createdAt: Date;
+    updatedAt: Date;
+    version: number;
+    groups?: TableGroup[];
+}
+type WebhookEvent = 'export.completed' | 'export.failed' | 'schema.updated';
+interface WebhookStats {
+    totalDeliveries: number;
+    successfulDeliveries: number;
+    failedDeliveries: number;
+    lastDeliveryAt: Date | null;
+    lastSuccessAt: Date | null;
+    lastFailureReason: string | null;
+}
+interface WebhookEndpoint {
+    id: string;
+    organizationId: string;
+    url: string;
+    events: WebhookEvent[];
+    secret: string;
+    active: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    stats: WebhookStats;
+}
+
+/**
+ * Portal Sessions resource
+ */
+
+declare class PortalSessions {
+    private readonly client;
+    constructor(client: Ferry);
+    /**
+     * Create a new portal session for an end user
+     *
+     * @example
+     * ```ts
+     * const session = await ferry.portalSessions.create({
+     *   profile: 'default',
+     *   scopeId: 'user_123',
+     *   expiresIn: 3600,
+     *   returnUrl: 'https://yourapp.com/settings',
+     * });
+     *
+     * // Redirect user to session.url
+     * ```
+     */
+    create(params: CreatePortalSessionRequest): Promise<CreatePortalSessionResponse>;
+    /**
+     * Get portal session details
+     *
+     * @example
+     * ```ts
+     * const session = await ferry.portalSessions.retrieve('ps_abc123');
+     * console.log(session.scopeId, session.expiresAt);
+     * ```
+     */
+    retrieve(sessionId: string): Promise<PortalSession & {
+        isExpired: boolean;
+    }>;
+    /**
+     * Revoke a portal session
+     *
+     * @example
+     * ```ts
+     * await ferry.portalSessions.revoke('ps_abc123');
+     * ```
+     */
+    revoke(sessionId: string): Promise<{
+        id: string;
+    }>;
+}
+
+/**
+ * Exports resource
+ */
+
+interface ExportResponse {
+    id: string;
+    status: ExportStatus;
+    scopeId: string;
+    /** Database connection ID used for this export */
+    connectionId?: string;
+    /** Database connection name (if connection still exists) */
+    connectionName?: string;
+    format: string;
+    tables: string[];
+    downloadUrl?: string;
+    downloadUrlExpiresAt?: string;
+    fileSizeBytes?: number;
+    totalRows?: number;
+    errorMessage?: string;
+    errorCode?: string;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+interface ListExportsParams extends Record<string, string | number | undefined> {
+    scopeId?: string;
+    /** Filter by database connection ID */
+    connectionId?: string;
+    status?: ExportStatus;
+    page?: number;
+    limit?: number;
+}
+declare class Exports {
+    private readonly client;
+    constructor(client: Ferry);
+    /**
+     * Create a new export job
+     *
+     * @example
+     * ```ts
+     * // Create export using primary connection
+     * const exportJob = await ferry.exports.create({
+     *   scopeId: 'user_123',
+     *   format: 'csv',
+     *   tables: ['users', 'posts', 'comments'],
+     * });
+     *
+     * // Create export using specific connection
+     * const exportJob = await ferry.exports.create({
+     *   scopeId: 'user_123',
+     *   connectionId: 'conn_abc123',
+     *   format: 'csv',
+     *   tables: ['users', 'posts'],
+     * });
+     *
+     * console.log(exportJob.id, exportJob.status);
+     * ```
+     */
+    create(params: CreateExportRequest): Promise<ExportResponse>;
+    /**
+     * Get export job details
+     *
+     * @example
+     * ```ts
+     * const exportJob = await ferry.exports.retrieve('exp_abc123');
+     *
+     * if (exportJob.status === 'completed') {
+     *   console.log('Download:', exportJob.downloadUrl);
+     * }
+     * ```
+     */
+    retrieve(exportId: string): Promise<ExportResponse>;
+    /**
+     * List exports
+     *
+     * @example
+     * ```ts
+     * // List all exports
+     * const { data, meta } = await ferry.exports.list();
+     *
+     * // Filter by scope
+     * const { data } = await ferry.exports.list({ scopeId: 'user_123' });
+     *
+     * // Filter by status
+     * const { data } = await ferry.exports.list({ status: 'completed' });
+     *
+     * // Filter by connection
+     * const { data } = await ferry.exports.list({ connectionId: 'conn_abc123' });
+     * ```
+     */
+    list(params?: ListExportsParams): Promise<{
+        data: ExportResponse[];
+        meta: {
+            page: number;
+            limit: number;
+            total: number;
+            totalPages: number;
+        } | undefined;
+    }>;
+    /**
+     * Wait for an export to complete
+     *
+     * @example
+     * ```ts
+     * const exportJob = await ferry.exports.create({ scopeId: 'user_123' });
+     * const completed = await ferry.exports.poll(exportJob.id, { maxWait: 300000 });
+     *
+     * if (completed.status === 'completed') {
+     *   console.log('Download:', completed.downloadUrl);
+     * }
+     * ```
+     */
+    poll(exportId: string, options?: {
+        maxWait?: number;
+        interval?: number;
+    }): Promise<ExportResponse>;
+}
+
+/**
+ * Database Connections resource
+ */
+
+declare class Connections {
+    private readonly client;
+    constructor(client: Ferry);
+    /**
+     * List all database connections for the organization
+     *
+     * @example
+     * ```ts
+     * const connections = await ferry.connections.list();
+     * for (const conn of connections) {
+     *   console.log(conn.name);
+     * }
+     * ```
+     */
+    list(): Promise<DatabaseConnection[]>;
+    /**
+     * Create a new database connection
+     *
+     * @example
+     * ```ts
+     * const connection = await ferry.connections.create({
+     *   name: 'Production DB',
+     *   host: 'db.example.com',
+     *   port: '5432',
+     *   database: 'myapp',
+     *   user: 'ferry_readonly',
+     *   password: 'secret',
+     *   ssl: true,
+     * });
+     * ```
+     */
+    create(params: CreateConnectionRequest): Promise<DatabaseConnection>;
+    /**
+     * Get a database connection by ID
+     *
+     * @example
+     * ```ts
+     * const connection = await ferry.connections.retrieve('conn_abc123');
+     * console.log(connection.host, connection.database);
+     * ```
+     */
+    retrieve(connectionId: string): Promise<DatabaseConnection>;
+    /**
+     * Update a database connection
+     *
+     * @example
+     * ```ts
+     * const connection = await ferry.connections.update('conn_abc123', {
+     *   name: 'Production DB (Updated)',
+     * });
+     * ```
+     */
+    update(connectionId: string, params: UpdateConnectionRequest): Promise<DatabaseConnection>;
+    /**
+     * Delete a database connection
+     *
+     * @example
+     * ```ts
+     * const result = await ferry.connections.delete('conn_abc123');
+     * console.log(result.deleted); // true
+     * ```
+     */
+    delete(connectionId: string): Promise<{
+        id: string;
+        deleted: boolean;
+    }>;
+    /**
+     * Test a database connection
+     *
+     * @example
+     * ```ts
+     * const result = await ferry.connections.test('conn_abc123');
+     * if (result.connected) {
+     *   console.log(`Connected to ${result.database} as ${result.user}`);
+     * } else {
+     *   console.error(`Connection failed: ${result.error}`);
+     * }
+     * ```
+     */
+    test(connectionId: string): Promise<TestConnectionResult>;
+}
+
+/**
+ * DataFerry SDK client
+ */
+
+interface FerryConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the DataFerry API (default: https://api.dataferry.dev) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+    meta?: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+/**
+ * Parameters for creating a portal session
+ */
+interface CreatePortalSessionParams {
+    /** Export profile name (required) */
+    profile: string;
+    /** The scope ID for data filtering (optional for single-tenant mode) */
+    scopeId?: string;
+    /** Return URL after export completes */
+    returnUrl?: string;
+    /** Custom session duration in seconds (default: 3600) */
+    expiresIn?: number;
+    /** End-user email for export completion notifications */
+    email?: string;
+    /** Custom metadata to attach to the session */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Portal session response
+ */
+interface PortalSessionResult {
+    /** Session ID */
+    id: string;
+    /** URL to redirect the user to */
+    url: string;
+    /** When the session expires */
+    expiresAt: Date;
+}
+declare class Ferry {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /** Portal session management */
+    readonly portalSessions: PortalSessions;
+    /** Export management */
+    readonly exports: Exports;
+    /** Database connection management */
+    readonly connections: Connections;
+    constructor(config: FerryConfig);
+    /**
+     * Create a portal session for an end user to export their data.
+     *
+     * This is the primary method for initiating a data export. It creates a
+     * secure session and returns a URL where the user can select and download
+     * their data.
+     *
+     * @example
+     * ```typescript
+     * const ferry = new Ferry({ apiKey: 'your-api-key' });
+     *
+     * // Create a session for a specific user
+     * const session = await ferry.createPortalSession({
+     *   profile: 'default',
+     *   scopeId: 'user_123',
+     *   returnUrl: 'https://app.example.com/settings',
+     * });
+     *
+     * // Redirect the user to the portal
+     * res.redirect(session.url);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Single-tenant mode (no scopeId required)
+     * const session = await ferry.createPortalSession({
+     *   profile: 'default',
+     *   returnUrl: 'https://app.example.com/settings',
+     * });
+     * ```
+     */
+    createPortalSession(params: CreatePortalSessionParams): Promise<PortalSessionResult>;
+    /**
+     * Make an authenticated API request
+     */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /**
+     * Make a paginated API request
+     */
+    requestPaginated<T>(path: string, params?: Record<string, string | number | undefined>): Promise<{
+        data: T[];
+        meta: ApiResponse<T>['meta'];
+    }>;
+}
+/**
+ * DataFerry SDK error
+ */
+declare class FerryError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+
+export { Connections, type CreateConnectionRequest, type CreateExportRequest, type CreatePortalSessionParams, type CreatePortalSessionRequest, type CreatePortalSessionResponse, type DatabaseConnection, type ExportFormat, type ExportJob, type ExportStatus, Exports, Ferry, type FerryConfig, FerryError, type PortalSessionResult, PortalSessions, type SchemaConfig, type TestConnectionResult, type UpdateConnectionRequest, type WebhookEndpoint, type WebhookEvent };