feat(queries): filter engine for invoice queries — status, date, amount range

[maztah1]

What the issue was

#851 asked for a filter and query engine for listing invoices — client.queryInvoices(filter) accepting a single typed query object that filters by status, creator, date range, amount range and tags, returning a paginated Page with sorting. There was no such API. The SDK had getInvoicesByCreator (raw IDs only) and a separate compileFilter/applyFilter/FilterIndex module built around a recursive and/or FilterCriteria tree, which had no notion of dates, tags, sorting, or paging.

Approach

New module src/invoiceQuery.ts

• InvoiceFilter — { creator?, status?, minAmount?, maxAmount?, fromDate?, toDate?, tags?, limit?, cursor?, sort? }. All supplied fields combine with AND; within a field, status matches any listed state while tags requires every listed tag.
• InvoiceQueryEngine — filter → sort → paginate over an in-memory invoice set. Also exported as a standalone queryInvoices(invoices, filter) for callers who already hold the invoices and want no network calls.
• InvoiceTagIndex — tag → invoices lookup, exposed via engine.tagIndex().
• InvoicePage — { items, nextCursor?, total }. nextCursor is omitted (not null) on the final page; total always reports the unpaginated match count.

client.queryInvoices(filter) — cursor-pages the creator's invoice IDs, fetches each invoice, then applies the filter in memory.

Decisions worth flagging:

• creator is required. The contract exposes no global invoice index, so an unscoped query would be an unbounded full scan. This throws a ValidationError rather than silently enumerating everything — the existing getInvoicesByCreator remains available for manual paging.
• Amounts are compared as bigint, never narrowed through Number, since stroop totals routinely exceed 2^53. Covered by a test at 2^53 + 1.
• Dates accept Unix seconds or milliseconds, matching the convention Invoice.createdAt already documents. Invoices with no createdAt are excluded from date filters and sort last.
• Cursors are offset-based (off:<n>), since sorting can reorder the underlying set; an offset stays deterministic for a given (filter, sort) pair. Ties break on invoice ID so pages never repeat or skip.
• Tags fall back to #hashtags parsed from the memo when an invoice has no explicit tags field, so existing invoices are taggable with no contract change. I added an optional tags?: string[] to Invoice for the explicit case.

How it was tested

57 new tests in test/invoiceQuery.test.ts, all passing:

• Each filter independently — creator, status (single and multi), min/max amount, from/to date, explicit tags, memo-derived tags, plus inclusive bounds, multi-recipient totals, and >2^53 amounts.
• Combined filters — a case where four of five candidates each fail exactly one predicate.
• Sorting — all four orders asserted by exact ID sequence, tie-breaking, and undated-invoice placement.
• Pagination — default and explicit limits, nextCursor presence/absence, total stability across pages, a full multi-page walk asserting no gaps or duplicates, and a cursor past the end.
• Empty results — no matches, empty input, unknown tag.
• Validation — inverted ranges, non-positive limit, unknown sort, malformed cursor.
• Client integration — queryInvoices against a stubbed client, including that it rejects a missing creator.

Full suite: 213 passed, 1 skipped, 0 failed. tsc --noEmit output diffed against the base branch to confirm no new errors (the repo has pre-existing type errors unrelated to this change).

Note: package.json's test script only runs two specific files; I ran the full suite via npx vitest run.

closes #851

[drips-wave]

@maztah1 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits