Programmatic Pagination with the SDK

View Markdown

Use pagination when your application renders a ranked recommendation list or a SmartSort result in pages. Request the full ranking with list_size and return only the first page with limit. Froomle must enable pagination for your environment before later pages are available.

The SDK offers two ways to retrieve more items:

First request Page-number method Result of a later page

getRecommendations(…​) with list_size greater than limit

response.lists()[i].pagination.getPage(pageNumber)

One RecommendationList with items. Each list in a multi-list response can be paged independently.

smartSort({ candidates, limit, pagination: true })

result.pagination.getPage(pageNumber)

A SmartSort result with items, entries, and sortedCandidates mapped to the original candidates.

Either first request, if you saved its listKey

getListSlice({ listKey, offset, limit })

A Recommendations response containing raw recommendation items. Use this for an arbitrary rank range or after a page reload.

Choose pagination.getPage(pageNumber) when you have the first result in memory and want consecutive pages at its fixed limit. Use the recommendation list’s helper for getRecommendations(…​); use the SmartSort result’s helper when you need candidate objects mapped on every page. Choose getListSlice(…​) when you only have a saved listKey after a reload or need a different starting rank or count. A slice gives you recommendation items; your application maps SmartSort item IDs back to products.

pageNumber starts at 1: the initial result is page 1. getPage(2) uses the initial limit as its fixed page size. offset in getListSlice is also 1-based, but means the rank of the first item to return, not a page number or a count of skipped items.

Initial limit Page number Slice { offset, limit } Ranks requested

20

1

{ offset: 1, limit: 20 }

1 through 20

20

2

{ offset: 21, limit: 20 }

21 through 40

20

3

{ offset: 41, limit: 20 }

41 through 60

The SDK does not provide a total page count. A list can contain fewer items than list_size, and its final page can be short or empty. Your application owns page controls, rendering, and recommendation impression/click tracking.

Page through recommendations

getRecommendations(…​) returns a Recommendations object, even when pagination is available. Read the list you want to display from lists(), then page that list. The pagination property sits beside its items.

import { getRecommendations } from '@froomle/frontend-sdk'

const response = await getRecommendations([
  { list_name: 'recommended_for_you', list_size: 100, limit: 20 },
])
const firstList = response.lists()[0]
renderItems(firstList.items) // Ranks 1 through 20

if (firstList.pagination) {
  const secondList = await firstList.pagination.getPage(2)
  renderItems(secondList.items) // Ranks 21 through 40, if available
}

firstList.pagination.pageNumber is 1, pageSize is 20, and offset is 1. The second list has pageNumber: 2, pageSize: 20, and offset: 21. Subsequent getPage(…​) calls keep the first page’s size. If the initial response has no usable list_key, pagination is null and only the initial items are available.

Page through SmartSort results

Pass the full candidate set to smartSort(…​). The SDK ranks that set once and returns the first limit items. Set pagination: true to get page controls on the result.

import { smartSort } from '@froomle/frontend-sdk'

const firstPage = await smartSort({
  list_name: 'search_results_rerank',
  candidates: allMatchingProducts,
  getId: (product) => product.sku,
  getItemType: () => 'product',
  limit: 24,
  pagination: true,
})
renderProducts(firstPage.sortedCandidates) // Ranks 1 through 24

const secondPage = await firstPage.pagination.getPage(2)
renderProducts(secondPage.sortedCandidates) // Ranks 25 through 48, if available

Each page also has items, entries, and pagination. The SDK maps later pages back to the candidates supplied in the first call, so this helper needs that first result in memory. Paginated SmartSort results do not include unmatchedCandidates: candidates absent from one page can appear on another. firstPage.pagination.listKey is null when later pages are unavailable; in that case, getPage(2) rejects. Customer-managed benchmark control order cannot be combined with SmartSort pagination. See Programmatic SmartSort for candidate mapping and tracking details.

Retrieve a rank range by list key

Save the key from firstList.pagination.listKey or firstPage.pagination.listKey while it is available. getListSlice(…​) works with keys from either flow, including in a later request after a page reload. Choose any positive starting rank and count; this call does not inherit the first page’s limit.

import { getListSlice } from '@froomle/frontend-sdk'

// savedListKey came from a recommendation list or a SmartSort result.
const slice = await getListSlice({
  listKey: savedListKey,
  offset: 25,
  limit: 12,
})
const rankedItems = slice.lists()[0].items // Ranks 25 through 36, if available

The return value is a Recommendations object: use slice.lists()[0].items or slice.items(). It has no attached pagination.getPage(…​) helper. For a SmartSort key, it does not restore the original candidate objects or sortedCandidates; use the returned item IDs to load your product data and preserve the returned rank order.

The saved key is valid only while the ranked list is available. If it expires, the API returns HTTP 404 and you must make a new initial request. The SDK rejects missing keys, non-integer page numbers, and offsets or limits below 1 before requesting a later page. See Manual API pagination for the underlying endpoint contract.