feat(data-access): add Token.allBySiteId with optional tokenTypes/cycle filters

[sandsinh]

Summary

Adds TokenCollection.allBySiteId(siteId, options) to @adobe/spacecat-shared-data-access. The method returns all tokens for a site in a single PostgREST round-trip, with optional tokenTypes (array, IN-filtered) and cycle (string, eq-filtered) narrowing. All four filter combinations are index-backed:

Filters	Index used
siteId + cycle	tokens_site_id_cycle_idx (new — see mysticat-data-service#498)
siteId + cycle + tokenTypes	tokens_site_id_cycle_idx + IN filter
siteId + tokenTypes	tokens_site_id_token_type_cycle_key prefix
siteId only	tokens_site_id_token_type_cycle_key prefix

This replaces the previous app-layer fan-out pattern (one call to findBySiteIdAndTokenType per type with cycle filtering in the controller) with a single query.

Why

The API controller (spacecat-api-service) needs to load multiple tokens for a site/cycle to compute remaining grant quotas. Today it parallelises N calls to findBySiteIdAndTokenType and then filters by cycle — N HTTP round-trips and a query path that won't scale once tokenTypes becomes wildcard-able. Pushing this into the data-access layer:

• Cuts to one round-trip regardless of |tokenTypes|.
• Lets callers omit tokenTypes (e.g. for an admin/all-types view) without falling into a full table scan, now that the (site_id, cycle) index exists.
• Centralises siteId / cycle / tokenTypes validation.

Changes

• src/models/token/token.collection.js — new allBySiteId(siteId, { tokenTypes?, cycle?, ...queryOptions }) method. Uses this.all({ siteId, cycle? }, { where: op.in(tokenType, …) }) so PostgREST emits a single WHERE site_id = ? AND cycle = ? AND token_type IN (…) query. Filter keys are stripped from the forwarded options.
• test/unit/models/token/token.collection.test.js — 9 new unit tests covering all four filter combinations, option forwarding, and validation errors. 100% coverage on token.collection.js.
• test/it/token/token.test.js — 10 new integration tests against PostgREST + Aurora (uses fixtures.sites[1] and historical cycles 2099-01 / 2099-02 to avoid colliding with the existing findBySiteIdAndTokenType / grantSuggestions suites).

Related

• Depends on the (site_id, cycle) index added in mysticat-data-service#498
• SITES-43808

Test plan

• npm test -w packages/spacecat-shared-data-access — 1913 passing, 100% lines on token.collection.js
• npm run lint -w packages/spacecat-shared-data-access — clean
• npm run test:it -w packages/spacecat-shared-data-access — full token IT suite passes (23 tests; 10 new + 13 pre-existing)
• Consumer follow-up in spacecat-api-service to swap the controller's parallel findBySiteIdAndTokenType loop for one allBySiteId call once the new version ships

[github-actions]

This PR will trigger a patch release when merged.