@kody/plaid
Read Plaid identity, items, accounts, balances, and transactions with sandbox-friendly secret-backed helpers.
Files
@kody/plaid — agent notes
Human setup and intent live in README.md. This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
name only — never paste secret values or bank passwords. Do not disable
live webhooks or jobs.
Secrets
| Name | Purpose |
|---|---|
plaidClientId | Dashboard client id; hosts sandbox.plaid.com, production.plaid.com |
plaidSecret | Dashboard secret (same hosts) |
plaidAccessToken | Optional Item access_token after Link / sandbox exchange |
plaidClientId-<label> / plaidSecret-<label> / plaidAccessToken-<label> | Extra account via account: "<label>" or explicit secret name fields |
Placeholder shape: {{secret:plaidClientId|scope=user}}.
Import paths
| Export | Import |
|---|---|
root dispatcher (default smoke-test) | kody:@kody/plaid |
| item | kody:@kody/plaid/item |
| accounts | kody:@kody/plaid/accounts |
| identity | kody:@kody/plaid/identity |
| transactions | kody:@kody/plaid/transactions |
| institutions | kody:@kody/plaid/institutions |
| link | kody:@kody/plaid/link |
| sandbox | kody:@kody/plaid/sandbox |
| smoke-test | kody:@kody/plaid/smoke-test |
Prefer static kody:@kody/plaid/... imports from execute. Do not lead with
packages.invoke. Low-level transport (plaidRequest, PlaidApiError) stays
pinned to sandbox.plaid.com / production.plaid.com with
Plaid-Version: 2020-09-14.
Smoke test (read-only)
Without credentials: { ok: true, live: false } plus setup URLs. With
plaidClientId / plaidSecret: lists a few institutions — no Items, no bank
login.
import smokeTest from 'kody:@kody/plaid/smoke-test'
export default async function main() {
return await smokeTest()
}Equivalent via root dispatcher:
import plaid from 'kody:@kody/plaid'
export default async function main() {
return await plaid({ action: 'smoke-test' })
}Read-only accounts (needs plaidAccessToken or accessToken):
import plaid from 'kody:@kody/plaid'
export default async function main() {
return await plaid({ action: 'get-accounts' })
}dryRun / confirm (mutations)
Link-token creation, sandbox public-token create, public-token exchange,
Item remove, webhook update, and transactions refresh default to dry-run.
They return { dryRun: true, method, path, body } unless you pass
confirm: true. dryRun: true always previews, even with confirm.
import { createLinkToken } from 'kody:@kody/plaid/link'
import { createSandboxPublicToken } from 'kody:@kody/plaid/sandbox'
import { exchangePublicToken } from 'kody:@kody/plaid/item'
export default async function main() {
const preview = await createLinkToken({
clientName: 'Example Finance',
clientUserId: 'user-123',
})
const sandboxPreview = await createSandboxPublicToken()
// Live exchange only after user approval — then save access_token as
// plaidAccessToken (never leave it in chat longer than needed).
const exchanged = await exchangePublicToken({
publicToken: 'public-sandbox-…',
confirm: true,
})
return { preview, sandboxPreview, exchanged }
}Bank login policy (agents)
Never request, accept, or store a bank username or password. Use Plaid Link
(or Sandbox public-token create) only. On ITEM_LOGIN_REQUIRED, recreate Link
in update mode for the owner — do not ask for bank credentials in chat.
Edge cases / fork notes
- Default environment is sandbox; pass
environment: "production"for live Items. Items cannot move between environments. - Fork before wiring secrets so each account owns its Plaid app credentials.
- Keep
LICENSE(MIT),community-icon.svg, and README Intent unchanged unless deliberately updating branding or scope. - Do not disable live webhooks on forked Items without an explicit request.