@hakimelek/monarchmoney 0.2.0 → 0.3.0

package/README.md

@@ -117,6 +117,8 @@ All methods return **typed responses**. Hover over any method in your editor for
 | `getSubscriptionDetails()` | `GetSubscriptionDetailsResponse` | Plan status (trial, premium, etc.) |
 | `getTransactionsSummary()` | `GetTransactionsSummaryResponse` | Aggregate summary |
 | `getTransactions(options?)` | `GetTransactionsResponse` | Transactions with full filtering |
+| `getAllTransactions(options?)` | `Transaction[]` | All matching transactions (auto-paginates) |
+| `getTransactionPages(options?)` | `AsyncGenerator<Transaction[]>` | Async generator yielding pages |
 | `getTransactionCategories()` | `GetTransactionCategoriesResponse` | All categories |
 | `getTransactionCategoryGroups()` | `GetTransactionCategoryGroupsResponse` | Category groups |
 | `getTransactionDetails(id)` | typed response | Single transaction detail |
@@ -194,17 +196,102 @@ const mm = new MonarchMoney({
   sessionFile: ".mm/mm_session.json", // session file path
   timeout: 10,                        // API timeout in seconds
   token: "pre-existing-token",        // skip login
+  retry: {
+    maxRetries: 3,                    // retry on 429/5xx (default: 3, set 0 to disable)
+    baseDelayMs: 500,                 // base delay with exponential backoff + jitter
+  },
+  rateLimit: {
+    requestsPerSecond: 10,            // token-bucket throttle (default: 0 = unlimited)
+  },
 });
 
 mm.setTimeout(30); // change timeout later
 ```
 
+Retry automatically handles transient failures (429 Too Many Requests, 500, 502, 503, 504) with exponential backoff and jitter. The `Retry-After` header is respected on 429 responses.
+
+## Auto-Pagination
+
+`getTransactions()` returns a single page. For large datasets, use the auto-pagination helpers:
+
+```ts
+// Async generator — yields one page at a time (memory-efficient)
+for await (const page of mm.getTransactionPages({ startDate: "2025-01-01", endDate: "2025-12-31" })) {
+  for (const tx of page) {
+    console.log(tx.merchant?.name, tx.amount);
+  }
+}
+
+// Or collect everything into a flat array
+const all = await mm.getAllTransactions({
+  startDate: "2025-01-01",
+  endDate: "2025-12-31",
+  pageSize: 100, // transactions per page (default: 100)
+});
+console.log(`${all.length} total transactions`);
+```
+
+Both methods accept the same filter options as `getTransactions()` (date range, category, account, tags, etc.).
+
+## Refresh Progress
+
+Track account refresh progress with the `onProgress` callback:
+
+```ts
+await mm.requestAccountsRefreshAndWait({
+  timeout: 300,
+  delay: 10,
+  onProgress: ({ completed, total, elapsedMs }) => {
+    console.log(`${completed}/${total} accounts refreshed (${(elapsedMs / 1000).toFixed(0)}s)`);
+  },
+});
+```
+
+## MCP Server (AI Agent Integration)
+
+This package includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server with **30 tools**, making your Monarch Money data accessible to AI assistants like Claude Desktop, Cursor, and any MCP-compatible client.
+
+### Setup
+
+1. Get your Monarch Money auth token by logging in with the library (see [Authentication](#authentication)) and saving `mm.token`.
+
+2. Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "monarch-money": {
+      "command": "npx",
+      "args": ["@hakimelek/monarchmoney"],
+      "env": {
+        "MONARCH_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+Or run it directly:
+
+```bash
+MONARCH_TOKEN=your-token npx @hakimelek/monarchmoney
+```
+
+### Available Tools
+
+**Read (18 tools):** `get_accounts`, `get_account_holdings`, `get_account_history`, `get_account_type_options`, `get_recent_account_balances`, `get_aggregate_snapshots`, `get_institutions`, `get_budgets`, `get_subscription_details`, `get_transactions`, `get_transactions_summary`, `get_transaction_details`, `get_transaction_categories`, `get_transaction_category_groups`, `get_transaction_tags`, `get_cashflow`, `get_cashflow_summary`, `get_recurring_transactions`
+
+**Write (12 tools):** `create_transaction`, `update_transaction`, `delete_transaction`, `create_manual_account`, `update_account`, `delete_account`, `refresh_accounts`, `is_refresh_complete`, `set_budget_amount`, `create_transaction_tag`, `set_transaction_tags`, `create_transaction_category`
+
+Every tool has typed parameters with descriptions, so AI agents know exactly what arguments to pass.
+
 ## Project Structure
 
 ```
 src/
   index.ts      — public exports
   client.ts     — MonarchMoney class with all API methods
+  mcp.ts        — MCP server (30 tools for AI agents)
   errors.ts     — error classes (MonarchMoneyError hierarchy)
   endpoints.ts  — API URL constants
   queries.ts    — all GraphQL query/mutation strings
@@ -245,6 +332,47 @@ Set a password on your Monarch account at [Settings > Security](https://app.mona
 
 Monarch requires email verification for new/unrecognized devices. After login, save the session token with `mm.saveSession()` or store `mm.token` — subsequent runs will reuse it without re-authenticating.
 
+## How This Library Compares
+
+There are several unofficial Monarch Money integrations. Here's how `@hakimelek/monarchmoney` stacks up.
+
+### Landscape
+
+| | **@hakimelek/monarchmoney** | **monarch-money-api** (pbassham) | **monarchmoney** (keithah) | **monarchmoney** (hammem) |
+|---|---|---|---|---|
+| **Platform** | Node.js / TypeScript | Node.js / JavaScript | Node.js / TypeScript | Python |
+| **npm weekly downloads** | — | ~440 | ~130 | N/A (pip: ~103K/mo) |
+| **Runtime deps** | **1** (speakeasy) | 5 | 7 | 3 |
+| **TypeScript types** | Full (every response) | None | Yes | N/A |
+| **Email OTP flow** | Yes | No | No | No |
+| **MFA / TOTP** | Yes | Yes | Yes | Yes |
+| **Session persistence** | Yes (0o600 perms) | Yes | Yes (AES-256) | Yes |
+| **Interactive CLI login** | Yes | Yes | Yes | Yes |
+| **HTTP client** | Native `fetch` | node-fetch | node-fetch + graphql-request | aiohttp |
+| **Error hierarchy** | 4 typed exceptions | Generic throws | Generic throws | 1 exception |
+| **Read methods** | 20 | 15 | ~20 | ~16 |
+| **Write methods** | 14 | 9 | ~12 | ~10 |
+| **Rate limiting** | Yes | No | Yes | No |
+| **Retry with backoff** | Yes | No | Yes | No |
+| **Auto-pagination** | Yes | No | No | No |
+| **Dual CJS + ESM** | Yes | No | Yes | No |
+| **Refresh progress events** | Yes | No | No | No |
+| **Built-in MCP server** | Yes (30 tools) | No | No | No |
+
+### Where this library wins
+
+**Minimal footprint.** One runtime dependency vs 5-7 in the JS/TS alternatives. Native `fetch` means zero HTTP polyfills on Node 18+.
+
+**Email OTP support.** Monarch now requires email verification for unrecognized devices, even when MFA is off. This is the only Node.js library that handles the full `EmailOtpRequiredException` → `submitEmailOtp()` flow. Without it, automated scripts break on first login from a new environment.
+
+**Typed everything.** Every API response has a dedicated TypeScript interface — 50+ exported types covering accounts, transactions, holdings, cashflow, budgets, recurring items, and mutations. The `monarch-money-api` package has no types at all.
+
+**Structured error handling.** Four distinct exception classes (`LoginFailedException`, `RequireMFAException`, `EmailOtpRequiredException`, `RequestFailedException`) with error codes and status codes. Competitors throw generic errors or strings.
+
+**Broader write coverage.** Includes `updateTransaction()`, `setBudgetAmount()`, `uploadAccountBalanceHistory()`, `getCashflow()`, `getCashflowSummary()`, and `getRecurringTransactions()` — all missing from `monarch-money-api`.
+
+**Clean, flat API.** One class, direct methods, no sub-objects or verbosity levels to learn. Import `MonarchMoney`, call methods, get typed results.
+
 ## Contributing
 
 Contributions welcome. Please ensure TypeScript compiles cleanly (`npm run build`) and tests pass (`npm test`).