feat: read the settled royalty ledger so consumers stop paging payouts by hand

[robrigo]

Why

The Explorer client reads a collection's royalty configuration but not what the contract has actually paid, so a marketplace or a payout dashboard has to page the raw payout logs itself. The indexer serves the settled ledger, its count, and per-account totals, one row per token symbol. This adds getRoyaltyPayouts, countRoyaltyPayouts, and getRoyaltyAccount with typed rows, filters, and enums, and widens IRoyaltyConfig, IRoyaltyTemplateRule, and IRoyaltyAttributeRule with the row fields the indexer returns.

Reading a response is unaffected by the widening. Code that builds one of those rows by hand, such as a test mock, must supply the added fields; the release entry records that under a breaking-changes heading, as the 2.0.1 entry did for BuyofferState. IRoyaltyPayout.listing_type and category are nullable because the indexer's formatter emits null for a stored value outside the served vocabulary.

Validation

yarn check-types, yarn lint, and yarn test pass at 141 tests (135 before). The six new tests pin the three URLs and their query strings against the fetch stub, the parse of the count string, the percent-encoding of a hostile account name, the enum members, and the row types against indexer-shaped rows with the nullable ids in both states.

[Copilot]

Pull request overview

Adds a typed read surface for the AtomicMarket v2 settled royalty payout ledger so SDK consumers can query payouts, counts, and per-account token totals without paging raw on-chain logs.

Changes:

• Adds getRoyaltyPayouts, countRoyaltyPayouts, and getRoyaltyAccount to AtomicMarketApi, with new filter param types for ledger paging and account aggregation.
• Introduces royalty-ledger enums (RoyaltyListingType, RoyaltyPayoutCategory, RoyaltyPayoutSort) and new row types (IRoyaltyPayout, IRoyaltyAccountTotal); widens existing royalty config/rule row interfaces to match indexer-returned fields.
• Adds/updates tests and README documentation to pin enum vocabularies, URL/query construction, and row shapes (including nullable enum fields).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/types.test.ts	Adds type-level assertions for new royalty row types and pins served enum vocabularies.
test/royalties-api.test.ts	Adds endpoint/query-string tests for the three new royalty-ledger read methods and count parsing.
src/API/Explorer/Params.ts	Introduces RoyaltyPayoutApiParams and RoyaltyAccountApiParams filter types.
src/API/Explorer/Objects.ts	Adds IRoyaltyPayout / IRoyaltyAccountTotal and widens royalty config/rule interfaces to indexer shapes.
src/API/Explorer/index.ts	Implements getRoyaltyPayouts, countRoyaltyPayouts, and getRoyaltyAccount on AtomicMarketApi.
src/API/Explorer/Enums.ts	Adds royalty-ledger vocabulary enums for listing type, payout category, and sort.
README.md	Documents the settled royalty ledger read APIs, semantics (nullable fields), and 2.4.0 release notes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.