Search & Pagination
Every */search operation is a POST that shares one request DSL and returns a PagedList<T> envelope.
The request shape
const page = await zr.parcels.search({
pageNumber: 1, // 1-based, min 1
pageSize: 25, // 1–1000
orderBy: ['createdAt desc', 'amount asc'],
keyword: 'amine', // simple search across default fields
advancedSearch: { // targeted keyword search
fields: ['trackingNumber', 'customer.name'],
keyword: 'amine',
},
advancedFilter: { // structured filter (see below)
field: 'state.id',
operator: 'eq',
value: stateId,
},
});Field paths are dotted camelCase into the response DTO (customer.name, state.id).
advancedFilter
A filter node is either a leaf or a branch.
A leaf targets one field:
{ field: 'level', operator: 'eq', value: 'wilaya' }A branch combines leaves with a single logic per level (and / or — no mixing within one node):
{
logic: 'and',
filters: [
{ field: 'state.id', operator: 'eq', value: stateId },
{ field: 'amount', operator: 'gte', value: 1000 },
],
}Operators
eq, neq, contains, startswith, endswith, gt, lt, gte, lte (availability depends on the field type).
Validate paging client-side
The live server tolerates out-of-range paging (pageNumber: 0 returned 200 with defaults, not 400 — drift §9.5). Don't rely on server validation for client bugs.
The PagedList<T> envelope
interface PagedList<T> {
items: T[];
pageNumber: number;
pageSize: number;
totalCount: number;
totalPages: number;
hasPrevious: boolean;
hasNext: boolean;
}See the generated PagedList.
Auto-paging
Every search method exposes a searchAll async iterator built on paginate(). It advances pageNumber itself, stops on hasNext === false, guards against servers that never terminate (the page must advance), and respects an optional maxItems:
let count = 0;
for await (const parcel of zr.parcels.searchAll({ pageSize: 200 }, { maxItems: 1000 })) {
count++;
}Sub-resource searches expose their own iterators (e.g. zr.pickupBags.searchParcelsAll(trackingNumber, body), zr.claims.searchCommentsAll(claimId, body), zr.treasury.searchPaymentsAll(body)).
You can also call paginate() directly:
import { paginate } from '@terminaldz/zrexpress-sdk';
for await (const item of paginate((b) => zr.customers.search(b), { pageSize: 100 })) {
// …
}