@dataferry/sdk

Node.js SDK for DataFerry - data export infrastructure for SaaS companies.

DataFerry helps you provide end-user data export functionality for GDPR/CCPA compliance and data portability.

Installation

npm install @dataferry/sdk

Quick Start

import { Ferry } from '@dataferry/sdk';

const ferry = new Ferry({
  apiKey: process.env.DATAFERRY_API_KEY,
});

// Create a portal session for an end user
const session = await ferry.createPortalSession({
  profile: 'default',
  scopeId: 'user_123',
  returnUrl: 'https://app.example.com/settings',
});

// Redirect the user to the portal URL
// session.url -> https://portal.dataferry.dev/session/...

Usage

Creating Portal Sessions

The simplest way to let users export their data is through the portal:

// With a scope ID (filters exported data to this user)
const session = await ferry.createPortalSession({
  profile: 'default',
  scopeId: 'user_123',
  returnUrl: 'https://app.example.com/settings',
});

// Without a scope ID (exports all data)
const session = await ferry.createPortalSession({
  profile: 'default',
  returnUrl: 'https://app.example.com/settings',
});

// With all options
const session = await ferry.createPortalSession({
  profile: 'default',
  scopeId: 'user_123',
  returnUrl: 'https://...',       // Where to redirect after export
  expiresIn: 3600,               // Session duration in seconds
  email: '[email protected]',     // Notify when export completes
  metadata: { plan: 'pro' },     // Custom metadata
});

console.log(session.url);       // Redirect user here
console.log(session.expiresAt); // Session expiration

Programmatic Exports

For server-to-server export workflows:

// Create an export job
const exportJob = await ferry.exports.create({
  scopeId: 'user_123',
  format: 'csv',
  tables: ['users', 'posts', 'comments'],
});

// Poll until complete
const completed = await ferry.exports.poll(exportJob.id, {
  maxWait: 300000,  // 5 minutes
  interval: 2000,   // Check every 2 seconds
});

if (completed.status === 'completed') {
  console.log('Download URL:', completed.downloadUrl);
}

Managing Database Connections

// List all connections
const connections = await ferry.connections.list();

// Create a new connection
const connection = await ferry.connections.create({
  name: 'Production DB',
  host: 'db.example.com',
  port: '5432',
  database: 'myapp',
  user: 'ferry_readonly',
  password: 'secret',
  ssl: true,
});

// Test a connection
const result = await ferry.connections.test(connection.id);
if (result.connected) {
  console.log(`Connected to ${result.database}`);
}

API Reference

Ferry

The main client class.

const ferry = new Ferry({
  apiKey: string,           // Required: Your API key
  baseUrl?: string,         // Optional: API base URL (default: https://api.dataferry.dev)
  timeout?: number,         // Optional: Request timeout in ms (default: 30000)
});

ferry.createPortalSession(params)

Creates a portal session for an end user.

| Parameter | Type | Description | |-----------|------|-------------| | profile | string | Export profile name (required) | | scopeId | string? | Scope ID for data filtering (omit to export all data) | | returnUrl | string? | URL to redirect after export | | expiresIn | number? | Session duration in seconds (default: 3600) | | email | string? | End-user email for export completion notifications | | metadata | object? | Custom metadata |

Returns: { id: string, url: string, expiresAt: Date }

ferry.exports

Export job management.

• create(params) - Create a new export job
• retrieve(id) - Get export job details
• list(params?) - List export jobs
• poll(id, options?) - Wait for export to complete

ferry.connections

Database connection management.

• list() - List all connections
• create(params) - Create a new connection
• retrieve(id) - Get connection details
• update(id, params) - Update a connection
• delete(id) - Delete a connection
• test(id) - Test a connection

ferry.portalSessions

Portal session management (advanced).

• create(params) - Create a portal session
• retrieve(id) - Get session details
• revoke(id) - Revoke a session

Error Handling

import { Ferry, FerryError } from '@dataferry/sdk';

try {
  const session = await ferry.createPortalSession({
    profile: 'default',
    scopeId: 'user_123',
  });
} catch (error) {
  if (error instanceof FerryError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Code: ${error.code}`);
    console.error(`Status: ${error.status}`);
  }
}

TypeScript

The SDK is written in TypeScript and includes full type definitions.

import {
  Ferry,
  FerryConfig,
  FerryError,
  CreatePortalSessionParams,
  PortalSessionResult,
  ExportJob,
  DatabaseConnection,
} from '@dataferry/sdk';

License

MIT