From 509f27344381acf24a5255a5de3696a97ef7c049 Mon Sep 17 00:00:00 2001 From: Deluan Date: Sat, 8 Aug 2026 15:19:36 -0400 Subject: [PATCH] docs(plugins): warn against setting ScrobbleOptions.Offset manually The all-ties carry rule assumes Offset counts already-returned rows at the boundary timestamp, which only holds for the options GetScrobbles returns. A hand-built From+Offset combination can silently skip scrobbles, so document the field as managed pagination state instead of a generic skip. --- plugins/host/scrobble_retriever.go | 6 +++--- plugins/pdk/go/host/nd_host_scrobbleretriever.go | 2 +- plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go | 2 +- .../pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/host/scrobble_retriever.go b/plugins/host/scrobble_retriever.go index b1bb1e19c..2582dd650 100644 --- a/plugins/host/scrobble_retriever.go +++ b/plugins/host/scrobble_retriever.go @@ -25,8 +25,8 @@ type ScrobbleOptions struct { // The maximum number of items to retrieve. This is capped at 5000, the // default if not specified MaxItems int `json:"maxItems"` - // How many scrobbles to skip. GetScrobbles sets this on the options it returns for - // the next page; plugins never need to set it themselves + // Pagination state managed by GetScrobbles; only meaningful on the options it returns. + // Never set it or combine it with your own timestamps — scrobbles may be silently skipped Offset int `json:"offset,omitempty"` } @@ -64,7 +64,7 @@ type ScrobbleRetrieverService interface { // - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble // - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest // - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000 - // - options.Offset: How many scrobbles to skip. Comes pre-set on the options returned by a previous call + // - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually // // Returns: // - scrobbles: The scrobbles in the requested range, ordered by submission time diff --git a/plugins/pdk/go/host/nd_host_scrobbleretriever.go b/plugins/pdk/go/host/nd_host_scrobbleretriever.go index 7b6b283c0..596d7ec1d 100644 --- a/plugins/pdk/go/host/nd_host_scrobbleretriever.go +++ b/plugins/pdk/go/host/nd_host_scrobbleretriever.go @@ -179,7 +179,7 @@ func ScrobbleRetrieverGetLastTimestamp(username string) (*int64, error) { // - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble // - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest // - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000 -// - options.Offset: How many scrobbles to skip. Comes pre-set on the options returned by a previous call +// - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually // // Returns: // - scrobbles: The scrobbles in the requested range, ordered by submission time diff --git a/plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go b/plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go index 2a5bb10fb..8fe6a694e 100644 --- a/plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go +++ b/plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go @@ -87,7 +87,7 @@ func (m *mockScrobbleRetrieverService) GetScrobbles(username string, options Scr // - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble // - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest // - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000 -// - options.Offset: How many scrobbles to skip. Comes pre-set on the options returned by a previous call +// - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually // // Returns: // - scrobbles: The scrobbles in the requested range, ordered by submission time diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs index b64201748..fe80d98f6 100644 --- a/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs +++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs @@ -169,7 +169,7 @@ pub fn get_last_timestamp(username: &str) -> Result, Error> { /// - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble /// - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest /// - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000 -/// - options.Offset: How many scrobbles to skip. Comes pre-set on the options returned by a previous call +/// - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually /// /// Returns: /// - scrobbles: The scrobbles in the requested range, ordered by submission time