mcpField
P
plaid-integration

plaid-integration

github.com/b-open-io开发1667 次安装4 周前更新
代码仓库

关于 plaid-integration

面向 TypeScript 和 Bun 应用的 Plaid 集成技能，涵盖银行账户连接与交易同步。内容包括客户端初始化、Link 令牌创建与交换、分页读取、增量同步、错误处理及 Bun SQLite 示例。

主要功能

  1. 01使用 Bun 初始化 Plaid 客户端
  2. 02创建 Link 令牌并交换访问令牌
  3. 03分页获取交易记录
  4. 04基于游标增量同步
  5. 05错误处理与 SQLite 示例

适用场景

  1. 01为应用添加银行账户连接
  2. 02持续同步交易数据
  3. 03构建 Bun SQLite 交易数据存储

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/b-open-io/prompts --skill plaid-integration

安装后在 Claude Code 中输入/plaid-integration确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
.clawnet/
unsigned-skill.json
references/
api-reference.md
code-examples.md

详细介绍

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 Token

省略 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 每次请求最多返回 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 数据库模块、命令行集成
  • references/api-reference.md — 所有 API 端点的请求／响应结构、沙盒测试凭据、Webhook 事件、速率限制

评论

支持 Markdown