ray-finance 0.5.0 → 0.5.1

package/README.md

@@ -118,6 +118,12 @@ Bring your own AI and banking credentials. Free forever.
 4. Link your accounts — checking, savings, credit cards, investments, loans, mortgage
 5. Done
 
+**Plaid OAuth banks (Chase, Capital One, etc.)** redirect through their bank's site, so you must:
+- Set `PLAID_REDIRECT_URI=http://localhost:9876/oauth-return` (use your `RAY_PORT` if you changed it).
+- In your [Plaid dashboard](https://dashboard.plaid.com) → Team Settings → API → Allowed redirect URIs, register the same URL. `http://localhost` is allowed by Plaid for local dev.
+
+**Plaid optional products** — Investments and Liabilities are off by default. If your Plaid account is approved for them, opt in with `PLAID_OPTIONAL_PRODUCTS=investments,liabilities`. Leaving them on without approval will cause `ray link` to fail.
+
 ## Commands
 
 Run `ray --help` to see all available commands.
@@ -219,6 +225,8 @@ RAY_MODEL=                  # Model name (e.g. claude-sonnet-4-6, gpt-4o, llama3
 PLAID_CLIENT_ID=            # Plaid client ID (US/Canada banks)
 PLAID_SECRET=               # Plaid secret key
 PLAID_ENV=production        # Plaid environment
+PLAID_REDIRECT_URI=         # Required for OAuth banks (Chase, Capital One). e.g. http://localhost:9876/oauth-return — must also be registered in your Plaid dashboard under Team Settings → API → Allowed redirect URIs
+PLAID_OPTIONAL_PRODUCTS=    # Comma-separated, e.g. investments,liabilities — only enable if your Plaid account is approved for them
 BRIDGE_CLIENT_ID=           # Bridge client ID (European banks)
 BRIDGE_CLIENT_SECRET=       # Bridge client secret
 BRIDGE_DEFAULT_EXTERNAL_USER_ID= # Optional: reuse an existing Bridge external_user_id

package/dist/config.d.ts

@@ -11,6 +11,8 @@ export interface RayConfig {
     plaidClientId: string;
     plaidSecret: string;
     plaidEnv: string;
+    plaidRedirectUri: string;
+    plaidOptionalProducts: string[];
     bridgeClientId: string;
     bridgeClientSecret: string;
     bridgeDefaultExternalUserId: string;

package/dist/config.js

@@ -49,6 +49,12 @@ function buildConfig() {
         plaidClientId: file.plaidClientId || process.env.PLAID_CLIENT_ID || "",
         plaidSecret: file.plaidSecret || process.env.PLAID_SECRET || "",
         plaidEnv: file.plaidEnv || process.env.PLAID_ENV || "production",
+        plaidRedirectUri: file.plaidRedirectUri || process.env.PLAID_REDIRECT_URI || "",
+        plaidOptionalProducts: file.plaidOptionalProducts ||
+            (process.env.PLAID_OPTIONAL_PRODUCTS || "")
+                .split(",")
+                .map(s => s.trim())
+                .filter(Boolean),
         bridgeClientId: file.bridgeClientId || process.env.BRIDGE_CLIENT_ID || "",
         bridgeClientSecret: file.bridgeClientSecret || process.env.BRIDGE_CLIENT_SECRET || "",
         bridgeDefaultExternalUserId: file.bridgeDefaultExternalUserId || process.env.BRIDGE_DEFAULT_EXTERNAL_USER_ID || "",

package/dist/plaid/link.js

@@ -8,13 +8,21 @@ export function getCountryCodes() {
         .map(c => CountryCode[c]);
     return codes.length > 0 ? codes : [CountryCode.Us];
 }
+function resolveOptionalProducts() {
+    const valid = new Set(Object.values(Products));
+    return config.plaidOptionalProducts
+        .map(p => p.toLowerCase())
+        .filter(p => valid.has(p));
+}
 /** Create a link token for initializing Plaid Link */
 export async function createLinkToken(products = [Products.Transactions]) {
+    const optional = resolveOptionalProducts();
     const resp = await plaidClient.linkTokenCreate({
         user: { client_user_id: "ray-user" },
         client_name: "Ray Finance",
         products,
-        optional_products: [Products.Investments, Products.Liabilities],
+        ...(optional.length > 0 ? { optional_products: optional } : {}),
+        ...(config.plaidRedirectUri ? { redirect_uri: config.plaidRedirectUri } : {}),
         country_codes: getCountryCodes(),
         language: "en",
     });

package/dist/public/link.html

@@ -60,7 +60,8 @@
     button:hover { opacity: 0.85; }
     button:disabled { opacity: 0.3; cursor: not-allowed; }
     .success { color: #34d399; font-weight: 500; }
-    .error { color: #f87171; font-size: 13px; margin-top: 16px; }
+    .error { color: #f87171; font-size: 13px; margin-top: 16px; line-height: 1.5; }
+    .error a { color: #f87171; text-decoration: underline; }
     .success-title-check {
       width: 18px;
       height: 18px;
@@ -136,10 +137,17 @@
         });
         if (!res.ok) {
           const data = await res.json().catch(() => ({}));
-          throw new Error(data.error || 'Failed to connect. Please run "ray link" again.');
+          const err = new Error(data.error || 'Failed to connect. Please run "ray link" again.');
+          err.code = data.error_code;
+          throw err;
         }
         const { link_token } = await res.json();
 
+        // Persist link_token + session for OAuth redirect flow (Chase, Capital One, etc.)
+        try {
+          localStorage.setItem('ray_plaid_link', JSON.stringify({ link_token, session_id: sessionId }));
+        } catch {}
+
         linkHandler = Plaid.create({
           token: link_token,
           onSuccess: async (publicToken, metadata) => {
@@ -156,7 +164,13 @@
                   institution_id: metadata.institution?.institution_id || null,
                 }),
               });
-              if (!resp.ok) throw new Error('Exchange failed');
+              if (!resp.ok) {
+                const data = await resp.json().catch(() => ({}));
+                const err = new Error(data.error || 'Exchange failed');
+                err.code = data.error_code;
+                throw err;
+              }
+              try { localStorage.removeItem('ray_plaid_link'); } catch {}
               const result = await resp.json();
               document.getElementById('connect-view').style.display = 'none';
               document.getElementById('success-view').style.display = 'block';
@@ -171,7 +185,7 @@
                 logoEl.style.display = 'inline-block';
               }
             } catch (e) {
-              showError('Failed to link account. Please try again with "ray link".');
+              showError(e.message || 'Failed to link account. Please try again with "ray link".', e.code);
             }
           },
           onExit: (err) => {
@@ -182,13 +196,29 @@
         linkHandler.open();
         document.getElementById('connect-view').style.display = 'none';
       } catch (e) {
-        showError(e.message || 'This link has expired. Please run "ray link" again.');
+        showError(e.message || 'This link has expired. Please run "ray link" again.', e.code);
+      }
+    }
+
+    function hintForCode(code) {
+      switch (code) {
+        case 'INVALID_PRODUCT':
+        case 'PRODUCTS_NOT_SUPPORTED':
+        case 'PRODUCT_NOT_READY':
+          return 'Your Plaid account isn\'t approved for this product. Request access at <a href="https://dashboard.plaid.com" target="_blank" rel="noopener">dashboard.plaid.com</a> → Account → Products.';
+        case 'INVALID_API_KEYS':
+          return 'Check your PLAID_CLIENT_ID and PLAID_SECRET in ~/.ray/config.json.';
+        case 'INVALID_FIELD':
+          return 'If your bank uses OAuth (Chase, Capital One), set PLAID_REDIRECT_URI and register the same URL in your Plaid dashboard.';
+        default:
+          return '';
       }
     }
 
-    function showError(msg) {
+    function showError(msg, code) {
       const el = document.getElementById('error');
-      el.textContent = msg;
+      const hint = hintForCode(code);
+      el.innerHTML = msg.replace(/</g, '&lt;') + (hint ? '<br><br>' + hint : '');
       el.style.display = 'block';
     }
 

package/dist/public/oauth-return.html

@@ -0,0 +1,121 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="icon" href="/favicon.png">
+  <title>Ray — Returning from your bank</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
+    body {
+      font-family: 'SF Mono', SFMono-Regular, ui-monospace, 'DejaVu Sans Mono', Menlo, Consolas, monospace;
+      background: #202023;
+      color: #ffffff;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      padding: 24px;
+    }
+    .top-logo {
+      position: absolute;
+      top: 32px;
+      left: 50%;
+      transform: translateX(-50%);
+    }
+    .top-logo img { height: 20px; filter: invert(1); }
+    .container { text-align: center; max-width: 400px; width: 100%; }
+    h1 { font-size: 16px; font-weight: 500; margin-bottom: 8px; color: #ffffff; letter-spacing: -0.01em; }
+    p { font-size: 13px; color: #9c9da1; margin-bottom: 24px; line-height: 1.6; }
+    .error { color: #f87171; font-size: 13px; margin-top: 16px; line-height: 1.5; }
+    .error a { color: #f87171; text-decoration: underline; }
+    .spinner {
+      display: inline-block;
+      width: 24px;
+      height: 24px;
+      border: 2px solid rgba(255, 255, 255, 0.1);
+      border-top-color: #9c9da1;
+      border-radius: 50%;
+      animation: spin 0.8s linear infinite;
+      margin-bottom: 20px;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+  </style>
+</head>
+<body>
+  <div class="top-logo"><img src="/ray-logo-dark.png" alt="Ray"></div>
+  <div class="container">
+    <div id="view">
+      <div class="spinner"></div>
+      <h1>Finishing connection</h1>
+      <p>Completing OAuth handoff with your bank...</p>
+      <div id="error" class="error" style="display:none"></div>
+    </div>
+  </div>
+
+  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
+  <script>
+    function showError(msg) {
+      const el = document.getElementById('error');
+      el.innerHTML = msg;
+      el.style.display = 'block';
+    }
+
+    async function resume() {
+      let stored;
+      try { stored = JSON.parse(localStorage.getItem('ray_plaid_link') || 'null'); } catch {}
+      if (!stored || !stored.link_token || !stored.session_id) {
+        showError('OAuth session not found. Please run "ray link" again.');
+        return;
+      }
+
+      if (typeof Plaid === 'undefined') {
+        let attempts = 0;
+        await new Promise((resolve, reject) => {
+          const check = setInterval(() => {
+            if (typeof Plaid !== 'undefined') { clearInterval(check); resolve(); }
+            else if (++attempts > 50) { clearInterval(check); reject(new Error('Failed to load Plaid SDK.')); }
+          }, 100);
+        });
+      }
+
+      const handler = Plaid.create({
+        token: stored.link_token,
+        receivedRedirectUri: window.location.href,
+        onSuccess: async (publicToken, metadata) => {
+          document.getElementById('view').innerHTML = '<div class="spinner"></div><h1>Linking</h1><p>Syncing ' + (metadata.institution?.name || 'account') + '...</p>';
+          try {
+            const resp = await fetch('/api/exchange', {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                public_token: publicToken,
+                session_id: stored.session_id,
+                institution_name: metadata.institution?.name || 'Bank Account',
+                institution_id: metadata.institution?.institution_id || null,
+              }),
+            });
+            if (!resp.ok) {
+              const data = await resp.json().catch(() => ({}));
+              throw new Error(data.error || 'Exchange failed');
+            }
+            try { localStorage.removeItem('ray_plaid_link'); } catch {}
+            const result = await resp.json();
+            const name = result.institution_name || metadata.institution?.name || 'Account';
+            document.getElementById('view').innerHTML = '<h1 style="color:#34d399">' + name + ' Connected</h1><p>Syncing transactions. You can close this page.</p>';
+          } catch (e) {
+            showError(e.message || 'Failed to link account. Please run "ray link" again.');
+          }
+        },
+        onExit: (err) => {
+          if (err) showError('Connection cancelled. Please run "ray link" again.');
+        },
+      });
+      handler.open();
+    }
+
+    resume().catch(e => showError(e.message || 'Unexpected error. Please run "ray link" again.'));
+  </script>
+</body>
+</html>

package/dist/server.js

@@ -27,6 +27,20 @@ function isRateLimited(ip) {
     entry.count++;
     return entry.count > RATE_LIMIT_MAX;
 }
+function plaidErrorJson(error, fallback) {
+    const data = error?.response?.data;
+    const code = data?.error_code;
+    const type = data?.error_type;
+    let message = data?.display_message ||
+        data?.error_message ||
+        error?.message ||
+        fallback;
+    if (code === "INVALID_API_KEYS") {
+        message =
+            "Plaid credentials error — make sure you're using production (not sandbox) keys. Check PLAID_CLIENT_ID and PLAID_SECRET in ~/.ray/config.json.";
+    }
+    return { error: message, error_code: code, error_type: type };
+}
 export function startLinkServer() {
     const app = express();
     app.use(express.json());
@@ -62,6 +76,10 @@ export function startLinkServer() {
         }
         res.sendFile(resolve(__dirname, "public", "link.html"));
     });
+    // OAuth redirect return page (Chase, Capital One, etc. send the user here after bank login)
+    app.get("/oauth-return", (_req, res) => {
+        res.sendFile(resolve(__dirname, "public", "oauth-return.html"));
+    });
     // Create link token
     app.post("/api/link-token", async (req, res) => {
         try {
@@ -74,16 +92,9 @@ export function startLinkServer() {
             res.json({ link_token: linkToken });
         }
         catch (error) {
-            console.error("Link token error:", error.message);
-            const plaidStatus = error?.response?.status;
-            if (plaidStatus === 400 || plaidStatus === 401 || plaidStatus === 403) {
-                res.status(500).json({
-                    error: "Plaid credentials error — make sure you're using production (not sandbox) keys. Check PLAID_CLIENT_ID and PLAID_SECRET in ~/.ray/config.json.",
-                });
-            }
-            else {
-                res.status(500).json({ error: "Failed to create link token: " + (error.message || "unknown error") });
-            }
+            const body = plaidErrorJson(error, "Failed to create link token");
+            console.error("Link token error:", body.error_code || "", error?.response?.data || error.message);
+            res.status(500).json(body);
         }
     });
     // Exchange public token
@@ -222,8 +233,9 @@ export function startLinkServer() {
             resolveComplete();
         }
         catch (error) {
-            console.error("Token exchange error:", error.message);
-            res.status(500).json({ error: "Failed to link account" });
+            const body = plaidErrorJson(error, "Failed to link account");
+            console.error("Token exchange error:", body.error_code || "", error?.response?.data || error.message);
+            res.status(500).json(body);
         }
     });
     const server = app.listen(config.port, "127.0.0.1");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ray-finance",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Local-first CLI that turns your bank data into a personal AI financial advisor",
   "type": "module",
   "license": "MIT",