plaid-integration

Plaid API の統合

Bun を使用する TypeScript アプリケーションで Plaid を統合し、銀行口座を接続して取引を同期します。

インストール

bun add plaid

クライアントの初期化

import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';

const plaidClient = new PlaidApi(new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV || 'sandbox'],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    }
  }
}));

Link トークンの作成

ポップアップモードを使用するには redirect_uri を省略してください。ローカルでの HTTP 開発では必須です。

const response = await plaidClient.linkTokenCreate({
  user: { client_user_id: `user-${Date.now()}` },
  client_name: 'My App',
  products: ['transactions'],
  country_codes: ['US'],
  language: 'en',
  // No redirect_uri = popup mode, works with HTTP localhost
});
const linkToken = response.data.link_token;

トークンの交換

ユーザーが Link を完了したら、一時的な public_token を永続的な access_token と交換します。

const response = await plaidClient.itemPublicTokenExchange({ public_token });
const { access_token, item_id } = response.data;
// Store access_token securely — never expose to clients

取引の同期

Plaid は 1 回のリクエストで最大 500 件の取引を返します。必ずページネーションを使用してください。

let offset = 0;
const count = 500;

while (true) {
  const response = await plaidClient.transactionsGet({
    access_token,
    start_date: '2023-01-01',
    end_date: '2024-12-31',
    options: { count, offset },
  });

  // Process response.data.transactions
  offset += response.data.transactions.length;
  if (offset >= response.data.total_transactions) break;
}

継続的な増分更新には、カーソルを使用する transactionsSync を推奨します。references/api-reference.md を参照してください。

エラー処理

error.response?.data から Plaid のエラーをキャッチします。

try {
  await plaidClient.transactionsGet({ ... });
} catch (error: any) {
  const plaidError = error.response?.data;
  if (!plaidError) throw error;

  switch (plaidError.error_code) {
    case 'ITEM_LOGIN_REQUIRED':
      // Re-initialize Link in update mode
      break;
    case 'INVALID_ACCESS_TOKEN':
      // Token revoked — delete item, prompt re-link
      break;
    case 'PRODUCT_NOT_READY':
      // Data still processing — retry after delay
      break;
    default:
      throw new Error(`Plaid error: ${plaidError.error_code} — ${plaidError.error_message}`);
  }
}

データベースのセットアップ

Bun SQLite を使用し、items → accounts → transactions の階層を構成します。インデックス、プリペアドステートメント、TypeScript 型を含む完全なスキーマについては、references/code-examples.md を参照してください。

リファレンスファイル

• references/code-examples.md — 完全に動作する実装：Elysia サーバーを使った銀行接続フロー、ページネーションによる取引の同期、Bun SQLite データベースモジュール一式、CLI 統合
• references/api-reference.md — リクエスト／レスポンスの形式、Sandbox テスト用認証情報、Webhook イベント、レート制限を含むすべての API エンドポイント