@this-npm-test-org/connection-plaid 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @this-npm-test-org/connection-plaid
+
+Read-only bank account access via Plaid for amodal IR agents. Pulls transactions + balances for fund operating accounts so the reconcile-bank-activity intent can match observed bank movements against expected distributions and contributions.
+
+The platform never moves money. JPMorgan (or whichever bank) executes the wires; this connection only reads the bank's record of what happened.
+
+## Auth
+
+Set `PLAID_ACCESS_TOKEN` to the access_token obtained via Plaid Link.
+
+For v1 local dev: one shared token works across all linked accounts on the Item. Production: one token per Item.
+
+## Tools generated
+
+Auto-generated from the Plaid OpenAPI spec, scoped via `connections/plaid/spec.json` `filter.include_paths`:
+
+- `plaid__transactions__sync` — incremental transaction sync
+- `plaid__transactions__get` — date-range transaction fetch
+- `plaid__accounts__get` — list accounts on the Item
+- `plaid__accounts__balance__get` — real-time balance check
+- `plaid__item__get` — Item + institution metadata
+
+See `connections/plaid/access.json` for the field-restriction policy.

package/connections/plaid/access.json

@@ -0,0 +1,72 @@
+{
+  "endpoints": {
+    "POST /transactions/sync": {
+      "returns": ["added", "modified", "removed", "next_cursor", "has_more"]
+    },
+    "POST /transactions/get": {
+      "returns": ["transactions", "total_transactions", "accounts"]
+    },
+    "POST /accounts/get": {
+      "returns": ["accounts", "item"]
+    },
+    "POST /accounts/balance/get": {
+      "returns": ["accounts"]
+    },
+    "POST /item/get": {
+      "returns": ["item", "status"]
+    }
+  },
+  "fieldRestrictions": [
+    {
+      "entity": "account",
+      "field": "account_id",
+      "policy": "retrieve",
+      "sensitivity": "low",
+      "reason": "Plaid-internal id, safe to log"
+    },
+    {
+      "entity": "account",
+      "field": "mask",
+      "policy": "retrieve",
+      "sensitivity": "low",
+      "reason": "Last-four digits only — what's already shown on packets and wire instructions"
+    },
+    {
+      "entity": "account",
+      "field": "official_name",
+      "policy": "retrieve",
+      "sensitivity": "low",
+      "reason": "Bank-issued display name, safe"
+    },
+    {
+      "entity": "transaction",
+      "field": "merchant_name",
+      "policy": "retrieve",
+      "sensitivity": "low",
+      "reason": "Counterparty name — needed for matching"
+    },
+    {
+      "entity": "transaction",
+      "field": "location",
+      "policy": "never_retrieve",
+      "sensitivity": "PII",
+      "reason": "Geolocation isn't needed for fund-account reconciliation"
+    },
+    {
+      "entity": "transaction",
+      "field": "personal_finance_category",
+      "policy": "retrieve",
+      "sensitivity": "low",
+      "reason": "Plaid's categorization — helps the matcher disambiguate"
+    }
+  ],
+  "rowScoping": {
+    "accounts": {
+      "account_id": {
+        "type": "explicit",
+        "label": "Only accounts the operator has connected via Plaid Link",
+        "from": "fund_bank_accounts.plaid_account_id"
+      }
+    }
+  }
+}

package/connections/plaid/entities.md

@@ -0,0 +1,13 @@
+# Entities
+
+## Item
+A connected institution (one row per bank the operator has linked via Plaid Link). Maps 1:N to accounts.
+
+## Account
+A specific bank account on an Item. Plaid's `account_id` joins to `fund_bank_accounts.plaid_account_id`. The `mask` is the last 4 of the account number — what's already printed on packets and stored as `account_number_last4`.
+
+## Transaction
+A posted (or pending) bank movement. The reconciler reads these and writes one `bank_transactions` row per posted transaction. `amount` is positive for debits (money out) in Plaid's convention; the reconciler normalizes to `direction: "debit" | "credit"` on the way in.
+
+## Cursor
+A per-account opaque token tracking the last successful sync point. Stored on `fund_bank_accounts` directly (one cursor per account is sufficient for v1).

package/connections/plaid/rules.md

@@ -0,0 +1,19 @@
+# Rules
+
+## Read-only, by design
+- The platform never moves money. Plaid here is *only* for reading the bank's record of what happened. Any future write-side path (ACH initiation via `processor/*`, balance-locking, etc.) is a separate decision and should not be added by widening this connection's filter.
+
+## Rate limits
+- Plaid throttles at the per-Item level. Default development tier is generous (no published per-minute cap), but production institutions can rate-limit `/transactions/sync` to ~5 rps per Item.
+- The reconciler runs hourly (`sync.frequency = hourly` in spec.json). For local dev, the operator can call it on demand via the "Reconcile now" button on /distributions.
+
+## Cursor management
+- `/transactions/sync` is cursor-based. The reconciler stores the latest `next_cursor` keyed by `fund_bank_accounts.account_id` (today: in the account row itself; future: a dedicated cursor table if multiple consumers need it).
+- After a re-link (the operator runs Plaid Link again because the token expired), the cursor must be cleared — Plaid issues a new Item id under the hood.
+
+## Matching policy
+- The reconciler does NOT auto-confirm transactions it can't unambiguously match. Ambiguous cases (multiple distributions of the same amount on the same day) become `unmatched_bank_transaction` suggestions for human review.
+- When the matcher flips a distribution `approved → confirmed`, attribution is `confirmed_by: "plaid:reconciler"`. The operator can still manually mark sent/confirmed before the reconciler runs — manual flips are not overwritten.
+
+## What an LP can see
+- Nothing. This connection is operator-side. LP-facing portal screens do not surface raw Plaid data; they show capital-account roll-forwards derived from the (post-reconciled) distribution + contribution rows.

package/connections/plaid/spec.json

@@ -0,0 +1,27 @@
+{
+  "description": "Read-only bank transactions, balances, and account metadata via Plaid. Used by reconcile-bank-activity to match wire activity against expected distributions and contributions.",
+  "type": "connection",
+  "specUrl": "https://raw.githubusercontent.com/plaid/plaid-openapi/master/2020-09-14.yml",
+  "format": "openapi",
+  "auth": {
+    "type": "bearer",
+    "token": "env:PLAID_ACCESS_TOKEN",
+    "header": "Authorization",
+    "prefix": "Bearer"
+  },
+  "baseUrl": "https://production.plaid.com",
+  "sync": {
+    "auto": true,
+    "frequency": "hourly",
+    "notify_drift": false
+  },
+  "filter": {
+    "include_paths": [
+      "/transactions/sync",
+      "/transactions/get",
+      "/accounts/get",
+      "/accounts/balance/get",
+      "/item/get"
+    ]
+  }
+}

package/connections/plaid/surface.md

@@ -0,0 +1,21 @@
+## Included
+
+### POST /transactions/sync
+Cursor-based incremental sync of bank transactions. The reconciler calls this on a cadence to pull added/modified/removed activity since the last cursor.
+
+### POST /transactions/get
+Date-range fetch of transactions. Fallback path when a cursor is unavailable (first sync, or after an Item re-link).
+
+### POST /accounts/get
+List the accounts associated with an Item (the LP's or fund's connected bank). Used to map a Plaid account_id to a fund_bank_accounts row.
+
+### POST /accounts/balance/get
+Real-time balance check. Read by the dashboard when an operator wants to see fund cash before approving a distribution.
+
+### POST /item/get
+Item metadata + the institution it belongs to (e.g. "JPMorgan Chase"). Used to populate the bank_name on a fund_bank_accounts row.
+
+## Excluded
+
+- `/auth/get`, `/identity/get`, `/processor/*` — these are write-adjacent / payment-rail surfaces. The platform doesn't initiate transfers; JPMorgan does. We only need read-only.
+- `/link/token/create` — handled out-of-band. The operator runs Plaid Link once per account, exchanges the public_token for an access_token, and pastes that into PLAID_ACCESS_TOKEN. Not an agent-side tool.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@this-npm-test-org/connection-plaid",
+  "version": "0.1.0",
+  "files": [
+    "connections"
+  ],
+  "description": "Read-only bank account access via Plaid. Pulls transactions + balances for fund operating accounts so the reconcile-bank-activity intent can match observed bank movements against expected distributions and contributions.",
+  "amodal": {
+    "name": "plaid",
+    "contains": ["connections"],
+    "tags": ["connection", "banking", "read-only"],
+    "description": "Read-only bank transaction + balance sync via Plaid. The platform never moves money; this connection only reads activity off the bank account so the reconciler can flip distribution/contribution status from approved → confirmed when the wire actually lands.",
+    "auth": {
+      "type": "bearer",
+      "envVars": {
+        "PLAID_ACCESS_TOKEN": "Plaid access_token obtained via Plaid Link. Per-account in production; one shared token is fine for v1 local."
+      }
+    },
+    "displayName": "Plaid",
+    "icon": "https://cdn.simpleicons.org/plaid",
+    "category": "Banking",
+    "oauth": null
+  }
+}