fix: adds a function to get latest token by createdAt (#1597)

## Summary
- Adds `findLastCreatedBySiteIdAndTokenType` to `TokenCollection` to
retrieve the most recently created token for a given site and token
type, regardless of cycle
- Useful when callers need the latest token across all cycles rather
than a specific cycle
- Validates required parameters and throws `DataAccessError` on missing
input

## Test plan
- [ ] Unit tests pass: `npm test -w
packages/spacecat-shared-data-access`
- [ ] Integration tests pass: `npm run test:it -w
packages/spacecat-shared-data-access` (requires Docker)
- [ ] Verify `findLastCreatedBySiteIdAndTokenType` returns null when no
tokens exist for a site/type
- [ ] Verify it returns the most recently created token when multiple
cycles exist
- [ ] Verify it throws when `siteId` or `tokenType` is missing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Sandesh Sinha <sandsinh@Sandeshs-MacBook-Pro.local>

Author: sandsinh

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

@@ -42,6 +42,21 @@ class TokenCollection extends BaseCollection {
    * @returns {Promise<import('./token.model.js').default|null>} Token instance
    *   (existing or newly created), or null when none exists and createIfNotFound is false.
    */
+  /**
+   * Finds the most recently created Token for a given siteId and tokenType,
+   * regardless of cycle. Returns null if no token exists.
+   *
+   * @param {string} siteId - Site ID (UUID).
+   * @param {string} tokenType - Token type (e.g. grant_cwv, grant_broken_backlinks).
+   * @returns {Promise<import('./token.model.js').default|null>} The last created Token, or null.
+   */
+  async findLastCreatedBySiteIdAndTokenType(siteId, tokenType) {
+    if (!hasText(siteId) || !hasText(tokenType)) {
+      throw new DataAccessError('TokenCollection.findLastCreatedBySiteIdAndTokenType: siteId and tokenType are required');
+    }
+    return this.findByIndexKeys({ siteId, tokenType }, { order: 'desc' });
+  }
+
   async findBySiteIdAndTokenType(siteId, tokenType, options = {}) {
     if (!hasText(siteId) || !hasText(tokenType)) {
       throw new DataAccessError('TokenCollection.findBySiteIdAndTokenType: siteId and tokenType are required');

packages/spacecat-shared-data-access/test/it/token/token.test.js

@@ -95,6 +95,63 @@ describe('Token IT', () => {
     });
   });
 
+  describe('findLastCreatedBySiteIdAndTokenType', () => {
+    // sites[2] — no tokens seeded for this site, so tests start clean
+    const siteId = '56a691db-d32e-4308-ac99-a21de0580557';
+    const tokenType = 'grant_cwv';
+
+    it('returns null when no token exists for the site and token type', async () => {
+      const token = await Token.findLastCreatedBySiteIdAndTokenType(siteId, tokenType);
+      expect(token).to.be.null;
+    });
+
+    it('returns the token when exactly one cycle exists', async () => {
+      const created = await Token.create({
+        siteId,
+        tokenType,
+        cycle: '2025-01',
+        total: 3,
+        used: 0,
+      });
+
+      const found = await Token.findLastCreatedBySiteIdAndTokenType(siteId, tokenType);
+
+      expect(found).to.be.an('object');
+      expect(found.getSiteId()).to.equal(siteId);
+      expect(found.getTokenType()).to.equal(tokenType);
+      expect(found.getCycle()).to.equal('2025-01');
+      expect(found.getId()).to.equal(created.getId());
+    });
+
+    it('returns the most recent cycle when multiple cycles exist', async () => {
+      // '2025-01' already created above; add a newer cycle
+      await Token.create({
+        siteId,
+        tokenType,
+        cycle: '2025-06',
+        total: 5,
+        used: 1,
+      });
+
+      const found = await Token.findLastCreatedBySiteIdAndTokenType(siteId, tokenType);
+
+      expect(found.getCycle()).to.equal('2025-06');
+      expect(found.getTotal()).to.equal(5);
+    });
+
+    it('throws when siteId is missing', async () => {
+      await expect(
+        Token.findLastCreatedBySiteIdAndTokenType('', tokenType),
+      ).to.be.rejectedWith(/required/);
+    });
+
+    it('throws when tokenType is missing', async () => {
+      await expect(
+        Token.findLastCreatedBySiteIdAndTokenType(siteId, ''),
+      ).to.be.rejectedWith(/required/);
+    });
+  });
+
   describe('allBySiteId', () => {
     // fixtures.sites[1].siteId — isolated from findBySiteIdAndTokenType /
     // grantSuggestions tests so seeded historical-cycle rows do not leak into

packages/spacecat-shared-data-access/test/unit/models/token/token.collection.test.js

@@ -63,6 +63,38 @@ describe('TokenCollection', () => {
     });
   });
 
+  describe('findLastCreatedBySiteIdAndTokenType', () => {
+    it('returns the last created token when found', async () => {
+      instance.findByIndexKeys = stub().resolves(model);
+
+      const result = await instance.findLastCreatedBySiteIdAndTokenType('site-1', 'grant_cwv');
+
+      expect(result).to.equal(model);
+      expect(instance.findByIndexKeys).to.have.been.calledOnceWith(
+        { siteId: 'site-1', tokenType: 'grant_cwv' },
+        { order: 'desc' },
+      );
+    });
+
+    it('returns null when no token exists', async () => {
+      instance.findByIndexKeys = stub().resolves(null);
+
+      const result = await instance.findLastCreatedBySiteIdAndTokenType('site-1', 'grant_cwv');
+
+      expect(result).to.be.null;
+    });
+
+    it('throws if siteId is missing', async () => {
+      await expect(instance.findLastCreatedBySiteIdAndTokenType(undefined, 'grant_cwv'))
+        .to.be.rejectedWith(/siteId|required/);
+    });
+
+    it('throws if tokenType is missing', async () => {
+      await expect(instance.findLastCreatedBySiteIdAndTokenType('site-1', ''))
+        .to.be.rejectedWith(/tokenType|required/);
+    });
+  });
+
   describe('findBySiteIdAndTokenType', () => {
     let expectedCycle;