@xenterprises/fastify-xplaid

Fastify plugin for Plaid financial data integration — bank account linking (Link tokens), transactions, balances, identity, auth, investments, liabilities, and webhook management. For Fastify apps that need to connect users' bank accounts through Plaid with a single, pre-configured client.

Install

npm install @xenterprises/fastify-xplaid fastify@5

Minimal example

import Fastify from "fastify";
import xPlaid from "@xenterprises/fastify-xplaid";

const fastify = Fastify({ logger: true });

// The consumer owns env access — the plugin never reads process.env
await fastify.register(xPlaid, {
  clientId: process.env.PLAID_CLIENT_ID,
  secret: process.env.PLAID_SECRET,
});

// Create a Link token for your frontend
const { linkToken } = await fastify.xplaid.link.createToken({ userId: "user_123" });

Options

All configuration arrives via app.register(xPlaid, options). The plugin never reads process.env.

| Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | clientId | string | Yes | — | Plaid client ID | | secret | string | Yes | — | Plaid secret (environment-specific) | | environment | string | No | "sandbox" | "sandbox", "development", or "production" | | version | string | No | "2020-09-14" | Plaid API version header | | active | boolean | No | true | Set false to skip registration entirely |

Decorators

Everything lives under the single fastify.xplaid namespace. The Plaid SDK client is created once at registration and reused by all methods.

xplaid.link

| Method | Signature | Description | |--------|-----------|-------------| | createToken | (params) → Promise | Create a Link token for initializing Plaid Link | | getToken | (linkToken) → Promise | Get information about a Link token | | exchangePublicToken | (publicToken) → Promise | Exchange a public token for an access token |

createToken params:

| Param | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | userId | string | Yes | — | Unique client user ID | | clientName | string | No | "App" | Application name (truncated to 30 chars) | | products | string[] | No | ["transactions"] | Products to enable | | countryCodes | string[] | No | ["US"] | Country codes | | language | string | No | "en" | Display language | | webhook | string | No | — | Webhook URL for real-time updates | | redirectUri | string | No | — | OAuth redirect URI | | accessToken | string | No | — | For update mode (omits products) |

xplaid.accounts

| Method | Signature | Description | |--------|-----------|-------------| | get | (accessToken, options?) → Promise | Get accounts for an Item | | getBalance | (accessToken, options?) → Promise | Get real-time account balances |

xplaid.transactions

| Method | Signature | Description | |--------|-----------|-------------| | sync | (accessToken, options?) → Promise | Sync transactions (recommended; cursor-based) | | get | (accessToken, startDate, endDate, options?) → Promise | Get transactions by date range | | refresh | (accessToken) → Promise | Force refresh transaction data | | getRecurring | (accessToken, options?) → Promise | Get recurring transaction streams |

xplaid.identity

| Method | Signature | Description | |--------|-----------|-------------| | get | (accessToken, options?) → Promise | Get identity info (name, email, phone, address) |

xplaid.auth

| Method | Signature | Description | |--------|-----------|-------------| | get | (accessToken, options?) → Promise | Get ACH routing and account numbers |

xplaid.investments

| Method | Signature | Description | |--------|-----------|-------------| | getHoldings | (accessToken, options?) → Promise | Get investment holdings | | getTransactions | (accessToken, startDate, endDate, options?) → Promise | Get investment transactions |

xplaid.liabilities

| Method | Signature | Description | |--------|-----------|-------------| | get | (accessToken, options?) → Promise | Get credit, mortgage, and student loan liabilities |

xplaid.items

| Method | Signature | Description | |--------|-----------|-------------| | get | (accessToken) → Promise | Get Item status and metadata | | remove | (accessToken) → Promise | Permanently remove an Item | | getInstitution | (institutionId, countryCodes?) → Promise | Get institution by ID | | searchInstitutions | (query, options?) → Promise | Search institutions by name |

xplaid.webhooks

| Method | Signature | Description | |--------|-----------|-------------| | update | (accessToken, webhookUrl) → Promise | Update webhook URL for an Item | | getVerificationKey | (keyId) → Promise | Get a webhook verification key (for verifying Plaid-Verification signatures in your own webhook route) |

This plugin does not register a webhook route. If you expose one, verify the JWT signature with getVerificationKey before processing the payload — see Plaid's webhook verification guide.

xplaid.sandbox

| Method | Signature | Description | |--------|-----------|-------------| | createPublicToken | (institutionId, products) → Promise | Create a sandbox public token (sandbox only) | | resetItem | (accessToken) → Promise | Reset an Item's login (sandbox only) |

xplaid.config

| Property | Type | Description | |----------|------|-------------| | environment | string | Current Plaid environment | | clientId | string | Masked client ID (***xxxx) — the full ID is never exposed |

xplaid.constants

| Constant | Description | |----------|-------------| | ENVIRONMENTS | { SANDBOX, DEVELOPMENT, PRODUCTION } (also a named export) | | PRODUCTS | { AUTH, TRANSACTIONS, IDENTITY, ASSETS, INVESTMENTS, LIABILITIES, BALANCE, INCOME, TRANSFER, SIGNAL, STATEMENTS } (also a named export) | | COUNTRY_CODES | { US, CA, GB, ES, FR, IE, NL, DE } (also a named export) |

xplaid.raw

Direct access to the underlying PlaidApi client for any Plaid endpoint not wrapped above.

Routes

None. The plugin only decorates fastify.xplaid.

Error behavior

Registration fails fast with actionable messages:

xplaid: missing required option `clientId` (string), e.g. `app.register(xPlaid, { clientId: 'your-client-id', secret: 'your-secret' })`
xplaid: missing required option `secret` (string), e.g. `app.register(xPlaid, { clientId: 'your-client-id', secret: 'your-secret' })`
xplaid: option `environment` must be one of: sandbox, development, production, e.g. `app.register(xPlaid, { ... })`
xplaid: option `version` must be a string, e.g. `app.register(xPlaid, { ... })`

Every API method validates its arguments ([xPlaid] <param> is required and must be a non-empty string) and wraps Plaid API failures into an Error with:

{
  message: "Human-readable error from Plaid or a fallback",
  statusCode: 400,          // HTTP status from Plaid (500 when unavailable)
  plaidError: {              // Full Plaid error body (or null)
    error_type: "INVALID_REQUEST",
    error_code: "INVALID_ACCESS_TOKEN",
    error_message: "...",
    display_message: "...",
    request_id: "..."
  }
}

Failures are logged through fastify.log with the Plaid error message only — raw SDK error objects (which may carry sensitive payloads) are never logged. The clientId is masked in xplaid.config and the secret is never exposed.

Requirements

• Node.js >= 20
• Fastify >= 5 (peer dependency)

License

Proprietary — All Rights Reserved X Enterprises. See LICENSE.