feat: SITES-40623 - token system in Spacecat by sandsinh · Pull Request #1414 · adobe/spacecat-shared

sandsinh · 2026-03-09T13:12:27Z

Summary

Add SuggestionGrant entity: New model, collection, schema, and TypeScript definitions for the suggestion_grants table. The collection provides splitSuggestionsByGrantStatus, isSuggestionGranted,
grantSuggestions, and findBySuggestionIds — centralizing all grant-related data access previously spread across the Suggestion collection.
Add Token entity: New model, collection, and schema for the tokens table. TokenCollection.findBySiteIdAndTokenType resolves the current-cycle token (auto-creating if createIfNotFound: true), and
Token.getRemaining() computes available tokens (total - used).
Bump data-service Docker image: Updated from v1.19.0 to v1.23.0 for integration tests (includes suggestion_grants, tokens tables, and grant_suggestions RPC).

Changes

New: SuggestionGrant (src/models/suggestion-grant/)

suggestion-grant.schema.js — Schema with suggestionId, grantId, siteId, tokenId, tokenType, grantedAt (all read-only). updatedAt/updatedBy marked postgrestIgnore (insert-only table).
suggestion-grant.collection.js — findBySuggestionIds (bulk lookup), splitSuggestionsByGrantStatus (partition into granted/not-granted), isSuggestionGranted (single-ID check), grantSuggestions
(resolves token, calls grant_suggestions RPC), invokeGrantSuggestionsRpc (raw RPC call).
suggestion-grant.model.js — Minimal model extending BaseModel.
index.js / index.d.ts — Exports and TypeScript interface definitions.

New: Token (src/models/token/)

token.schema.js — Schema with siteId, tokenType, cycle, total, used. Composite index on (siteId, tokenType) + cycle.
token.collection.js — findBySiteIdAndTokenType(siteId, tokenType, options) resolves current-cycle token using getTokenGrantConfig from spacecat-shared-utils; creates token if createIfNotFound: true
with total = min(options.total, config.tokensPerCycle).
token.model.js — getRemaining() returns max(0, total - used). Static TOKEN_TYPES enum.

Modified

entity.registry.js — Registered SuggestionGrant and Token entities.
models/index.js — Re-exported new entity modules.
postgrest.utils.js — Added SuggestionGrant: 'suggestion_grants' table override.
suggestion.schema.js — Added optional suggestionKey attribute.

Tests

Unit tests: suggestion-grant.collection.test.js (416 lines), suggestion-grant.model.test.js, token.collection.test.js, token.model.test.js, token.schema.test.js, suggestion.model.test.js (updated for
suggestionKey).
Integration tests: suggestion-grant.test.js, suggestion.test.js (grant flow), token.test.js, all-collections-methods-coverage.test.js (updated for new entities). Docker image bumped to v1.23.0.

Test plan

Unit tests for all new collection methods, model methods, and schema validation
Integration tests against real PostgREST (Docker) for token lifecycle and grant flow
splitSuggestionsByGrantStatus correctly partitions granted vs. not-granted IDs
grantSuggestions consumes a token and inserts grant rows via RPC
findBySiteIdAndTokenType auto-creates tokens when createIfNotFound: true
Token.getRemaining() returns correct value and clamps to 0
Error paths: invalid inputs throw DataAccessError, RPC failures propagate correctly
All existing tests continue to pass

Related Issue

Motivation and Context

Sites need a capped number of granted suggestions per opportunity type and cycle. The shared library adds:

Token schema so clients can read/create token rows and resolve current-cycle allocation.
Grant config in utils so cycle and per-cycle limits are defined in one place and reused (e.g. by TokenCollection for creation and cycle).
Suggestion grants so UI/API can show which suggestions were granted and with which cycle/token.
grantSuggestion so callers can grant by IDs without touching RPC or token creation directly; token creation for the current cycle happens on first use.

How Has This Been Tested?

spacecat-shared-utils: token-grant-config.test.js — TOKEN_GRANT_CONFIG shape, tokensPerCycle/cycle/cycleFormat per type, getTokenGrantConfig returns correct values and currentCycle, unknown type returns undefined, and that config is immutable (e.g. copy, not reference).
spacecat-shared-data-access:
- Token: token.schema.test.js, token.model.test.js, token.collection.test.js (e.g. findBySiteIdAndTokenType with create/upsert and config).
- Suggestions: suggestion.collection.test.js — grantSuggestion calls findBySiteIdAndTokenType, checks remaining, invokes RPC with correct params; returns no_tokens when remaining < count and does not call RPC; handles RPC error and RPC granted: false.
- Integration: test/it/token/token.test.js and suggestion ITs where applicable.

Please ensure your pull request adheres to the following guidelines:

make sure to link the related issues in this description
when merging / squashing, make sure the fixed issue references are visible in the commits, for easy compilation of release notes

Related Issues

Thanks for contributing!

Made-with: Cursor # Conflicts: # packages/spacecat-shared-data-access/src/models/entitlement/entitlement.collection.js # packages/spacecat-shared-data-access/test/unit/models/entitlement/entitlement.collection.test.js

github-actions · 2026-03-09T13:38:02Z

This PR will trigger a minor release when merged.

…ES-40623-spacecat-shared-utils PR) Made-with: Cursor

Kanishkavijay39 · 2026-03-17T18:20:58Z

verview

Adds two new entities (Token, SuggestionGrant) to implement a capped suggestion grant system. Tokens track per-site, per-cycle allocation; SuggestionGrant records
which suggestions were granted and via which token. Includes a grantSuggestions high-level method that checks token balance, calls a PostgREST RPC, and returns
results.

Critical Issues

Production dependency pinned to a GitHub Gist tarball

"@adobe/spacecat-shared-utils": "https://gist.githubusercontent.com/sandsinh/e6c7d5895ece4f0ad3b32a64701faf3b/raw/..."

This is the most significant blocker. The Gist URL:

Can be deleted or edited by the author at any time
Has no integrity hash — supply chain risk
Is not reproducible (the raw/ URL with a commit SHA is stable, but the dependency is not from the registry)
Signals PR feat: SITES-40623 - token system in Spacecat #1414 depends on PR feat(spacecat-shared-utils): SITES-40623 - add token grant config and exports #1420 not yet being merged/published

This PR must not be merged until #1420 is published to npm and the dependency is updated to a proper semver reference.

grantSuggestions token check is wrong for batch grants

// suggestion-grant.collection.js
if (token.getRemaining() >= 1) { ... }

This only checks that at least 1 token remains. If suggestionIds.length > token.getRemaining(), the RPC is still called with all IDs. The check should be:

if (token.getRemaining() >= suggestionIds.length) { ... }

Unless the intent is that the entire batch consumes exactly 1 token (not 1 per suggestion), which is not documented anywhere in the code or PR description.

Design & Architecture Issues

Cross-entity coupling inside a collection

SuggestionGrantCollection.grantSuggestions reaches into entityRegistry to resolve TokenCollection:

const tokenCollection = this.entityRegistry.getCollection('Token');

This is unusual for this codebase — collections typically don't resolve sibling collections. It creates hidden coupling and makes the method harder to test in
isolation. Consider moving this orchestration to the service layer, or at minimum documenting it as intentional.

findBySuggestionIds and invokeGrantSuggestionsRpc return raw { data, error } PostgREST responses

These two methods bypass the standard entity-level error handling the rest of the layer uses (DataAccessError). If PostgREST returns an error, callers of
findBySuggestionIds get a raw error object rather than a thrown exception. This is inconsistent — grantSuggestions does handle the error from
invokeGrantSuggestionsRpc, but findBySuggestionIds callers must handle { data, error } themselves.

invokeGrantSuggestionsRpc is public

It's a raw implementation detail exposed on the collection. It should be private (rename to #invokeGrantSuggestionsRpc or document as internal-only). Exposing it
invites callers to bypass grantSuggestions's token-check logic.

Code-Level Issues

Token.getRemaining() uses fragile optional chaining

getRemaining() {
const total = this.getTotal?.() ?? this.total ?? 0;
const used = this.getUsed?.() ?? this.used ?? 0;
return Math.max(0, total - used);
}

this.getTotal?.() with ?. implies getTotal might not exist. In this codebase, BaseModel generates getters from the schema — they'll always exist. The fallback to
this.total is unnecessary and potentially masks a bug if the schema generation changes. Should be simply:

return Math.max(0, this.getTotal() - this.getUsed());

token.schema.js — total is readOnly but created by the collection

readOnly on total prevents updates, which is intentional — total is set at creation time. But the name is slightly misleading. A comment clarifying "set at creation,
never updated" would help.

docker-compose.yml — pull_policy: always

pull_policy: ${MYSTICAT_DATA_SERVICE_PULL_POLICY:-always}

Defaults to always, meaning every local npm run test:it run re-pulls the Docker image even if it's already present. This significantly slows local dev. The default
should be missing (only pull if not cached locally), with always available for CI via the env var override. The previous behaviour had no pull_policy, which Docker
Compose defaults to missing.

Test Coverage

Strengths:

Good unit test coverage for all new methods including error paths
Integration tests cover token exhaustion (no_tokens) scenario
Mutation guards and undefined input cases are tested

Minor Issues

suggestion-grant.schema.js marks updatedAt/updatedBy as postgrestIgnore — fine for an insert-only table, but a comment explaining why would help future readers
PR description mentions integration test coverage for grantSuggestions via Suggestion, but SuggestionGrantCollection.grantSuggestions appears to live in
suggestion-grant, not suggestion — the PR description mixes these up

Kanishkavijay39 · 2026-03-17T19:08:39Z

packages/spacecat-shared-data-access/src/models/suggestion-grant/suggestion-grant.collection.js

+      .from(this.tableName)
+      .select('suggestion_id,grant_id')
+      .in('suggestion_id', suggestionIds);
+    return { data: data ?? [], error };


We can throw DataAccessError in case of failure

Kanishkavijay39 · 2026-03-17T19:17:00Z

packages/spacecat-shared-data-access/src/models/suggestion-grant/suggestion-grant.collection.js

+      throw new DataAccessError('grantSuggestions: tokenType is required', this);
+    }
+
+    const tokenCollection = this.entityRegistry.getCollection('TokenCollection');


Design concern: Collections typically don't call into other collections via entityRegistry. This cross-entity coupling is atypical for this codebase orchestration usually lives in the service layer.

We are using it in some collections. So it should be good.

Kanishkavijay39 · 2026-03-17T19:17:25Z

packages/spacecat-shared-data-access/src/models/suggestion-grant/suggestion-grant.collection.js

+    const tokenCollection = this.entityRegistry.getCollection('TokenCollection');
+    const token = await tokenCollection.findBySiteIdAndTokenType(siteId, tokenType);
+
+    if (!token || token.getRemaining() < 1) {


Critical bug: token.getRemaining() >= 1 only checks if at least one token remains. If you pass 5 suggestionIds but only 2 tokens remain, it still proceeds. Should be

= suggestionIds.length (assuming 1 token per suggestion) or the semantics need documenting.

1 token could grant multiple suggestions in some cases, no need for check on suggestionIds.

packages/spacecat-shared-data-access/src/models/token/token.model.js

## [@adobe/spacecat-shared-data-access-v3.24.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.23.0...@adobe/spacecat-shared-data-access-v3.24.0) (2026-03-19) ### Features * SITES-40623 - token system in Spacecat ([#1414](#1414)) ([9c540ba](9c540ba))

solaris007 · 2026-03-19T12:02:44Z

🎉 This PR is included in version @adobe/spacecat-shared-data-access-v3.24.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

sandsinh added 3 commits February 17, 2026 14:50

feat: SITES-40623 - token system in Spacecat

788de85

Merge branch 'main' into SITES-40623

1ee7367

Made-with: Cursor # Conflicts: # packages/spacecat-shared-data-access/src/models/entitlement/entitlement.collection.js # packages/spacecat-shared-data-access/test/unit/models/entitlement/entitlement.collection.test.js

fix: adds grant suggestion

9dc72ff

sandsinh marked this pull request as draft March 9, 2026 13:12

fix: cleanup

5240910

sandsinh and others added 9 commits March 10, 2026 11:40

fix: update schema

46178f4

fix: remove unnecessary changes

2057799

fix: revert unnecessary changes

a4e071a

Merge branch 'main' into SITES-40623

eb758a5

chore: remove spacecat-shared-utils token grant changes (moved to SIT…

0012617

…ES-40623-spacecat-shared-utils PR) Made-with: Cursor

fix: adds utils lib

54845cd

fix: update package lock

128a258

Merge branch 'main' into SITES-40623

ad4331c

Merge branch 'main' into SITES-40623

cc18b56

sandsinh marked this pull request as ready for review March 10, 2026 12:03

sandsinh added 12 commits March 11, 2026 01:02

fix: update token schema

99ff418

fix: remove unnecessary code

0040232

fix: update token schema

b84160f

fix: adds collection functions

3b83205

fix: adds grant id in the response

6c2f758

fix: update docker image

d9c777b

fix: adds coverage

04b6231

Merge branch 'main' into SITES-40623

4e5c65a

fix: adds Suggestion grants schema

b6569d5

fix: update package

e0b5928

fix: remove unnecessary changes

07de127

Merge branch 'main' into SITES-40623

7124f1d

sandsinh requested a review from Kanishkavijay39 March 17, 2026 08:50

Kanishkavijay39 requested changes Mar 17, 2026

View reviewed changes

sandsinh added 3 commits March 18, 2026 10:02

fix: address review comments

a8e2fdf

Merge branch 'main' into SITES-40623

1f3882c

fix: update package.json

173eb01

Kanishkavijay39 approved these changes Mar 19, 2026

View reviewed changes

sandsinh added 6 commits March 19, 2026 16:27

Merge branch 'main' into SITES-40623

d65d42a

fix: update deps

c15470a

fix: update package-lock

ef50c71

fix: update IT tests

1b15883

fix: IT test

52c77dc

fix: cleanups

9fa3bf4

sandsinh merged commit 9c540ba into main Mar 19, 2026
7 checks passed

sandsinh deleted the SITES-40623 branch March 19, 2026 11:54

solaris007 added the released label Mar 19, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: SITES-40623 - token system in Spacecat#1414

feat: SITES-40623 - token system in Spacecat#1414
sandsinh merged 34 commits intomainfrom
SITES-40623

sandsinh commented Mar 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 9, 2026

Uh oh!

Kanishkavijay39 commented Mar 17, 2026

Uh oh!

Kanishkavijay39 Mar 17, 2026

Uh oh!

sandsinh Mar 18, 2026

Uh oh!

Kanishkavijay39 Mar 17, 2026

Uh oh!

sandsinh Mar 18, 2026

Uh oh!

Kanishkavijay39 Mar 17, 2026

Uh oh!

sandsinh Mar 18, 2026

Uh oh!

Uh oh!

Uh oh!

solaris007 commented Mar 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

sandsinh commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issue

Motivation and Context

How Has This Been Tested?

Related Issues

Uh oh!

github-actions bot commented Mar 9, 2026

Uh oh!

Kanishkavijay39 commented Mar 17, 2026

Uh oh!

Kanishkavijay39 Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

sandsinh Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Kanishkavijay39 Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

sandsinh Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Kanishkavijay39 Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

sandsinh Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

solaris007 commented Mar 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sandsinh commented Mar 9, 2026 •

edited

Loading