Skip to content
← Public packages

@kody/plaid

Read Plaid identity, items, accounts, balances, and transactions with sandbox-friendly secret-backed helpers.

FollowFork

Files

AGENTS.md

116 lines · 3.8 KB · Markdown

@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

NamePurpose
plaidClientIdDashboard client id; hosts sandbox.plaid.com, production.plaid.com
plaidSecretDashboard secret (same hosts)
plaidAccessTokenOptional 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

ExportImport
root dispatcher (default smoke-test)kody:@kody/plaid
itemkody:@kody/plaid/item
accountskody:@kody/plaid/accounts
identitykody:@kody/plaid/identity
transactionskody:@kody/plaid/transactions
institutionskody:@kody/plaid/institutions
linkkody:@kody/plaid/link
sandboxkody:@kody/plaid/sandbox
smoke-testkody:@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.