# @kody/plaid ## Intent Reusable Plaid helpers so Kody agents can read identity, Items, accounts, balances, and transactions on **the caller's** Plaid app — not a shared platform connection. Auth is a saved client id plus secret. Reads are free-form and sandbox-first. Link-token creation and other mutations default to a dry-run preview and need `confirm: true` to run live. This listing is meant to be forked. After you fork, save your own `plaidClientId` / `plaidSecret` and call the helpers in your account. Never ask for or store a bank username or password in chat. Plaid Link (or the Sandbox public-token helper) is how Items are created. Share this package as https://kody.codes/@kody/plaid ## What it does - Read Items, accounts, balances, identity, and transactions - Browse / search institutions - Create Link tokens and Sandbox public tokens (dry-run by default) - Exchange public tokens and manage Item webhooks with explicit `confirm` ## Prerequisites / setup **Client id + secret** (secret-backed). There is no built-in Plaid OAuth integration and no bank-login flow in this package. Do not open `/connect/oauth` for Plaid. Do not collect institution credentials in chat. | Secret | Purpose | | --- | --- | | `plaidClientId` | Dashboard client id (`PLAID_CLIENT_ID`) | | `plaidSecret` | Dashboard secret (`PLAID_SECRET`) — sandbox or production key | | `plaidAccessToken` | Optional Item `access_token` after Link or sandbox exchange | 1. Create keys at [dashboard.plaid.com/developers/keys](https://dashboard.plaid.com/developers/keys). Prefer **sandbox** keys first. Never paste the secret or a bank password into chat. 2. Save the client id: https://kody.codes/account/secrets/new?name=plaidClientId&description=Plaid%20API%20client%20id%20from%20dashboard.plaid.com%2Fdevelopers%2Fkeys%20(PLAID_CLIENT_ID)&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user 3. Save the secret: https://kody.codes/account/secrets/new?name=plaidSecret&description=Plaid%20API%20secret%20from%20dashboard.plaid.com%2Fdevelopers%2Fkeys%20(PLAID_SECRET)&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user 4. In the account secrets UI, approve hosts **`sandbox.plaid.com`** and **`production.plaid.com`** on both secrets. Saving a secret does not approve hosts by itself. 5. Optional Item access token after Link or a confirmed sandbox exchange (this is **not** a bank password): https://kody.codes/account/secrets/new?name=plaidAccessToken&description=Plaid%20Item%20access_token%20from%20Link%20or%20sandbox%20public-token%20exchange.%20Not%20a%20bank%20password.&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user 6. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths and smoke checks. Defaults to the **Sandbox** API (`sandbox.plaid.com`). Pass `environment: "production"` per call to use `production.plaid.com`. Items cannot move between environments. ### Additional accounts Pass `account: "work"` to use `plaidClientId-work` / `plaidSecret-work` / `plaidAccessToken-work`, or pass `clientIdSecret` / `secretSecret` / `accessTokenSecret` explicitly. https://kody.codes/account/secrets/new?name=plaidClientId-work&description=Plaid%20API%20client%20id%20for%20the%20work%20account&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user https://kody.codes/account/secrets/new?name=plaidSecret-work&description=Plaid%20API%20secret%20for%20the%20work%20account&allowedHosts=sandbox.plaid.com,production.plaid.com&scope=user ## Bank login policy Agents must **never** request, accept, or store a bank username or password. Plaid Link collects those credentials in Plaid's own UI. This package only creates a `link_token` (dry-run by default) or, in Sandbox, a public token via `/sandbox/public_token/create` without taking institution credentials. If Plaid returns `ITEM_LOGIN_REQUIRED`, create a Link token in update mode and have the owner complete Link again. Do not ask them to type their bank password here. ## Done when - `plaidClientId` and `plaidSecret` are saved; Plaid hosts and package secret access are approved - Smoke test returns `ok: true` (live institutions sample when credentials exist — no Items created, no bank login) - Mutations default to dry-run and refuse live calls unless `confirm: true` ## Branding `community-icon.svg` is Plaid's official mark from the [plaid.com](https://plaid.com) header (same path as Wikimedia `File:Plaid logo.svg`), on Plaid black `#111111`. Plaid® is a trademark of Plaid Inc. This package is not affiliated with or endorsed by Plaid. ## Docs - [Plaid API](https://plaid.com/docs/api/) - [Sandbox](https://plaid.com/docs/sandbox/) - [Link](https://plaid.com/docs/link/) - [Transactions sync](https://plaid.com/docs/api/products/transactions/#transactionssync)