plaid-node

Plaid is the official Node.js and TypeScript client library for the Plaid API, generated from Plaid’s OpenAPI 3.0 specification using OpenAPI Generator’s typescript-axios template. It exposes a single PlaidApi class that wraps every Plaid product — Auth, Transactions, Identity, Assets, Liabilities, Investments, Income, Payment Initiation, Identity Verification, Monitor, Enrich, and Statements — behind fully typed request and response models.

Because the client is generated directly from Plaid’s own API spec, it stays in lockstep with new endpoints and fields as Plaid ships them. Maintainers cut a new release roughly monthly, document breaking changes in the CHANGELOG, and gate them behind semantic-versioning major bumps, with the README carrying an explicit pre/post-9.0.0 migration guide for teams still on the older callback-based client.

What You Get

• A typed PlaidApi client class covering every Plaid product (Auth, Transactions, Identity, Assets, Liabilities, Investments, Income, Payment Initiation, Identity Verification, Monitor, Enrich, Statements)
• Full TypeScript type definitions for every request and response model, generated straight from Plaid’s OpenAPI schema
• A Configuration object plus PlaidEnvironments.sandbox/.production constants for setting API credentials, base URL, and the Plaid-Version header
• An axios-based HTTP layer with promise support and a consistent error shape (error.response.data with error_type/error_code)
• CHANGELOG- and README-driven migration guidance for upgrading across major client versions

Common Use Cases

• Exchanging a Link public_token for a permanent access_token and fetching linked accounts
• Pulling transaction history via transactionsSync/transactionsGet for budgeting or accounting apps
• Verifying bank account and routing numbers with Auth before initiating ACH transfers
• Running identity or income verification checks during user onboarding
• Downloading Asset Reports as PDFs for lending and underwriting workflows

Under The Hood

Architecture plaid-node follows a layered structure typical of OpenAPI-generated clients: configuration.ts holds a Configuration object (API credentials, base path, headers), base.ts defines BaseAPI/RequiredError primitives, common.ts provides auth-injection and request-building helpers (setApiKeyToObject, createRequestFunction, assertParamExists), and a single very large api.ts implements every Plaid product as functions wrapped into a PlaidApi class extending BaseAPI. index.ts re-exports api and configuration as the package’s public surface. Because api.ts is generated by OpenAPI Generator’s typescript-axios template from Plaid’s own OpenAPI spec (the Mustache templates live under templates/typescript-axios), the file is explicitly marked “do not edit manually” — the maintained surface a contributor actually touches is the small hand-written base.ts/common.ts/configuration.ts trio plus the test harness, while endpoint coverage tracks Plaid’s spec automatically. Data flow is linear: a caller builds a request object, PlaidApi methods delegate to generated axios-request builders in common.ts, and responses or errors pass through untouched as axios promises.

Tech Stack The client is written in TypeScript targeting Node >=10, compiled with tsc into dist/ for publishing, and uses axios as its sole runtime dependency. There is no web or ORM framework involved since this is a pure API client; the closest analog is OpenAPI Generator itself, whose templates in the repo capture how api.ts, base.ts, and configuration.ts are regenerated from Plaid’s separate plaid-openapi spec repo. Tests run via mocha and chai with ts-node/register against the compiled dist/ output, executed inside a Docker container built from the repo’s Dockerfile on CircleCI (machine executor, docker build then docker run with sandbox credentials as env vars). Releases are tagged with the xyz tool via make release-major/minor/patch, and linting is split between ESLint and a legacy JSHint config.

Code Quality The test/ directory holds 23 spec files (accounts.spec.ts, transactions.spec.ts, paymentInitiation.spec.ts, and similar) written in TypeScript with Mocha/Chai, but nearly all of them are integration tests that hit Plaid’s live sandbox API using injected client credentials rather than unit tests with mocks — client.spec.ts is the one narrow unit test, asserting that the PlaidApi constructor doesn’t throw. Error handling is centralized and typed: RequiredError extends Error for missing-parameter validation, and generated methods call assertParamExists before building each request; consumers are expected to catch axios errors and read error.response.data for Plaid’s structured error fields, which the README documents explicitly. Because the generated files all carry lint-disable headers, actual lint coverage applies mainly to the small hand-maintained surface, and there’s no visible coverage tooling beyond the TypeScript compiler succeeding.

API Design Ergonomics lean on OpenAPI-generator conventions: every endpoint is a verb-suffixed method on one PlaidApi instance (transactionsSync, accountsGet, itemPublicTokenExchange), so naming is mechanically consistent across the large set of generated endpoints rather than hand-curated, and each request takes a single typed request object instead of positional arguments — a deliberate improvement the README documents over the older callback-based client it replaced. Getting started requires only a Configuration plus a PlaidEnvironments constant and a PlaidApi instantiation, with auth headers set once at the client level rather than per call. Type definitions are exhaustive since they’re generated from Plaid’s own spec, giving strong editor autocomplete for deeply nested response shapes, though the tradeoff is that the generated client file is not designed for a human to browse directly — discoverability leans on IDE autocomplete and Plaid’s separately hosted API reference rather than in-repo docs.