cata-centavo 0.1.0

package/dist/mcp/tools/bill-summary-format.js

@@ -0,0 +1,161 @@
+import { ClosingDateSource, newestBill, } from "../../core/bill.js";
+import { deriveBillCommitment, derivePostedCents, partitionBillRows, } from "../../core/bill-rows.js";
+import { isSelfTransfer } from "../../core/self-transfer.js";
+import { toDecimal } from "../format.js";
+/** The card's own figures, always available because they come from the account itself. */
+export function formatSummaryBase(account) {
+    return {
+        accountId: account.id,
+        institution: account.institution,
+        currency: account.currency,
+        utilization: toDecimal(account.amountCents),
+        creditLimit: decimalOrNull(account.credit?.limitCents ?? null),
+        availableLimit: decimalOrNull(account.credit?.availableLimitCents ?? null),
+    };
+}
+/**
+ * The two estimates of the open bill, plus the gap the caller must quote.
+ * They are measured differently and neither one bounds the other.
+ */
+export function formatDerivedFigures(account, rows, bills, openCycle) {
+    let openBillId = null;
+    if (openCycle.source === ClosingDateSource.openBill) {
+        openBillId = newestBill(bills)?.id ?? null;
+    }
+    const partition = partitionBillRows(rows, openCycle.openCycle, openBillId);
+    const postedCents = postedFor(openCycle, bills, partition.openCycleRows);
+    const commitment = deriveBillCommitment(partition, account.amountCents);
+    return {
+        posted: toDecimal(postedCents),
+        committed: toDecimal(commitment.committedCents),
+        futureInstalments: toDecimal(commitment.futureCents),
+        gap: toDecimal(Math.abs(commitment.committedCents - postedCents)),
+        committedIsNegative: commitment.committedCents < 0,
+        postedExceedsCommitted: postedCents > commitment.committedCents,
+        topTransactions: topTransactions(partition.openCycleRows),
+    };
+}
+function postedFor(openCycle, bills, rows) {
+    if (openCycle.source === ClosingDateSource.openBill) {
+        return newestBill(bills)?.totalCents ?? derivePostedCents(rows);
+    }
+    return derivePostedCents(rows);
+}
+function topTransactions(rows) {
+    return rows
+        .filter((row) => row.amountCents < 0 && !isSelfTransfer(row))
+        .toSorted(compareCharges)
+        .slice(0, 5)
+        .map((row) => ({
+        id: row.id,
+        date: row.localDate,
+        description: row.description,
+        amount: toDecimal(-row.amountCents),
+        category: row.category,
+    }));
+}
+function compareCharges(left, right) {
+    const amountOrder = left.amountCents - right.amountCents;
+    if (amountOrder !== 0) {
+        return amountOrder;
+    }
+    const dateOrder = right.localDate.localeCompare(left.localDate);
+    if (dateOrder !== 0) {
+        return dateOrder;
+    }
+    return left.id.localeCompare(right.id);
+}
+/** The open cycle's own dates, derived differently depending on what identified the cycle. */
+export function formatCycle(openCycle, bills, account, storedDay) {
+    const dates = cycleDates(openCycle, bills, account, storedDay);
+    return {
+        openCycle: openCycle.openCycle,
+        ...dates,
+        closingDateSource: openCycle.source,
+    };
+}
+function cycleDates(openCycle, bills, account, storedDay) {
+    const latestBill = newestBill(bills);
+    if (openCycle.source === ClosingDateSource.openBill) {
+        return datesFromOpenBill(latestBill);
+    }
+    if (openCycle.source === ClosingDateSource.lastClosed) {
+        return datesAfterClosedBill(latestBill);
+    }
+    if (openCycle.source === ClosingDateSource.local) {
+        return datesFromLocalDay(openCycle.openCycle, storedDay, account);
+    }
+    return {
+        closingDate: dateInCycleFrom(creditDate(account, "balanceCloseDate"), openCycle.openCycle),
+        dueDate: dateInCycleFrom(creditDate(account, "balanceDueDate"), openCycle.openCycle),
+    };
+}
+function datesFromOpenBill(bill) {
+    if (bill === null) {
+        return { closingDate: null, dueDate: null };
+    }
+    return { closingDate: bill.closingDate, dueDate: bill.dueDate };
+}
+function datesAfterClosedBill(bill) {
+    if (bill === null) {
+        return { closingDate: null, dueDate: null };
+    }
+    return {
+        closingDate: shiftOneMonth(bill.closingDate),
+        dueDate: shiftOneMonth(bill.dueDate),
+    };
+}
+function datesFromLocalDay(cycle, storedDay, account) {
+    let closingDate = null;
+    if (storedDay !== null) {
+        closingDate = dateInCycle(cycle, storedDay);
+    }
+    return {
+        closingDate,
+        dueDate: dateInCycleFrom(creditDate(account, "balanceDueDate"), cycle),
+    };
+}
+function creditDate(account, field) {
+    if (account.credit === null) {
+        return null;
+    }
+    return account.credit[field];
+}
+function decimalOrNull(cents) {
+    if (cents === null) {
+        return null;
+    }
+    return toDecimal(cents);
+}
+function shiftOneMonth(date) {
+    if (date === null) {
+        return null;
+    }
+    const year = Number(date.slice(0, 4));
+    const month = Number(date.slice(5, 7));
+    const day = Number(date.slice(8, 10));
+    let shiftedYear = year;
+    let shiftedMonth = month + 1;
+    if (shiftedMonth === 13) {
+        shiftedYear += 1;
+        shiftedMonth = 1;
+    }
+    return dateFromParts(shiftedYear, shiftedMonth, day);
+}
+function dateInCycleFrom(date, cycle) {
+    if (date === null) {
+        return null;
+    }
+    return dateInCycle(cycle, date.getUTCDate());
+}
+function dateInCycle(cycle, day) {
+    const year = Number(cycle.slice(0, 4));
+    const month = Number(cycle.slice(5, 7));
+    return dateFromParts(year, month, day);
+}
+function dateFromParts(year, month, day) {
+    const lastDay = new Date(Date.UTC(year, month, 0)).getUTCDate();
+    const clampedDay = Math.min(day, lastDay);
+    return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(clampedDay).padStart(2, "0")}`;
+}
+//# sourceMappingURL=bill-summary-format.js.map

package/dist/mcp/tools/bill-summary-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bill-summary-format.js","sourceRoot":"","sources":["../../../src/mcp/tools/bill-summary-format.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EACjB,UAAU,GAGX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,0FAA0F;AAC1F,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,EAAE;QACrB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,WAAW,EAAE,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC;QAC3C,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,IAAI,IAAI,CAAC;QAC9D,cAAc,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,mBAAmB,IAAI,IAAI,CAAC;KAC3E,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAgB,EAChB,IAAmC,EACnC,KAAsB,EACtB,SAAoB;IAEpB,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,IAAI,SAAS,CAAC,MAAM,KAAK,iBAAiB,CAAC,QAAQ,EAAE,CAAC;QACpD,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC;IAC7C,CAAC;IACD,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC3E,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IACzE,MAAM,UAAU,GAAG,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAExE,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC;QAC9B,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,cAAc,CAAC;QAC/C,iBAAiB,EAAE,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC;QACpD,GAAG,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,GAAG,WAAW,CAAC,CAAC;QACjE,mBAAmB,EAAE,UAAU,CAAC,cAAc,GAAG,CAAC;QAClD,sBAAsB,EAAE,WAAW,GAAG,UAAU,CAAC,cAAc;QAC/D,eAAe,EAAE,eAAe,CAAC,SAAS,CAAC,aAAa,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAChB,SAAoB,EACpB,KAAsB,EACtB,IAAmC;IAEnC,IAAI,SAAS,CAAC,MAAM,KAAK,iBAAiB,CAAC,QAAQ,EAAE,CAAC;QACpD,OAAO,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,eAAe,CAAC,IAAmC;IAC1D,OAAO,IAAI;SACR,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;SAC5D,QAAQ,CAAC,cAAc,CAAC;SACxB,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACb,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,SAAS;QACnB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC;QACnC,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACvB,CAAC,CAAC,CAAC;AACR,CAAC;AAED,SAAS,cAAc,CAAC,IAAwB,EAAE,KAAyB;IACzE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACzD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAChE,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,WAAW,CACzB,SAAoB,EACpB,KAAsB,EACtB,OAAgB,EAChB,SAAwB;IAExB,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC/D,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,GAAG,KAAK;QACR,iBAAiB,EAAE,SAAS,CAAC,MAAM;KACpC,CAAC;AACJ,CAAC;AAOD,SAAS,UAAU,CACjB,SAAoB,EACpB,KAAsB,EACtB,OAAgB,EAChB,SAAwB;IAExB,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,SAAS,CAAC,MAAM,KAAK,iBAAiB,CAAC,QAAQ,EAAE,CAAC;QACpD,OAAO,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,iBAAiB,CAAC,UAAU,EAAE,CAAC;QACtD,OAAO,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,iBAAiB,CAAC,KAAK,EAAE,CAAC;QACjD,OAAO,iBAAiB,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IACD,OAAO;QACL,WAAW,EAAE,eAAe,CAAC,UAAU,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC;QAC1F,OAAO,EAAE,eAAe,CAAC,UAAU,CAAC,OAAO,EAAE,gBAAgB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC;KACrF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAiB;IAC1C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAiB;IAC7C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO;QACL,WAAW,EAAE,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC5C,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa,EAAE,SAAwB,EAAE,OAAgB;IAClF,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,WAAW,GAAG,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO;QACL,WAAW;QACX,OAAO,EAAE,eAAe,CAAC,UAAU,CAAC,OAAO,EAAE,gBAAgB,CAAC,EAAE,KAAK,CAAC;KACvE,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,OAAgB,EAChB,KAA4C;IAE5C,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CAAC,KAAoB;IACzC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,aAAa,CAAC,IAAmB;IACxC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACtC,IAAI,WAAW,GAAG,IAAI,CAAC;IACvB,IAAI,YAAY,GAAG,KAAK,GAAG,CAAC,CAAC;IAC7B,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;QACxB,WAAW,IAAI,CAAC,CAAC;QACjB,YAAY,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,aAAa,CAAC,WAAW,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,eAAe,CAAC,IAAiB,EAAE,KAAa;IACvD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,WAAW,CAAC,KAAa,EAAE,GAAW;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,aAAa,CAAC,IAAY,EAAE,KAAa,EAAE,GAAW;IAC7D,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IAChE,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACrH,CAAC"}

package/dist/mcp/tools/bill-summary.js

@@ -0,0 +1,105 @@
+import { identifyOpenCycle } from "../../core/bill.js";
+import { localDayOf, todayIn } from "../../core/date.js";
+import { formatCycle, formatDerivedFigures, formatSummaryBase } from "./bill-summary-format.js";
+import { finishToolError, textResult } from "./result.js";
+/** Refreshes the card's connection, then reports whatever the cache can support. */
+export async function executeBillSummary(options) {
+    const { deps, source, reader, account: resolvedAccount, startedAt } = options;
+    const loaded = await reader.load([resolvedAccount.connectionId]);
+    const unavailable = unavailableFor(loaded.unavailable, resolvedAccount.connectionId);
+    const refusal = unavailableResult(unavailable, resolvedAccount, deps.log, startedAt);
+    if (refusal !== null) {
+        return refusal;
+    }
+    const account = loaded.accounts.find(({ id }) => id === resolvedAccount.id) ?? resolvedAccount;
+    return summarizeCachedCard({ deps, source, reader, account });
+}
+async function summarizeCachedCard(options) {
+    const { deps, source, reader, account } = options;
+    const rows = reader.cardRows(account.id);
+    const base = formatSummaryBase(account);
+    if (rows.length === 0) {
+        return textResult({
+            ...base,
+            message: "This card has never been synced, or its latest sync returned no cached transactions.",
+        });
+    }
+    const today = todayIn(deps.clock);
+    const dataThrough = reader.dataThrough([account.id], today).get(account.connectionId);
+    if (dataThrough === undefined) {
+        return textResult({
+            ...base,
+            message: "No cached transaction date is available through today, so bill figures were omitted.",
+        });
+    }
+    return summarizeDatedCard({ deps, source, account, rows, base, today, dataThrough });
+}
+async function summarizeDatedCard(options) {
+    const { deps, source, account, rows, base, today, dataThrough } = options;
+    const bills = await source.bank.getBills(account);
+    const storedDay = storedClosingDay(deps.closingDays, account.id);
+    const balanceDueDate = dateOnly(account.credit?.balanceDueDate ?? null);
+    const openCycle = identifyOpenCycle(bills, storedDay, balanceDueDate, today);
+    const freshness = {
+        dataThrough,
+        staleDays: staleDays(account.lastUpdatedAt, dataThrough),
+    };
+    if (openCycle === null) {
+        return textResult({
+            ...base,
+            ...freshness,
+            message: "The open cycle cannot be identified. Use setClosingDay for this card.",
+        });
+    }
+    return textResult({
+        ...base,
+        cycle: formatCycle(openCycle, bills, account, storedDay),
+        ...formatDerivedFigures(account, rows, bills, openCycle),
+        ...freshness,
+    });
+}
+function storedClosingDay(store, accountId) {
+    if (store === null || store === undefined) {
+        return null;
+    }
+    return store.list().find((entry) => entry.accountId === accountId)?.day ?? null;
+}
+function unavailableFor(unavailable, connectionId) {
+    return unavailable.find((candidate) => candidate.connectionId === connectionId) ?? null;
+}
+/**
+ * Only the failures the model can act on become readable content. Anything else
+ * throws, because a protocol error is the channel a human reads.
+ */
+function unavailableResult(unavailable, account, log, startedAt) {
+    if (unavailable === null) {
+        return null;
+    }
+    if (!isReadableUnavailable(unavailable.kind)) {
+        throw new Error(unavailable.message);
+    }
+    return finishToolError(log, startedAt, unavailable.message, {
+        tool: "getBillSummary",
+        accountId: account.id,
+        connectionId: unavailable.connectionId,
+        kind: unavailable.kind,
+    });
+}
+function isReadableUnavailable(kind) {
+    return kind === "consent-revoked"
+        || kind === "consent-expired"
+        || kind === "unknown-connection"
+        || kind === "no-accounts";
+}
+function dateOnly(date) {
+    return date?.toISOString().slice(0, 10) ?? null;
+}
+function staleDays(lastUpdatedAt, dataThrough) {
+    if (lastUpdatedAt === null) {
+        return null;
+    }
+    const updatedDay = localDayOf(lastUpdatedAt.toISOString());
+    const milliseconds = Date.parse(`${updatedDay}T00:00:00.000Z`) - Date.parse(`${dataThrough}T00:00:00.000Z`);
+    return Math.max(0, Math.trunc(milliseconds / 86_400_000));
+}
+//# sourceMappingURL=bill-summary.js.map

package/dist/mcp/tools/bill-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bill-summary.js","sourceRoot":"","sources":["../../../src/mcp/tools/bill-summary.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/bills.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { ACCOUNT_TYPES } from "../../core/account.js";
+import { toDecimal } from "../format.js";
+import { executeBillSummary } from "./bill-summary.js";
+import { configurationProblems, finishToolError, textResult, } from "./result.js";
+export const GET_BILLS_DESCRIPTION = `Credit card statements for one card, newest first.
+
+Use this tool when:
+- the user asks what a past bill totalled, or when one was due
+- you need the closing day of recent cycles
+- the user asks whether a bill was paid
+
+Returns: cycles with closing date, due date, total, minimum payment, finance
+charges and payments. Usually these are closed statements, but on some banks the
+newest entry is the cycle still in progress — getBillSummary says which. An empty
+list means this bank does not publish bills, which is normal on non-regulated
+connections.`;
+export const GET_BILL_SUMMARY_DESCRIPTION = `The credit card bill currently in progress, as two independent estimates.
+
+Use this tool when:
+- the user asks what their open or current bill is
+- the user asks how much of the card limit is used
+- the user is deciding whether to spend more this cycle
+
+Returns: posted, what has actually posted to the open cycle, valid only through
+dataThrough; and committed, the used limit minus instalments scheduled for later
+cycles. They are measured differently and neither is a proven bound, so quote
+their gap rather than a midpoint. Also returns cycle and limit details, feed
+staleness, and the five largest purchases in the cycle.`;
+const getBillsSchema = z.object({
+    accountId: z.string().min(1),
+    limit: z.number().int().min(1).max(100).default(12),
+});
+const getBillSummarySchema = z.object({
+    accountId: z.string().min(1),
+});
+export function registerGetBills(server, deps) {
+    server.registerTool("getBills", { description: GET_BILLS_DESCRIPTION, inputSchema: getBillsSchema }, async (input) => handleGetBills(deps, input));
+}
+export function registerGetBillSummary(server, deps) {
+    server.registerTool("getBillSummary", { description: GET_BILL_SUMMARY_DESCRIPTION, inputSchema: getBillSummarySchema }, async (input) => handleGetBillSummary(deps, input));
+}
+export async function handleGetBills(deps, rawInput) {
+    const startedAt = Date.now();
+    const parsed = getBillsSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        return finishToolError(deps.log, startedAt, parsed.error.message, { tool: "getBills" });
+    }
+    if (!deps.source.ok) {
+        return finishToolError(deps.log, startedAt, configurationProblems(deps.source.problems), { tool: "getBills" });
+    }
+    const resolved = await resolveCreditAccount({
+        source: deps.source,
+        log: deps.log,
+        startedAt,
+        accountId: parsed.data.accountId,
+        tool: "getBills",
+    });
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    const bills = await deps.source.bank.getBills(resolved.account);
+    return textResult({ bills: bills.slice(0, parsed.data.limit).map(formatBill) });
+}
+export async function handleGetBillSummary(deps, rawInput) {
+    const startedAt = Date.now();
+    const parsed = getBillSummarySchema.safeParse(rawInput);
+    if (!parsed.success) {
+        return finishToolError(deps.log, startedAt, parsed.error.message, { tool: "getBillSummary" });
+    }
+    if (!deps.source.ok) {
+        return finishToolError(deps.log, startedAt, configurationProblems(deps.source.problems), { tool: "getBillSummary" });
+    }
+    if (deps.reader === null) {
+        return finishToolError(deps.log, startedAt, "Transaction reader is unavailable.", { tool: "getBillSummary" });
+    }
+    const source = deps.source;
+    const reader = deps.reader;
+    const resolved = await resolveCreditAccount({
+        source,
+        log: deps.log,
+        startedAt,
+        accountId: parsed.data.accountId,
+        tool: "getBillSummary",
+    });
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    return executeBillSummary({ deps, source, reader, account: resolved.account, startedAt });
+}
+async function resolveCreditAccount(options) {
+    const { source, log, startedAt, accountId, tool } = options;
+    let account;
+    try {
+        account = await source.bank.getAccount(accountId);
+    }
+    catch (error) {
+        if (source.toFailure(error).kind === "unknown-connection") {
+            return unknownAccount(log, startedAt, accountId, tool);
+        }
+        throw error;
+    }
+    if (!source.connections.includes(account.connectionId)) {
+        return unknownAccount(log, startedAt, accountId, tool);
+    }
+    if (account.type !== ACCOUNT_TYPES.credit) {
+        let actualType = account.type;
+        if (account.subtype !== null) {
+            actualType = `${account.type} (${account.subtype})`;
+        }
+        return {
+            ok: false,
+            result: finishToolError(log, startedAt, `Account ${account.id} has type ${actualType}; ${tool} requires a CREDIT card.`, { tool, accountId: account.id, accountType: account.type, accountSubtype: account.subtype }),
+        };
+    }
+    return { ok: true, account };
+}
+function unknownAccount(log, startedAt, accountId, tool) {
+    return {
+        ok: false,
+        result: finishToolError(log, startedAt, `Unknown account ${accountId}: not found.`, {
+            tool,
+            accountId,
+        }),
+    };
+}
+function formatBill(bill) {
+    let minimumPayment = null;
+    if (bill.minimumPaymentCents !== null) {
+        minimumPayment = toDecimal(bill.minimumPaymentCents);
+    }
+    return {
+        id: bill.id,
+        closingDate: bill.closingDate,
+        dueDate: bill.dueDate,
+        total: toDecimal(bill.totalCents),
+        currency: bill.currency,
+        minimumPayment,
+        financeCharges: toDecimal(bill.financeChargesCents),
+        payments: toDecimal(bill.paymentsCents),
+        paymentCount: bill.paymentCount,
+    };
+}
+//# sourceMappingURL=bills.js.map

package/dist/mcp/tools/bills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bills.js","sourceRoot":"","sources":["../../../src/mcp/tools/bills.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/closing-days.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { configurationProblems, finishToolError, textResult } from "./result.js";
+export const LIST_CLOSING_DAYS_DESCRIPTION = `Lists the closing days stored locally for credit cards.
+
+Use this tool when:
+- You need to see which cards have a manual closing-day fallback.
+- You need the stored day before changing or deleting it.
+
+Returns: Every stored account id and closing day. An empty list means no closing days are stored.`;
+export const SET_CLOSING_DAY_DESCRIPTION = `Stores the billing-cycle closing day for one credit card.
+
+Use this tool when:
+- The bank does not report the card's closing day.
+- The user wants to correct an existing stored day.
+
+Returns: The account id and day that were stored. This replaces any earlier day for the card.`;
+export const DELETE_CLOSING_DAY_DESCRIPTION = `Deletes the closing day stored locally for one credit card.
+
+Use this tool when:
+- A stored closing day is wrong and should no longer be used.
+- The bank now reports the closing day and the manual fallback is no longer needed.
+
+Returns: The account id and the number of stored rows deleted.`;
+const accountIdSchema = z.string().min(1);
+const setClosingDaySchema = z.object({
+    accountId: accountIdSchema,
+    day: z.number().int().min(1).max(31),
+});
+const deleteClosingDaySchema = z.object({
+    accountId: accountIdSchema,
+});
+export function registerListClosingDays(server, deps) {
+    server.registerTool("listClosingDays", { description: LIST_CLOSING_DAYS_DESCRIPTION }, async () => handleListClosingDays(deps));
+}
+export function registerSetClosingDay(server, deps) {
+    server.registerTool("setClosingDay", { description: SET_CLOSING_DAY_DESCRIPTION, inputSchema: setClosingDaySchema }, async (input) => handleSetClosingDay(deps, input));
+}
+export function registerDeleteClosingDay(server, deps) {
+    server.registerTool("deleteClosingDay", { description: DELETE_CLOSING_DAY_DESCRIPTION, inputSchema: deleteClosingDaySchema }, async (input) => handleDeleteClosingDay(deps, input));
+}
+export async function handleListClosingDays(deps) {
+    const startedAt = Date.now();
+    const resolved = resolveStore(deps, startedAt, "listClosingDays");
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    return textResult({ closingDays: resolved.store.list() });
+}
+export async function handleSetClosingDay(deps, rawInput) {
+    const startedAt = Date.now();
+    const parsed = setClosingDaySchema.safeParse(rawInput);
+    if (!parsed.success) {
+        return finishToolError(deps.log, startedAt, parsed.error.message, { tool: "setClosingDay" });
+    }
+    const resolved = resolveStore(deps, startedAt, "setClosingDay");
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    resolved.store.set(parsed.data.accountId, parsed.data.day);
+    return textResult(parsed.data);
+}
+export async function handleDeleteClosingDay(deps, rawInput) {
+    const startedAt = Date.now();
+    const parsed = deleteClosingDaySchema.safeParse(rawInput);
+    if (!parsed.success) {
+        return finishToolError(deps.log, startedAt, parsed.error.message, { tool: "deleteClosingDay" });
+    }
+    const resolved = resolveStore(deps, startedAt, "deleteClosingDay");
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    const deleted = resolved.store.delete(parsed.data.accountId);
+    return textResult({ accountId: parsed.data.accountId, deleted });
+}
+function resolveStore(deps, startedAt, tool) {
+    if (!deps.source.ok) {
+        return {
+            ok: false,
+            result: finishToolError(deps.log, startedAt, configurationProblems(deps.source.problems), { tool }),
+        };
+    }
+    if (deps.closingDays === null || deps.closingDays === undefined) {
+        return {
+            ok: false,
+            result: finishToolError(deps.log, startedAt, "Closing-day storage is unavailable.", { tool }),
+        };
+    }
+    return { ok: true, store: deps.closingDays };
+}
+//# sourceMappingURL=closing-days.js.map

package/dist/mcp/tools/closing-days.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closing-days.js","sourceRoot":"","sources":["../../../src/mcp/tools/closing-days.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/list-transactions.js

@@ -0,0 +1,122 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { isCategoryFilterValue } from "../../core/category.js";
+import { decodeCursor, encodeCursor } from "../cursor.js";
+import { toDecimal } from "../format.js";
+import { configurationProblems, finishToolError, textResult } from "./result.js";
+import { validateRange, validationMessage, toTransactionFilter } from "./transaction-input.js";
+const dateInput = z.string().regex(/^\d{4}-\d{2}-\d{2}$/u, "must be YYYY-MM-DD");
+const categoryInput = z.string().refine(isCategoryFilterValue, 'must be a known category id, or "none" for uncategorized');
+const listTransactionsInput = z.object({
+    startDate: dateInput,
+    endDate: dateInput,
+    categories: z.array(categoryInput).optional(),
+    minAmountCents: z.number().int().optional(),
+    maxAmountCents: z.number().int().optional(),
+    accountType: z.enum(["BANK", "CREDIT", "INVESTMENT", "LOAN"]).optional(),
+    accountSubtype: z.string().min(1).optional(),
+    limit: z.number().int().min(1).max(100),
+    cursor: z.string().optional(),
+}).superRefine(validateRange);
+export const LIST_TRANSACTIONS_DESCRIPTION = `Lists individual transactions over a date range with a bounded page size.
+
+Use this tool when:
+- You need the descriptions, amounts and ids behind an aggregate.
+- You need to inspect a page of matching transactions before requesting details.
+- You need to continue through a large result set with the returned cursor.
+
+- You need to find what has no category yet, by passing \`categories: ["none"]\`.
+
+Returns: Up to 100 transactions ordered newest first, with a cursor when more rows remain. Each row carries its category and \`categorySrc\`, which says where that category came from: \`override\` and \`counterparty\` are the user's own corrections, \`pluggy\` came from the bank data, and \`learned\` and \`mcc\` are inferred. The cursor belongs to the exact filters used for the request. If a connection is unavailable, available rows are returned with an explicit notice.`;
+export function registerListTransactions(server, deps) {
+    server.registerTool("listTransactions", { description: LIST_TRANSACTIONS_DESCRIPTION, inputSchema: listTransactionsInput }, async (input) => handleListTransactions(deps, input));
+}
+export async function handleListTransactions(deps, input) {
+    const startedAt = Date.now();
+    const parsed = listTransactionsInput.safeParse(input);
+    if (!parsed.success) {
+        return finishToolError(deps.log, startedAt, validationMessage(parsed.error), { outcome: "invalid-input" });
+    }
+    const log = deps.log.child({ tool: "listTransactions" });
+    log.info({}, "listTransactions started");
+    if (!deps.source.ok) {
+        return finishToolError(log, startedAt, configurationProblems(deps.source.problems), { problems: deps.source.problems.length });
+    }
+    if (deps.reader === null) {
+        return finishToolError(log, startedAt, "Transaction reader is unavailable.", { outcome: "reader-unavailable" });
+    }
+    return executeListTransactions({ deps, input: parsed.data, startedAt, log, reader: deps.reader });
+}
+async function executeListTransactions(options) {
+    const { deps, input, startedAt, log, reader } = options;
+    if (!deps.source.ok) {
+        return finishToolError(log, startedAt, configurationProblems(deps.source.problems), { problems: deps.source.problems.length });
+    }
+    try {
+        const loaded = await reader.load(deps.source.connections);
+        const filter = toTransactionFilter(input, loaded.accounts);
+        const after = cursorPosition(input.cursor, filter);
+        if (after.error !== null) {
+            return finishToolError(log, startedAt, after.error, { outcome: "invalid-cursor" });
+        }
+        const rows = reader.query(addPage(filter, input.limit, after.position));
+        const response = formatListResponse({ rows, limit: input.limit, filter, unavailable: loaded.unavailable });
+        log.info({ durationMs: Date.now() - startedAt, outcome: "ok", rows: rows.length }, "listTransactions finished");
+        return textResult(response);
+    }
+    catch (error) {
+        return finishToolError(log, startedAt, `Cannot list transactions: ${messageOf(error)}`, { outcome: "failure" });
+    }
+}
+function cursorPosition(cursor, filter) {
+    if (cursor === undefined) {
+        return { error: null };
+    }
+    const decoded = decodeCursor(cursor, filter);
+    if (!decoded.ok) {
+        return { error: `Invalid transaction cursor: ${decoded.message}.` };
+    }
+    return { position: decoded.position, error: null };
+}
+function addPage(filter, limit, after) {
+    if (after === undefined) {
+        return { ...filter, limit: limit + 1 };
+    }
+    return { ...filter, limit: limit + 1, after };
+}
+function formatListResponse(options) {
+    const page = options.rows.slice(0, options.limit);
+    let cursor;
+    if (options.rows.length > options.limit) {
+        const last = page.at(-1);
+        if (last !== undefined) {
+            cursor = encodeCursor({ localDate: last.localDate, id: last.id }, options.filter);
+        }
+    }
+    let notice;
+    if (options.unavailable.length > 0) {
+        notice = `Some connections were unavailable: ${options.unavailable.map(({ connectionId }) => connectionId).join(", ")}.`;
+    }
+    return {
+        transactions: page.map((row) => formatListRow(row)),
+        cursor,
+        notice,
+    };
+}
+function formatListRow(row) {
+    return {
+        id: row.id,
+        date: row.localDate,
+        descriptionNorm: row.descriptionNorm,
+        amount: toDecimal(row.amountCents),
+        category: row.category,
+        categorySrc: row.categorySrc,
+    };
+}
+function messageOf(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=list-transactions.js.map