[FEATURE] Add Bridge BYOK provider support by falcononrails · Pull Request #2 · cdinnison/ray-finance

falcononrails · 2026-04-13T10:11:12Z

Summary

add Bridge as a second BYOK banking provider alongside Plaid
introduce a small provider layer so link + sync dispatch by institution provider
keep managed mode Plaid-only and preserve existing Plaid behavior

What changed

extend ray setup config to store optional Bridge BYOK credentials and a reusable default Bridge external_user_id
make ray link provider-aware, with Bridge support for:
- auto-create/reuse of a Ray-managed Bridge user
- linking with an existing external_user_id
- reconnect/update flows for Bridge items that require user action
add provider-aware institution state via provider, provider_user_id, and provider_state
add Bridge account + transaction sync into the existing generic accounts and transactions tables
surface Bridge reconnect-needed state in ray accounts and ray doctor

Notes

Bridge is BYOK-only in this pass
Bridge Connect completion is detected by polling rather than a localhost callback
this scope intentionally excludes Bridge holdings/stocks, liabilities enrichment, recurring detection, and webhooks
the existing src/plaid/* implementation is intentionally left in place for this PR; the provider boundary is added here, and moving Plaid fully under src/providers/ should be done in a follow-up refactor to keep this diff reviewable and lower-risk

Discussion

issue: Add Bridge as a BYOK banking provider alongside Plaid #3

Validation

npm run build
npm test

vercel · 2026-04-13T10:11:17Z

@falcononrails is attempting to deploy a commit to the Otherness Team on Vercel.

A member of the Team first needs to authorize it.

cdinnison

Thanks for this contribution — really well-structured PR overall. The provider abstraction is clean, the Bridge client is well-factored (injectable fetch, pagination, proper error class), and the incremental approach of wrapping Plaid rather than moving it is the right call for keeping this reviewable.

Test coverage is solid — the deleted transaction, incremental sync cursor, and reconnect state tests are thorough. The import-existing-items flow is a nice UX touch.

A few things to address before merging — see inline comments. The main ones are:

Stale provider_state for reconnect messages — the daily-sync reconnect block reads pre-sync state and is redundant with result.message
getItem fallback catches all errors — should scope to 404
formatMoney tests were gutted — need to still verify actual output for default locale
Inline import() types — should use top-level imports
bridgeClientId masked as password — client IDs aren't secret

Also a couple of non-blocking notes on currency formatting scope and the polling timeout.

cdinnison · 2026-04-14T05:42:42Z

+      if (result.reconnectRequired && providerKey === "bridge") {
+        const state = parseProviderState<BridgeProviderState>(inst.provider_state);
+        const reconnectMessage = describeBridgeProviderState(state);
+        if (reconnectMessage) console.log(`  ${reconnectMessage}`);


This block is redundant — syncBridgeInstitution already sets result.message with the reconnect description when reconnectRequired is true (see index.ts:405). And it has a bug: it reads the pre-sync inst.provider_state rather than the state that was just updated in the DB by syncInstitution.

Suggestion: drop this entire if (result.reconnectRequired && providerKey === "bridge") block. The result.message line above it already handles this.

Fixed in 3f06cc9. I removed that redundant reconnect block from daily sync so it now relies on provider sync result messaging only.

cdinnison · 2026-04-14T05:42:42Z

+  }
+
+  const accessToken = await client.ensureAccessToken(externalUserId);
+  const item = await client.getItem(accessToken, institution.item_id).catch(async () => {


This .catch() swallows all errors — network failures, auth errors, rate-limits — and falls back to listing all items. If getItem fails for a non-404 reason, listItems will likely fail too, just with a more confusing error.

Suggestion: scope the catch to 404 only:

const item = await client.getItem(accessToken, institution.item_id).catch(async (err) => { if (!(err instanceof BridgeApiError && err.status === 404)) throw err; const items = await client.listItems(accessToken); // ... });

Fixed in 3f06cc9. The getItem fallback now only catches BridgeApiError 404; all other errors are re-thrown.

cdinnison · 2026-04-14T05:42:42Z

+}
+
+function upsertBridgeInstitution(
+  db: import("../types.js").Database,


Database and InstitutionRecord are used throughout this file via inline import("../types.js") annotations (~10 occurrences). Since InstitutionProvider is already imported from types.js at the top, just add them to that import:

import type { InstitutionProvider, Database, InstitutionRecord } from "../types.js";

Fixed in 3f06cc9. I imported Database and InstitutionRecord at the top-level type import and removed inline import() type annotations.

cdinnison · 2026-04-14T05:42:42Z

+  },
+): Promise<BridgeItem[]> {
+  const previousById = new Map(options.previousItems.map(item => [String(item.id), item]));
+  const deadline = Date.now() + 10 * 60 * 1000;


Non-blocking: 10-minute polling at 3-second intervals with no escape hatch — if the user abandons the Bridge Connect flow, they're stuck waiting. Consider printing a hint like "Press Ctrl+C to cancel" alongside the spinner, or shortening the timeout.

Addressed in 3f06cc9. Added an explicit "Press Ctrl+C to cancel waiting" hint before polling Bridge Connect completion.

cdinnison · 2026-04-14T05:42:42Z

      },
+      {
+        theme,
+        type: "password",


Client IDs aren't secret — this should use type: "input" instead of type: "password" so the user can see what they're typing. Keep bridgeClientSecret as password.

Fixed in 3f06cc9. bridgeClientId prompt now uses type: input (bridgeClientSecret remains password).

cdinnison · 2026-04-14T05:42:42Z

-  it("formats negative as absolute", () => expect(formatMoney(-99)).toBe("$99.00"));
-  it("formats zero", () => expect(formatMoney(0)).toBe("$0.00"));
+  it("formats positive", () => {
+    expect(formatMoney(1234.5)).toMatch(/\d/);


These assertions are too weak now — toMatch(/\d/) and toContain("1") pass for almost any string containing a number. The currency formatting change is fine, but the tests should still verify the default output.

Suggestion: set config.displayLocale = "en-US" and config.displayCurrency = "USD" in the test (with afterEach cleanup) and assert toBe("$1,234.50"). That way you're testing the formatting logic, not just that a digit exists.

Fixed in 3f06cc9. I strengthened formatMoney tests by forcing en-US/USD in test setup and asserting exact outputs ($1,234.50, $99.00, $0.00), with cleanup after each test.

cdinnison · 2026-04-14T05:42:42Z

@@ -0,0 +1,109 @@
+import { config } from "./config.js";


Non-blocking: this module is a nice addition, but it changes output for all users (not just Bridge), and the displayLocale/displayCurrency config options aren't exposed in ray setup. Users can only set them via env vars or editing the config file directly. Consider either adding them as optional fields in setup, or at least mentioning the env vars (RAY_DISPLAY_LOCALE, RAY_DISPLAY_CURRENCY) in ray doctor or help output so they're discoverable.

Addressed in 3f06cc9. I added display format discoverability in ray doctor, including explicit mention of RAY_DISPLAY_LOCALE and RAY_DISPLAY_CURRENCY.

falcononrails · 2026-04-17T09:11:56Z

@cdinnison I pushed follow-up commit 3f06cc9 addressing all inline review items.

removed redundant Bridge reconnect message block in daily sync
narrowed getItem fallback to BridgeApiError 404 only
replaced inline import() type annotations with top-level type imports
added Ctrl+C cancel hint while polling Bridge Connect
switched bridgeClientId setup prompt to input
strengthened formatMoney tests with deterministic en-US/USD assertions
added display locale/currency env var discoverability in ray doctor

Verified with npm run build and npm test.

cdinnison · 2026-04-27T21:28:43Z

Thank you! I've been out sick so will review ASAP. appreciate the follow-ups

falcononrails changed the title ~~Add Bridge BYOK provider support~~ [FEATURE] Add Bridge BYOK provider support Apr 13, 2026

falcononrails force-pushed the feature/bridge-byok branch 3 times, most recently from d116da7 to e3000a0 Compare April 13, 2026 15:38

cdinnison requested changes Apr 14, 2026

View reviewed changes

adamjgmiller mentioned this pull request Apr 16, 2026

Add ray import-apple for manual Apple Card CSV imports #8

Open

falcononrails added 2 commits April 17, 2026 11:37

[FEATURE] Add Bridge BYOK provider support

70552ad

[BUGFIX] Address Bridge PR review feedback

fcc60af

falcononrails force-pushed the feature/bridge-byok branch from 3f06cc9 to fcc60af Compare April 17, 2026 09:39

falcononrails requested a review from cdinnison April 19, 2026 10:38

Conversation

falcononrails commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Notes

Discussion

Validation

Uh oh!

vercel Bot commented Apr 13, 2026

Uh oh!

cdinnison left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

falcononrails commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cdinnison commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

falcononrails commented Apr 13, 2026 •

edited

Loading

falcononrails commented Apr 17, 2026 •

edited

Loading