@hakimelek/monarchmoney 0.2.0 → 0.3.0

package/dist/cjs/client.js

@@ -0,0 +1,923 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MonarchMoney = void 0;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const readline = __importStar(require("node:readline"));
+const speakeasy_1 = __importDefault(require("speakeasy"));
+const endpoints_js_1 = require("./endpoints.js");
+const errors_js_1 = require("./errors.js");
+const queries = __importStar(require("./queries.js"));
+const SESSION_FILE = ".mm/mm_session.json";
+const DEFAULT_RECORD_LIMIT = 100;
+const USER_AGENT = "MonarchMoneyAPI (https://github.com/hammem/monarchmoney)";
+const ORIGIN = "https://app.monarch.com";
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RATE_LIMIT_RPS = 0; // disabled
+class MonarchMoney {
+    _headers;
+    _sessionFile;
+    _token;
+    _timeout;
+    _maxRetries;
+    _retryBaseDelayMs;
+    _rateLimitRps;
+    _rateLimitTokens;
+    _rateLimitLastRefill;
+    constructor(options = {}) {
+        const { sessionFile = SESSION_FILE, timeout = 10, token } = options;
+        this._headers = {
+            Accept: "application/json",
+            "Client-Platform": "web",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            Origin: ORIGIN,
+            "device-uuid": crypto.randomUUID(),
+            "monarch-client": "monarch-core-web-app-graphql",
+            "monarch-client-version": "v1.0.1668",
+        };
+        if (token) {
+            this._headers["Authorization"] = `Token ${token}`;
+        }
+        this._sessionFile = path.isAbsolute(sessionFile)
+            ? sessionFile
+            : path.resolve(process.cwd(), sessionFile);
+        this._token = token ?? null;
+        this._timeout = timeout * 1000;
+        this._maxRetries = options.retry?.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this._retryBaseDelayMs = options.retry?.baseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+        this._rateLimitRps = options.rateLimit?.requestsPerSecond ?? DEFAULT_RATE_LIMIT_RPS;
+        this._rateLimitTokens = this._rateLimitRps || 1;
+        this._rateLimitLastRefill = Date.now();
+    }
+    /** Timeout for API calls, in seconds. */
+    get timeout() {
+        return this._timeout / 1000;
+    }
+    /** Sets the timeout for API calls, in seconds. */
+    setTimeout(timeoutSecs) {
+        this._timeout = timeoutSecs * 1000;
+    }
+    /** The current auth token, or `null` if not logged in. */
+    get token() {
+        return this._token;
+    }
+    /** Sets the auth token directly (e.g. from an external source). */
+    setToken(token) {
+        this._token = token;
+        this._headers["Authorization"] = `Token ${token}`;
+    }
+    /**
+     * Logs into Monarch Money.
+     *
+     * @param email - Account email address.
+     * @param password - Account password.
+     * @param options.useSavedSession - Load token from disk if available. Default: `true`.
+     * @param options.saveSession - Persist token to disk after login. Default: `true`.
+     * @param options.mfaSecretKey - TOTP secret for automatic MFA (base32). Bypasses MFA prompt.
+     * @throws {RequireMFAException} If MFA is required. Call `multiFactorAuthenticate()` next.
+     * @throws {LoginFailedException} If credentials are invalid.
+     */
+    async login(email, password, options = {}) {
+        const { useSavedSession = true, saveSession = true, mfaSecretKey } = options;
+        if (useSavedSession && fs.existsSync(this._sessionFile)) {
+            this.loadSession(this._sessionFile);
+            return;
+        }
+        if (!email?.trim() || !password?.trim()) {
+            throw new errors_js_1.LoginFailedException("Email and password are required to login when not using a saved session.");
+        }
+        await this._loginUser(email, password, mfaSecretKey);
+        if (saveSession) {
+            this.saveSession(this._sessionFile);
+        }
+    }
+    /**
+     * Completes the MFA step after a `RequireMFAException`.
+     *
+     * @param email - Account email address.
+     * @param password - Account password.
+     * @param code - The 6-digit TOTP code.
+     */
+    async multiFactorAuthenticate(email, password, code) {
+        await this._multiFactorAuthenticate(email, password, code);
+    }
+    /**
+     * Submits the code sent to your email when the API returns "Retrieve the code from your email to continue login."
+     */
+    async submitEmailOtp(email, password, code) {
+        await this._submitEmailOtp(email, password, code);
+    }
+    /**
+     * Interactive CLI login that prompts for email, password, and MFA code if needed.
+     */
+    async interactiveLogin(options = {}) {
+        const { useSavedSession = true, saveSession = true } = options;
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const ask = (prompt) => new Promise((resolve) => rl.question(prompt, (answer) => resolve(answer.trim())));
+        let email = "";
+        let passwd = "";
+        try {
+            email = await ask("Email: ");
+            passwd = await ask("Password: ");
+            await this.login(email, passwd, { useSavedSession, saveSession: false });
+            if (saveSession)
+                this.saveSession(this._sessionFile);
+        }
+        catch (e) {
+            if (e instanceof errors_js_1.EmailOtpRequiredException) {
+                const code = await ask("Enter the code from your email: ");
+                await this.submitEmailOtp(email, passwd, code);
+                if (saveSession)
+                    this.saveSession(this._sessionFile);
+            }
+            else if (e instanceof errors_js_1.RequireMFAException) {
+                const code = await ask("Two Factor Code: ");
+                await this.multiFactorAuthenticate(email, passwd, code);
+                if (saveSession)
+                    this.saveSession(this._sessionFile);
+            }
+            else {
+                throw e;
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    /** Saves the current session token to disk. */
+    saveSession(filename) {
+        const file = path.resolve(filename ?? this._sessionFile);
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ token: this._token }), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    /** Loads a previously saved session token from disk. */
+    loadSession(filename) {
+        const file = path.resolve(filename ?? this._sessionFile);
+        const raw = fs.readFileSync(file, "utf8");
+        const data = JSON.parse(raw);
+        if (!data.token) {
+            throw new errors_js_1.LoginFailedException("Session file does not contain a valid token.");
+        }
+        this.setToken(data.token);
+    }
+    /** Deletes the session file from disk. */
+    deleteSession(filename) {
+        const file = path.resolve(filename ?? this._sessionFile);
+        if (fs.existsSync(file))
+            fs.unlinkSync(file);
+    }
+    // ---------- Private auth ----------
+    async _loginUser(email, password, mfaSecretKey) {
+        const body = {
+            username: email,
+            password,
+            supports_mfa: true,
+            supports_email_otp: true,
+            supports_recaptcha: true,
+            trusted_device: false,
+        };
+        if (mfaSecretKey) {
+            body.totp = speakeasy_1.default.totp({ secret: mfaSecretKey, encoding: "base32" });
+        }
+        const res = await fetch((0, endpoints_js_1.getLoginEndpoint)(), {
+            method: "POST",
+            headers: this._headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this._timeout),
+        });
+        let bodyText = "";
+        try {
+            bodyText = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        if (!res.ok) {
+            let detail = "";
+            let errorCode = "";
+            try {
+                const data = JSON.parse(bodyText);
+                detail = typeof data.detail === "string" ? data.detail : "";
+                errorCode = typeof data.error_code === "string" ? data.error_code : "";
+            }
+            catch {
+                detail = bodyText || "";
+            }
+            const combined = `${detail} ${errorCode}`.toLowerCase();
+            if (errorCode === "EMAIL_OTP_REQUIRED" || (res.status === 403 && /email.*code|email.*otp|otp.*email/i.test(combined))) {
+                throw new errors_js_1.EmailOtpRequiredException(detail || "Email verification code required. Check your email.");
+            }
+            if (res.status === 403 && /mfa|multi.?factor|two.?factor|2fa|totp/i.test(combined)) {
+                throw new errors_js_1.RequireMFAException(detail || "Multi-Factor Auth Required");
+            }
+            throw new errors_js_1.LoginFailedException(detail || `HTTP ${res.status}: ${res.statusText}`, res.status);
+        }
+        const data = JSON.parse(bodyText);
+        this.setToken(data.token);
+    }
+    async _multiFactorAuthenticate(email, password, code) {
+        const body = {
+            username: email,
+            password,
+            supports_mfa: true,
+            totp: code,
+            trusted_device: false,
+        };
+        const res = await fetch((0, endpoints_js_1.getLoginEndpoint)(), {
+            method: "POST",
+            headers: this._headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this._timeout),
+        });
+        if (!res.ok) {
+            let msg = "";
+            try {
+                const data = (await res.json());
+                if (typeof data.detail === "string")
+                    msg = data.detail;
+                else if (typeof data.error_code === "string")
+                    msg = data.error_code;
+            }
+            catch {
+                // response body not JSON
+            }
+            throw new errors_js_1.LoginFailedException(msg || `HTTP ${res.status}: ${res.statusText}`, res.status);
+        }
+        const data = (await res.json());
+        this.setToken(data.token);
+    }
+    async _submitEmailOtp(email, password, code) {
+        const body = {
+            username: email,
+            password,
+            supports_mfa: true,
+            supports_email_otp: true,
+            supports_recaptcha: true,
+            trusted_device: false,
+            email_otp: code,
+        };
+        const res = await fetch((0, endpoints_js_1.getLoginEndpoint)(), {
+            method: "POST",
+            headers: this._headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this._timeout),
+        });
+        let bodyText = "";
+        try {
+            bodyText = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        if (!res.ok) {
+            let msg = "";
+            try {
+                const data = JSON.parse(bodyText);
+                if (typeof data.detail === "string")
+                    msg = data.detail;
+                else if (typeof data.error_code === "string")
+                    msg = data.error_code;
+            }
+            catch {
+                msg = bodyText || "";
+            }
+            throw new errors_js_1.LoginFailedException(msg || `HTTP ${res.status}: ${res.statusText}`, res.status);
+        }
+        const data = JSON.parse(bodyText);
+        this.setToken(data.token);
+    }
+    // ---------- Rate limiter ----------
+    async _acquireRateLimitToken() {
+        if (this._rateLimitRps <= 0)
+            return;
+        const now = Date.now();
+        const elapsed = now - this._rateLimitLastRefill;
+        const refill = (elapsed / 1000) * this._rateLimitRps;
+        this._rateLimitTokens = Math.min(this._rateLimitRps, this._rateLimitTokens + refill);
+        this._rateLimitLastRefill = now;
+        if (this._rateLimitTokens < 1) {
+            const waitMs = ((1 - this._rateLimitTokens) / this._rateLimitRps) * 1000;
+            await new Promise((r) => globalThis.setTimeout(r, waitMs));
+            this._rateLimitTokens = 0;
+            this._rateLimitLastRefill = Date.now();
+        }
+        else {
+            this._rateLimitTokens -= 1;
+        }
+    }
+    // ---------- Retry with backoff ----------
+    async _fetchWithRetry(url, init) {
+        await this._acquireRateLimitToken();
+        let lastError;
+        for (let attempt = 0; attempt <= this._maxRetries; attempt++) {
+            try {
+                const res = await fetch(url, {
+                    ...init,
+                    signal: AbortSignal.timeout(this._timeout),
+                });
+                if (res.ok || !RETRYABLE_STATUS_CODES.has(res.status) || attempt === this._maxRetries) {
+                    return res;
+                }
+                const retryAfterHeader = res.headers.get("Retry-After");
+                const retryAfterMs = retryAfterHeader
+                    ? parseFloat(retryAfterHeader) * 1000
+                    : undefined;
+                await this._backoff(attempt, retryAfterMs);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt === this._maxRetries)
+                    break;
+                await this._backoff(attempt);
+            }
+        }
+        throw lastError ?? new errors_js_1.RequestFailedException("Request failed after retries");
+    }
+    async _backoff(attempt, retryAfterMs) {
+        const jitter = Math.random() * 0.5 + 0.75; // 0.75–1.25x
+        const exponentialMs = this._retryBaseDelayMs * Math.pow(2, attempt) * jitter;
+        const delayMs = retryAfterMs != null
+            ? Math.max(retryAfterMs, exponentialMs)
+            : exponentialMs;
+        await new Promise((r) => globalThis.setTimeout(r, delayMs));
+    }
+    // ---------- Private GraphQL ----------
+    async gqlCall(operation, query, variables = {}) {
+        if (!this._token) {
+            throw new errors_js_1.LoginFailedException("Not authenticated. Call login() first or provide a token.");
+        }
+        const res = await this._fetchWithRetry((0, endpoints_js_1.getGraphQL)(), {
+            method: "POST",
+            headers: this._headers,
+            body: JSON.stringify({ operationName: operation, query, variables }),
+        });
+        if (!res.ok) {
+            throw new errors_js_1.RequestFailedException(`HTTP ${res.status}: ${res.statusText}`, { statusCode: res.status });
+        }
+        const json = (await res.json());
+        if (json.errors?.length) {
+            throw new errors_js_1.RequestFailedException(json.errors.map((e) => e.message).join("; "), { graphQLErrors: json.errors });
+        }
+        if (!json.data) {
+            throw new errors_js_1.RequestFailedException("No data in GraphQL response");
+        }
+        return json.data;
+    }
+    // ---------- Date helpers ----------
+    _getStartOfCurrentMonth() {
+        const d = new Date();
+        return new Date(d.getFullYear(), d.getMonth(), 1).toISOString().slice(0, 10);
+    }
+    _getEndOfCurrentMonth() {
+        const d = new Date();
+        return new Date(d.getFullYear(), d.getMonth() + 1, 0)
+            .toISOString()
+            .slice(0, 10);
+    }
+    // =====================================================================
+    //  READ METHODS
+    // =====================================================================
+    /** Gets all accounts linked to Monarch Money. */
+    async getAccounts() {
+        return this.gqlCall("GetAccounts", queries.GET_ACCOUNTS);
+    }
+    /** Gets all available account types and their subtypes. */
+    async getAccountTypeOptions() {
+        return this.gqlCall("GetAccountTypeOptions", queries.GET_ACCOUNT_TYPE_OPTIONS);
+    }
+    /**
+     * Gets daily account balances starting from `startDate`.
+     * Defaults to 31 days ago if not specified.
+     */
+    async getRecentAccountBalances(startDate) {
+        if (!startDate) {
+            const d = new Date();
+            d.setDate(d.getDate() - 31);
+            startDate = d.toISOString().slice(0, 10);
+        }
+        return this.gqlCall("GetAccountRecentBalances", queries.GET_RECENT_ACCOUNT_BALANCES, { startDate });
+    }
+    /**
+     * Gets net-value snapshots grouped by account type.
+     * @param timeframe - `"year"` or `"month"` granularity.
+     */
+    async getAccountSnapshotsByType(startDate, timeframe) {
+        return this.gqlCall("GetSnapshotsByAccountType", queries.GET_SNAPSHOTS_BY_ACCOUNT_TYPE, { startDate, timeframe });
+    }
+    /** Gets daily aggregate net value across all accounts. */
+    async getAggregateSnapshots(options) {
+        const d = new Date();
+        d.setFullYear(d.getFullYear() - 150);
+        d.setDate(1);
+        return this.gqlCall("GetAggregateSnapshots", queries.GET_AGGREGATE_SNAPSHOTS, {
+            filters: {
+                startDate: options?.startDate ?? d.toISOString().slice(0, 10),
+                endDate: options?.endDate ?? undefined,
+                accountType: options?.accountType ?? undefined,
+            },
+        });
+    }
+    /** Gets holdings (securities) for a brokerage or investment account. */
+    async getAccountHoldings(accountId) {
+        const today = new Date().toISOString().slice(0, 10);
+        return this.gqlCall("Web_GetHoldings", queries.GET_HOLDINGS, {
+            input: {
+                accountIds: [String(accountId)],
+                endDate: today,
+                includeHiddenHoldings: true,
+                startDate: today,
+            },
+        });
+    }
+    /** Gets daily balance history for a specific account. */
+    async getAccountHistory(accountId) {
+        const result = await this.gqlCall("AccountDetails_getAccount", queries.GET_ACCOUNT_HISTORY, {
+            id: String(accountId),
+        });
+        return result.snapshots.map((s) => ({
+            ...s,
+            accountId: String(accountId),
+            accountName: result.account.displayName,
+        }));
+    }
+    /** Gets linked institutions and their credentials. */
+    async getInstitutions() {
+        return this.gqlCall("Web_GetInstitutionSettings", queries.GET_INSTITUTIONS);
+    }
+    /**
+     * Gets budgets with actual amounts for the given date range.
+     * Defaults to previous month through next month.
+     */
+    async getBudgets(startDate, endDate) {
+        let start = startDate;
+        let end = endDate;
+        if (!start && !end) {
+            const d = new Date();
+            start = new Date(d.getFullYear(), d.getMonth() - 1, 1)
+                .toISOString()
+                .slice(0, 10);
+            end = new Date(d.getFullYear(), d.getMonth() + 2, 0)
+                .toISOString()
+                .slice(0, 10);
+        }
+        else if (Boolean(start) !== Boolean(end)) {
+            throw new Error("You must specify both startDate and endDate, not just one of them.");
+        }
+        return this.gqlCall("Common_GetJointPlanningData", queries.GET_BUDGETS, { startDate: start, endDate: end });
+    }
+    /** Gets Monarch Money subscription details (plan status, trial, etc.). */
+    async getSubscriptionDetails() {
+        return this.gqlCall("GetSubscriptionDetails", queries.GET_SUBSCRIPTION_DETAILS);
+    }
+    /** Gets aggregate transaction summary (totals, averages, counts). */
+    async getTransactionsSummary() {
+        return this.gqlCall("GetTransactionsPage", queries.GET_TRANSACTIONS_SUMMARY);
+    }
+    /**
+     * Gets transactions with filtering, pagination, and sorting.
+     * Defaults to the most recent 100 transactions.
+     */
+    async getTransactions(options = {}) {
+        const { limit = DEFAULT_RECORD_LIMIT, offset = 0, ...filterOpts } = options;
+        const filters = this._buildTransactionFilters(filterOpts);
+        return this.gqlCall("GetTransactionsList", queries.GET_TRANSACTIONS_LIST, { offset, limit, orderBy: "date", filters });
+    }
+    /**
+     * Async generator that automatically paginates through all matching transactions.
+     * Yields one page of `Transaction[]` at a time.
+     *
+     * @param options - Same filter options as `getTransactions()`.
+     * @param options.pageSize - Number of transactions per page. Default: `100`.
+     *
+     * @example
+     * ```ts
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    async *getTransactionPages(options = {}) {
+        const { pageSize = DEFAULT_RECORD_LIMIT, ...filterOpts } = options;
+        let offset = 0;
+        while (true) {
+            const response = await this.getTransactions({
+                ...filterOpts,
+                limit: pageSize,
+                offset,
+            });
+            const results = response.allTransactions.results;
+            if (results.length === 0)
+                break;
+            yield results;
+            offset += results.length;
+            if (offset >= response.allTransactions.totalCount)
+                break;
+        }
+    }
+    /**
+     * Returns all matching transactions across all pages as a flat array.
+     * Convenience wrapper around `getTransactionPages()`.
+     */
+    async getAllTransactions(options = {}) {
+        const all = [];
+        for await (const page of this.getTransactionPages(options)) {
+            all.push(...page);
+        }
+        return all;
+    }
+    _buildTransactionFilters(opts) {
+        const { startDate, endDate, search = "", categoryIds = [], accountIds = [], tagIds = [], hasAttachments, hasNotes, hiddenFromReports, isSplit, isRecurring, importedFromMint, syncedFromInstitution, } = opts;
+        if (Boolean(startDate) !== Boolean(endDate)) {
+            throw new Error("You must specify both startDate and endDate, not just one.");
+        }
+        const filters = {
+            search,
+            categories: categoryIds,
+            accounts: accountIds,
+            tags: tagIds,
+        };
+        if (hasAttachments != null)
+            filters.hasAttachments = hasAttachments;
+        if (hasNotes != null)
+            filters.hasNotes = hasNotes;
+        if (hiddenFromReports != null)
+            filters.hideFromReports = hiddenFromReports;
+        if (isRecurring != null)
+            filters.isRecurring = isRecurring;
+        if (isSplit != null)
+            filters.isSplit = isSplit;
+        if (importedFromMint != null)
+            filters.importedFromMint = importedFromMint;
+        if (syncedFromInstitution != null)
+            filters.syncedFromInstitution = syncedFromInstitution;
+        if (startDate && endDate) {
+            filters.startDate = startDate;
+            filters.endDate = endDate;
+        }
+        return filters;
+    }
+    /** Gets all transaction categories. */
+    async getTransactionCategories() {
+        return this.gqlCall("GetCategories", queries.GET_CATEGORIES);
+    }
+    /** Gets all category groups. */
+    async getTransactionCategoryGroups() {
+        return this.gqlCall("ManageGetCategoryGroups", queries.GET_CATEGORY_GROUPS);
+    }
+    /** Gets detailed data for a single transaction. */
+    async getTransactionDetails(transactionId) {
+        return this.gqlCall("GetTransactionDetails", queries.GET_TRANSACTION_DETAILS, { id: transactionId });
+    }
+    /** Gets the splits for a transaction. */
+    async getTransactionSplits(transactionId) {
+        return this.gqlCall("GetTransactionSplits", queries.GET_TRANSACTION_SPLITS, { id: transactionId });
+    }
+    /** Gets all tags configured in the account. */
+    async getTransactionTags() {
+        return this.gqlCall("GetTransactionTags", queries.GET_TRANSACTION_TAGS);
+    }
+    /**
+     * Gets cashflow data grouped by category, category group, and merchant.
+     * Defaults to the current month.
+     */
+    async getCashflow(options) {
+        if (options && Boolean(options.startDate) !== Boolean(options.endDate)) {
+            throw new Error("You must specify both startDate and endDate, not just one.");
+        }
+        const start = options?.startDate ?? this._getStartOfCurrentMonth();
+        const end = options?.endDate ?? this._getEndOfCurrentMonth();
+        return this.gqlCall("Web_GetCashFlowPage", queries.GET_CASHFLOW, {
+            filters: {
+                search: "",
+                categories: [],
+                accounts: [],
+                tags: [],
+                startDate: start,
+                endDate: end,
+            },
+        });
+    }
+    /**
+     * Gets cashflow summary (income, expenses, savings, savings rate).
+     * Defaults to the current month.
+     */
+    async getCashflowSummary(options) {
+        if (options && Boolean(options.startDate) !== Boolean(options.endDate)) {
+            throw new Error("You must specify both startDate and endDate, not just one.");
+        }
+        const start = options?.startDate ?? this._getStartOfCurrentMonth();
+        const end = options?.endDate ?? this._getEndOfCurrentMonth();
+        return this.gqlCall("Web_GetCashFlowPage", queries.GET_CASHFLOW_SUMMARY, {
+            filters: {
+                search: "",
+                categories: [],
+                accounts: [],
+                tags: [],
+                startDate: start,
+                endDate: end,
+            },
+        });
+    }
+    /**
+     * Gets upcoming recurring transactions for a date range.
+     * Defaults to the current month.
+     */
+    async getRecurringTransactions(startDate, endDate) {
+        if (Boolean(startDate) !== Boolean(endDate)) {
+            throw new Error("You must specify both startDate and endDate, not just one.");
+        }
+        return this.gqlCall("Web_GetUpcomingRecurringTransactionItems", queries.GET_RECURRING_TRANSACTIONS, {
+            startDate: startDate ?? this._getStartOfCurrentMonth(),
+            endDate: endDate ?? this._getEndOfCurrentMonth(),
+        });
+    }
+    /** Checks whether a prior account refresh request has completed. */
+    async isAccountsRefreshComplete(accountIds) {
+        const result = await this.gqlCall("ForceRefreshAccountsQuery", queries.GET_REFRESH_STATUS);
+        if (!result.accounts) {
+            throw new errors_js_1.RequestFailedException("Unable to check refresh status");
+        }
+        const list = accountIds?.length
+            ? result.accounts.filter((a) => accountIds.includes(a.id))
+            : result.accounts;
+        return list.every((a) => !a.hasSyncInProgress);
+    }
+    // =====================================================================
+    //  WRITE METHODS
+    // =====================================================================
+    /** Creates a new manual account. */
+    async createManualAccount(params) {
+        return this.gqlCall("Web_CreateManualAccount", queries.CREATE_MANUAL_ACCOUNT, {
+            input: {
+                type: params.accountType,
+                subtype: params.accountSubType,
+                includeInNetWorth: params.isInNetWorth,
+                name: params.accountName,
+                displayBalance: params.accountBalance ?? 0,
+            },
+        });
+    }
+    /** Updates an account's settings and/or balance. */
+    async updateAccount(accountId, updates) {
+        const input = { id: accountId };
+        if (updates.accountName != null)
+            input.name = updates.accountName;
+        if (updates.accountBalance != null)
+            input.displayBalance = updates.accountBalance;
+        if (updates.accountType != null)
+            input.type = updates.accountType;
+        if (updates.accountSubType != null)
+            input.subtype = updates.accountSubType;
+        if (updates.includeInNetWorth != null)
+            input.includeInNetWorth = updates.includeInNetWorth;
+        if (updates.hideFromSummaryList != null)
+            input.hideFromList = updates.hideFromSummaryList;
+        if (updates.hideTransactionsFromReports != null)
+            input.hideTransactionsFromReports = updates.hideTransactionsFromReports;
+        return this.gqlCall("Common_UpdateAccount", queries.UPDATE_ACCOUNT, { input });
+    }
+    /** Deletes an account by ID. */
+    async deleteAccount(accountId) {
+        return this.gqlCall("Common_DeleteAccount", queries.DELETE_ACCOUNT, { id: accountId });
+    }
+    /**
+     * Requests an account balance/transaction refresh. Non-blocking.
+     * Use `isAccountsRefreshComplete()` to poll for status.
+     */
+    async requestAccountsRefresh(accountIds) {
+        const result = await this.gqlCall("Common_ForceRefreshAccountsMutation", queries.FORCE_REFRESH_ACCOUNTS, { input: { accountIds } });
+        if (!result.forceRefreshAccounts.success) {
+            throw new errors_js_1.RequestFailedException(JSON.stringify(result.forceRefreshAccounts.errors));
+        }
+        return true;
+    }
+    /**
+     * Refreshes accounts and polls until complete or timeout.
+     *
+     * @param options.onProgress - Called after each poll with progress info.
+     * @returns `true` if all accounts refreshed within the timeout, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * await mm.requestAccountsRefreshAndWait({
+     *   onProgress: ({ completed, total, elapsedMs }) => {
+     *     console.log(`${completed}/${total} accounts refreshed (${(elapsedMs / 1000).toFixed(0)}s)`);
+     *   },
+     * });
+     * ```
+     */
+    async requestAccountsRefreshAndWait(options) {
+        const { timeout = 300, delay = 10, onProgress } = options ?? {};
+        let accountIds = options?.accountIds;
+        if (!accountIds) {
+            const data = await this.getAccounts();
+            accountIds = data.accounts.map((a) => a.id);
+        }
+        await this.requestAccountsRefresh(accountIds);
+        const startTime = Date.now();
+        const deadline = startTime + timeout * 1000;
+        while (Date.now() < deadline) {
+            await new Promise((r) => globalThis.setTimeout(r, delay * 1000));
+            const result = await this.gqlCall("ForceRefreshAccountsQuery", queries.GET_REFRESH_STATUS);
+            if (!result.accounts) {
+                throw new errors_js_1.RequestFailedException("Unable to check refresh status");
+            }
+            const tracked = accountIds.length
+                ? result.accounts.filter((a) => accountIds.includes(a.id))
+                : result.accounts;
+            const completed = tracked.filter((a) => !a.hasSyncInProgress).length;
+            onProgress?.({
+                completed,
+                total: tracked.length,
+                elapsedMs: Date.now() - startTime,
+            });
+            if (completed === tracked.length)
+                return true;
+        }
+        return false;
+    }
+    /** Creates a new transaction. */
+    async createTransaction(params) {
+        return this.gqlCall("Common_CreateTransactionMutation", queries.CREATE_TRANSACTION, {
+            input: {
+                date: params.date,
+                accountId: params.accountId,
+                amount: Math.round(params.amount * 100) / 100,
+                merchantName: params.merchantName,
+                categoryId: params.categoryId,
+                notes: params.notes ?? "",
+                shouldUpdateBalance: params.updateBalance ?? false,
+            },
+        });
+    }
+    /**
+     * Updates an existing transaction. Only provided fields are changed.
+     */
+    async updateTransaction(transactionId, updates) {
+        const input = { id: transactionId };
+        if (updates.categoryId != null)
+            input.category = updates.categoryId;
+        if (updates.merchantName != null)
+            input.name = updates.merchantName;
+        if (updates.goalId != null)
+            input.goalId = updates.goalId;
+        if (updates.amount != null)
+            input.amount = updates.amount;
+        if (updates.date != null)
+            input.date = updates.date;
+        if (updates.hideFromReports != null)
+            input.hideFromReports = updates.hideFromReports;
+        if (updates.needsReview != null)
+            input.needsReview = updates.needsReview;
+        if (updates.notes != null)
+            input.notes = updates.notes;
+        return this.gqlCall("Web_TransactionDrawerUpdateTransaction", queries.UPDATE_TRANSACTION, { input });
+    }
+    /** Deletes a transaction by ID. */
+    async deleteTransaction(transactionId) {
+        const result = await this.gqlCall("Common_DeleteTransactionMutation", queries.DELETE_TRANSACTION, { input: { id: transactionId } });
+        if (result.deleteTransaction.errors?.length) {
+            throw new errors_js_1.RequestFailedException(JSON.stringify(result.deleteTransaction.errors));
+        }
+        return result.deleteTransaction.deleted;
+    }
+    /** Deletes a transaction category. Optionally moves transactions to another category. */
+    async deleteTransactionCategory(categoryId, moveToCategoryId) {
+        const result = await this.gqlCall("Web_DeleteCategory", queries.DELETE_CATEGORY, { id: categoryId, moveToCategoryId });
+        if (!result.deleteCategory.deleted &&
+            result.deleteCategory.errors?.length) {
+            throw new errors_js_1.RequestFailedException(JSON.stringify(result.deleteCategory.errors));
+        }
+        return result.deleteCategory.deleted;
+    }
+    /** Deletes multiple transaction categories. Returns results per category. */
+    async deleteTransactionCategories(categoryIds) {
+        return Promise.all(categoryIds.map((id) => this.deleteTransactionCategory(id).catch((e) => e instanceof Error ? e : new Error(String(e)))));
+    }
+    /** Creates a new transaction category within a category group. */
+    async createTransactionCategory(params) {
+        const d = new Date();
+        d.setDate(1);
+        return this.gqlCall("Web_CreateCategory", queries.CREATE_CATEGORY, {
+            input: {
+                groupId: params.groupId,
+                name: params.name,
+                icon: params.icon ?? "\u2753",
+                rolloverStartMonth: params.rolloverStartMonth ?? d.toISOString().slice(0, 10),
+                rolloverEnabled: params.rolloverEnabled ?? false,
+                rolloverType: params.rolloverType ?? "monthly",
+            },
+        });
+    }
+    /** Creates a new tag for transactions. */
+    async createTransactionTag(name, color) {
+        return this.gqlCall("Common_CreateTransactionTag", queries.CREATE_TRANSACTION_TAG, { input: { name, color } });
+    }
+    /** Sets (replaces) all tags on a transaction. */
+    async setTransactionTags(transactionId, tagIds) {
+        return this.gqlCall("Web_SetTransactionTags", queries.SET_TRANSACTION_TAGS, { input: { transactionId, tagIds } });
+    }
+    /**
+     * Creates, modifies, or removes splits on a transaction.
+     * Pass an empty array to remove all splits.
+     * The sum of split amounts must equal the transaction amount.
+     */
+    async updateTransactionSplits(transactionId, splitData) {
+        return this.gqlCall("Common_SplitTransactionMutation", queries.SPLIT_TRANSACTION, { input: { transactionId, splitData } });
+    }
+    /**
+     * Sets a budget amount for a category or category group.
+     * A zero amount clears the budget. Exactly one of `categoryId` or `categoryGroupId` is required.
+     */
+    async setBudgetAmount(params) {
+        const { categoryId, categoryGroupId } = params;
+        if ((categoryId == null) === (categoryGroupId == null)) {
+            throw new Error("You must specify either categoryId OR categoryGroupId; not both.");
+        }
+        return this.gqlCall("Common_UpdateBudgetItem", queries.UPDATE_BUDGET_ITEM, {
+            input: {
+                startDate: params.startDate ?? this._getStartOfCurrentMonth(),
+                timeframe: params.timeframe ?? "month",
+                categoryId: categoryId ?? undefined,
+                categoryGroupId: categoryGroupId ?? undefined,
+                amount: params.amount,
+                applyToFuture: params.applyToFuture ?? false,
+            },
+        });
+    }
+    /**
+     * Uploads a CSV file of balance history for a manual account.
+     * @param accountId - The account to apply history to.
+     * @param csvContent - CSV string content.
+     */
+    async uploadAccountBalanceHistory(accountId, csvContent) {
+        if (!accountId?.trim() || !csvContent?.trim()) {
+            throw new errors_js_1.RequestFailedException("accountId and csvContent cannot be empty");
+        }
+        const form = new FormData();
+        form.append("files", new Blob([csvContent], { type: "text/csv" }), "upload.csv");
+        form.append("account_files_mapping", JSON.stringify({ "upload.csv": accountId }));
+        const headers = { ...this._headers };
+        delete headers["Content-Type"];
+        const res = await this._fetchWithRetry((0, endpoints_js_1.getAccountBalanceHistoryUploadEndpoint)(), {
+            method: "POST",
+            headers,
+            body: form,
+        });
+        if (!res.ok) {
+            throw new errors_js_1.RequestFailedException(`HTTP ${res.status}: ${res.statusText}`, { statusCode: res.status });
+        }
+    }
+}
+exports.MonarchMoney = MonarchMoney;
+//# sourceMappingURL=client.js.map