@dataferry/sdk 0.1.0

package/README.md

@@ -0,0 +1,201 @@
+# @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
+
+```bash
+npm install @dataferry/sdk
+```
+
+## Quick Start
+
+```typescript
+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({
+  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:
+
+```typescript
+// Multi-tenant: specify the scope ID (typically user ID)
+const session = await ferry.createPortalSession({
+  scopeId: 'user_123',
+  returnUrl: 'https://app.example.com/settings',
+});
+
+// Single-tenant: no scopeId needed
+const session = await ferry.createPortalSession({
+  returnUrl: 'https://app.example.com/settings',
+});
+
+// With all options
+const session = await ferry.createPortalSession({
+  scopeId: 'user_123',
+  connectionId: 'conn_abc',      // Use a specific database connection
+  returnUrl: 'https://...',       // Where to redirect after export
+  expiresIn: 3600,               // Session duration in seconds
+  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:
+
+```typescript
+// 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
+
+```typescript
+// 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.
+
+```typescript
+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 |
+|-----------|------|-------------|
+| `scopeId` | `string?` | The scope ID for data filtering (optional for single-tenant) |
+| `connectionId` | `string?` | Database connection ID (defaults to primary) |
+| `returnUrl` | `string?` | URL to redirect after export |
+| `expiresIn` | `number?` | Session duration in seconds |
+| `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
+
+```typescript
+import { Ferry, FerryError } from '@dataferry/sdk';
+
+try {
+  const session = await ferry.createPortalSession({ 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.
+
+```typescript
+import {
+  Ferry,
+  FerryConfig,
+  FerryError,
+  CreatePortalSessionParams,
+  PortalSessionResult,
+  ExportJob,
+  DatabaseConnection,
+} from '@dataferry/sdk';
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,464 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Connections: () => Connections,
+  Exports: () => Exports,
+  Ferry: () => Ferry,
+  FerryError: () => FerryError,
+  PortalSessions: () => PortalSessions
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/resources/portalSessions.ts
+var PortalSessions = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async create(params) {
+    return this.client.request(
+      "POST",
+      "/api/v1/portal-sessions",
+      params
+    );
+  }
+  /**
+   * Get portal session details
+   *
+   * @example
+   * ```ts
+   * const session = await ferry.portalSessions.retrieve('ps_abc123');
+   * console.log(session.scopeId, session.expiresAt);
+   * ```
+   */
+  async retrieve(sessionId) {
+    return this.client.request(
+      "GET",
+      `/api/v1/portal-sessions/${sessionId}`
+    );
+  }
+  /**
+   * Revoke a portal session
+   *
+   * @example
+   * ```ts
+   * await ferry.portalSessions.revoke('ps_abc123');
+   * ```
+   */
+  async revoke(sessionId) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/portal-sessions/${sessionId}`
+    );
+  }
+};
+
+// src/resources/exports.ts
+var Exports = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async create(params) {
+    return this.client.request(
+      "POST",
+      "/api/v1/exports",
+      params
+    );
+  }
+  /**
+   * Get export job details
+   *
+   * @example
+   * ```ts
+   * const exportJob = await ferry.exports.retrieve('exp_abc123');
+   *
+   * if (exportJob.status === 'completed') {
+   *   console.log('Download:', exportJob.downloadUrl);
+   * }
+   * ```
+   */
+  async retrieve(exportId) {
+    return this.client.request(
+      "GET",
+      `/api/v1/exports/${exportId}`
+    );
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async list(params) {
+    return this.client.requestPaginated(
+      "/api/v1/exports",
+      params
+    );
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async poll(exportId, options = {}) {
+    const maxWait = options.maxWait ?? 3e5;
+    const interval = options.interval ?? 2e3;
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWait) {
+      const exportJob = await this.retrieve(exportId);
+      if (exportJob.status === "completed" || exportJob.status === "failed" || exportJob.status === "expired") {
+        return exportJob;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(`Export ${exportId} did not complete within ${maxWait}ms`);
+  }
+};
+
+// src/resources/connections.ts
+var Connections = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List all database connections for the organization
+   *
+   * @example
+   * ```ts
+   * const connections = await ferry.connections.list();
+   * for (const conn of connections) {
+   *   console.log(conn.name);
+   * }
+   * ```
+   */
+  async list() {
+    const result = await this.client.requestPaginated(
+      "/api/v1/connections"
+    );
+    return result.data;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async create(params) {
+    return this.client.request(
+      "POST",
+      "/api/v1/connections",
+      params
+    );
+  }
+  /**
+   * Get a database connection by ID
+   *
+   * @example
+   * ```ts
+   * const connection = await ferry.connections.retrieve('conn_abc123');
+   * console.log(connection.host, connection.database);
+   * ```
+   */
+  async retrieve(connectionId) {
+    return this.client.request(
+      "GET",
+      `/api/v1/connections/${connectionId}`
+    );
+  }
+  /**
+   * Update a database connection
+   *
+   * @example
+   * ```ts
+   * const connection = await ferry.connections.update('conn_abc123', {
+   *   name: 'Production DB (Updated)',
+   * });
+   * ```
+   */
+  async update(connectionId, params) {
+    return this.client.request(
+      "PUT",
+      `/api/v1/connections/${connectionId}`,
+      params
+    );
+  }
+  /**
+   * Delete a database connection
+   *
+   * @example
+   * ```ts
+   * const result = await ferry.connections.delete('conn_abc123');
+   * console.log(result.deleted); // true
+   * ```
+   */
+  async delete(connectionId) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/connections/${connectionId}`
+    );
+  }
+  /**
+   * 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}`);
+   * }
+   * ```
+   */
+  async test(connectionId) {
+    return this.client.request(
+      "POST",
+      `/api/v1/connections/${connectionId}/test`
+    );
+  }
+};
+
+// src/client.ts
+var Ferry = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  /** Portal session management */
+  portalSessions;
+  /** Export management */
+  exports;
+  /** Database connection management */
+  connections;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? "https://api.dataferry.dev";
+    this.timeout = config.timeout ?? 3e4;
+    this.portalSessions = new PortalSessions(this);
+    this.exports = new Exports(this);
+    this.connections = new Connections(this);
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async createPortalSession(params) {
+    const request = { profile: params.profile };
+    if (params.scopeId !== void 0) {
+      request.scopeId = params.scopeId;
+    }
+    if (params.returnUrl !== void 0) {
+      request.returnUrl = params.returnUrl;
+    }
+    if (params.expiresIn !== void 0) {
+      request.expiresIn = params.expiresIn;
+    }
+    if (params.email !== void 0) {
+      request.email = params.email;
+    }
+    if (params.metadata !== void 0) {
+      request.metadata = params.metadata;
+    }
+    const response = await this.portalSessions.create(request);
+    return {
+      id: response.id,
+      url: response.url,
+      expiresAt: response.expiresAt
+    };
+  }
+  /**
+   * Make an authenticated API request
+   */
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Basic ${Buffer.from(this.apiKey + ":").toString("base64")}`
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const fetchOptions = {
+        method,
+        headers,
+        signal: controller.signal
+      };
+      if (body) {
+        fetchOptions.body = JSON.stringify(body);
+      }
+      const response = await fetch(url, fetchOptions);
+      const data = await response.json();
+      if (!response.ok || !data.success) {
+        const error = new FerryError(
+          data.error?.message ?? "An error occurred",
+          data.error?.code ?? "UNKNOWN_ERROR",
+          response.status
+        );
+        throw error;
+      }
+      return data.data;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Make a paginated API request
+   */
+  async requestPaginated(path, params) {
+    const searchParams = new URLSearchParams();
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          searchParams.set(key, String(value));
+        }
+      }
+    }
+    const url = searchParams.toString() ? `${path}?${searchParams}` : path;
+    const response = await fetch(`${this.baseUrl}${url}`, {
+      headers: {
+        Authorization: `Basic ${Buffer.from(this.apiKey + ":").toString("base64")}`
+      }
+    });
+    const result = await response.json();
+    if (!response.ok || !result.success) {
+      throw new FerryError(
+        result.error?.message ?? "An error occurred",
+        result.error?.code ?? "UNKNOWN_ERROR",
+        response.status
+      );
+    }
+    return {
+      data: result.data,
+      meta: result.meta
+    };
+  }
+};
+var FerryError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "FerryError";
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Connections,
+  Exports,
+  Ferry,
+  FerryError,
+  PortalSessions
+});
+//# sourceMappingURL=index.cjs.map