Pagination, filtering and sorting

New list routes page with keyset cursors: ?limit= (1 to 200, default 50) and ?cursor=. The answer is { "data": [...], "nextCursor": "…" }, with nextCursor null on the last page, and a Link: <…?cursor=…>; rel="next" header. No documented route uses it yet: the ones that page today predate it, and are listed below.

• Cursors are opaque: pass them back as given. One from elsewhere is a 400 invalid_cursor.
• There’s no offset paging over large tables: a cursor stays correct while rows are added.

A few routes predate the convention, or mirror a page on the site. The reference marks them “Paginated”; here’s how each one pages:

• GETAudit logpass the last page’s nextCursor as before
• GETSearch peoplestep offset by the page size until total
• GETA publisher or imprintpage through the series browser from 1 until total
• GETA shop’s storefrontpage from 1 until count is covered

The SDK knows each of these, so one loop walks any of them:

import { createCollectorClient } from '@collector/sdk';

const collector = createCollectorClient();

// Every listing on a shop's shelves, across pages, with the shop's own filters.
for await (const listing of collector.paginate('getPublicStorefront', {
  path: { slug: 'some-shop' },
  query: { sort: 'price_asc' },
})) {
  console.log(`${listing.issue.seriesTitle} #${listing.issue.number}`, listing.priceCents, listing.currency);
}

// Or whole pages at a time.
for await (const page of collector.pages('getPublicStorefront', { path: { slug: 'some-shop' } })) {
  console.log(`page ${page.inventory.page}: ${page.inventory.listings.length} of ${page.inventory.count}`);
}

• Filters: ?filter[field]=value, each field from a list the route allows. An unknown field or a bad value is 400 invalid_filter, naming what’s allowed.
• Sorting: ?sort=field,-other: a leading - means descending, from the route’s allowed fields; anything else is 400 invalid_sort.
• Routes older than the convention take plain parameters (status, sort, q…): each one’s are in the reference.