Sdk

npm install @dataferry/sdk

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

const ferry = new Ferry({
  apiKey: process.env.DATAFERRY_API_KEY,
  baseUrl: 'https://api.dataferry.dev', // optional, defaults to this
  timeout: 30000, // optional, request timeout in ms
});

const session = await ferry.createPortalSession({
  scopeId: 'user_123',           // Required for multi-tenant
  connectionId: 'conn_abc',      // Optional, uses primary if omitted
  returnUrl: 'https://...',      // Where to redirect after
  expiresIn: 3600,               // Session duration in seconds (default: 3600)
  metadata: { plan: 'pro' },     // Custom data attached to session
});

{
  id: 'ps_abc123',
    url: 'https://portal.dataferry.dev/s/abc123',
    expiresAt: Date
}

const session = await ferry.portalSessions.create({
  scopeId: 'user_123',
  returnUrl: 'https://...',
});

const session = await ferry.portalSessions.retrieve('ps_abc123');
// { id, scopeId, expiresAt, isExpired, ... }

await ferry.portalSessions.revoke('ps_abc123');

const exportJob = await ferry.exports.create({
  scopeId: 'user_123',
  connectionId: 'conn_abc',  // optional
  format: 'csv',
  tables: ['conversations', 'messages'],  // optional, defaults to all
});

const exportJob = await ferry.exports.retrieve('exp_abc123');

if (exportJob.status === 'completed') {
  console.log(exportJob.downloadUrl);
}

const { data, meta } = await ferry.exports.list({
  scopeId: 'user_123',
  connectionId: 'conn_abc',
  status: 'completed',
  page: 1,
  limit: 20,
});

const completed = await ferry.exports.poll('exp_abc123', {
  maxWait: 300000,  // 5 minutes
  interval: 2000,   // check every 2 seconds
});

const connections = await ferry.connections.list();

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

const connection = await ferry.connections.retrieve('conn_abc123');

const connection = await ferry.connections.update('conn_abc123', {
  name: 'Production DB (Updated)',
});

await ferry.connections.delete('conn_abc123');

const result = await ferry.connections.test('conn_abc123');
if (result.connected) {
  console.log('Connected successfully');
}

await ferry.connections.setPrimary('conn_abc123');

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

try {
  await ferry.createPortalSession({ scopeId: 'user_123' });
} catch (error) {
  if (error instanceof FerryError) {
    console.log(error.code);    // 'INVALID_REQUEST'
    console.log(error.message); // 'Invalid scopeId'
    console.log(error.status);  // 400
  }
}

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