@adobe/spacecat-shared-data-access 3.22.0 → 3.24.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@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](https://github.com/adobe/spacecat-shared/issues/1414)) ([9c540ba](https://github.com/adobe/spacecat-shared/commit/9c540babf47984e15737bde509b54df9b5233c54))
+
+## [@adobe/spacecat-shared-data-access-v3.23.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.22.0...@adobe/spacecat-shared-data-access-v3.23.0) (2026-03-18)
+
+### Features
+
+* add cited-analsys as audit types ([#1444](https://github.com/adobe/spacecat-shared/issues/1444)) ([c87bf2e](https://github.com/adobe/spacecat-shared/commit/c87bf2e0d3ad77589fa44a1f9b9638ce0deaab53))
+
 ## [@adobe/spacecat-shared-data-access-v3.22.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.21.0...@adobe/spacecat-shared-data-access-v3.22.0) (2026-03-17)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.22.0",
+  "version": "3.24.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@adobe/fetch": "^4.2.3",
-    "@adobe/spacecat-shared-utils": "1.101.0",
+    "@adobe/spacecat-shared-utils": "1.105.0",
     "@supabase/postgrest-js": "2.99.1",
     "@aws-sdk/client-s3": "^3.940.0",
     "@types/joi": "17.2.3",

package/src/models/audit/audit.model.js

@@ -86,6 +86,7 @@ class Audit extends BaseModel {
     WIKIPEDIA_ANALYSIS: 'wikipedia-analysis',
     REDDIT_ANALYSIS: 'reddit-analysis',
     YOUTUBE_ANALYSIS: 'youtube-analysis',
+    CITED_ANALYSIS: 'cited-analysis',
     COMMERCE_PRODUCT_ENRICHMENTS: 'commerce-product-enrichments',
     COMMERCE_PRODUCT_ENRICHMENTS_YEARLY: 'commerce-product-enrichments-yearly',
     COMMERCE_PRODUCT_PAGE_ENRICHMENT: 'commerce-product-page-enrichment',

package/src/models/base/entity.registry.js

@@ -38,10 +38,12 @@ import SiteEnrollmentCollection from '../site-enrollment/site-enrollment.collect
 import SiteTopFormCollection from '../site-top-form/site-top-form.collection.js';
 import SiteTopPageCollection from '../site-top-page/site-top-page.collection.js';
 import SuggestionCollection from '../suggestion/suggestion.collection.js';
+import SuggestionGrantCollection from '../suggestion-grant/suggestion-grant.collection.js';
 import PageIntentCollection from '../page-intent/page-intent.collection.js';
 import ReportCollection from '../report/report.collection.js';
 import TrialUserCollection from '../trial-user/trial-user.collection.js';
 import TrialUserActivityCollection from '../trial-user-activity/trial-user-activity.collection.js';
+import TokenCollection from '../token/token.collection.js';
 import PageCitabilityCollection from '../page-citability/page-citability.collection.js';
 import PlgOnboardingCollection from '../plg-onboarding/plg-onboarding.collection.js';
 import SentimentGuidelineCollection from '../sentiment-guideline/sentiment-guideline.collection.js';
@@ -71,10 +73,12 @@ import SiteEnrollmentSchema from '../site-enrollment/site-enrollment.schema.js';
 import SiteTopFormSchema from '../site-top-form/site-top-form.schema.js';
 import SiteTopPageSchema from '../site-top-page/site-top-page.schema.js';
 import SuggestionSchema from '../suggestion/suggestion.schema.js';
+import SuggestionGrantSchema from '../suggestion-grant/suggestion-grant.schema.js';
 import PageIntentSchema from '../page-intent/page-intent.schema.js';
 import ReportSchema from '../report/report.schema.js';
 import TrialUserSchema from '../trial-user/trial-user.schema.js';
 import TrialUserActivitySchema from '../trial-user-activity/trial-user-activity.schema.js';
+import TokenSchema from '../token/token.schema.js';
 import PageCitabilitySchema from '../page-citability/page-citability.schema.js';
 import PlgOnboardingSchema from '../plg-onboarding/plg-onboarding.schema.js';
 import SentimentGuidelineSchema from '../sentiment-guideline/sentiment-guideline.schema.js';
@@ -199,10 +203,12 @@ EntityRegistry.registerEntity(SiteEnrollmentSchema, SiteEnrollmentCollection);
 EntityRegistry.registerEntity(SiteTopFormSchema, SiteTopFormCollection);
 EntityRegistry.registerEntity(SiteTopPageSchema, SiteTopPageCollection);
 EntityRegistry.registerEntity(SuggestionSchema, SuggestionCollection);
+EntityRegistry.registerEntity(SuggestionGrantSchema, SuggestionGrantCollection);
 EntityRegistry.registerEntity(PageIntentSchema, PageIntentCollection);
 EntityRegistry.registerEntity(ReportSchema, ReportCollection);
 EntityRegistry.registerEntity(TrialUserSchema, TrialUserCollection);
 EntityRegistry.registerEntity(TrialUserActivitySchema, TrialUserActivityCollection);
+EntityRegistry.registerEntity(TokenSchema, TokenCollection);
 EntityRegistry.registerEntity(PageCitabilitySchema, PageCitabilityCollection);
 EntityRegistry.registerEntity(PlgOnboardingSchema, PlgOnboardingCollection);
 EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollection);

package/src/models/index.js

@@ -36,10 +36,12 @@ export * from './site-top-form/index.js';
 export * from './site-top-page/index.js';
 export * from './site/index.js';
 export * from './suggestion/index.js';
+export * from './suggestion-grant/index.js';
 export * from './page-intent/index.js';
 export * from './report/index.js';
 export * from './trial-user/index.js';
 export * from './trial-user-activity/index.js';
+export * from './token/index.js';
 export * from './page-citability/index.js';
 export * from './plg-onboarding/index.js';
 export * from './sentiment-guideline/index.js';

package/src/models/suggestion-grant/index.d.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type { BaseCollection, BaseModel } from '../index';
+
+export interface SuggestionGrant extends BaseModel {
+  getGrantId(): string;
+  getSuggestionId(): string;
+  getSiteId(): string;
+  getTokenId(): string;
+  getTokenType(): string;
+  getGrantedAt(): string;
+}
+
+export interface SuggestionGrantCollection extends BaseCollection<SuggestionGrant> {
+  findBySuggestionIds(suggestionIds: string[]): Promise<{ data: Array<{ suggestion_id: string; grant_id: string }>; error: object | null }>;
+  invokeGrantSuggestionsRpc(suggestionIds: string[], siteId: string, tokenType: string, cycle: string): Promise<{ data: Array | null; error: object | null }>;
+  splitSuggestionsByGrantStatus(suggestionIds: string[]): Promise<{ grantedIds: string[]; notGrantedIds: string[]; grantIds: string[] }>;
+  isSuggestionGranted(suggestionId: string): Promise<boolean>;
+  grantSuggestions(suggestionIds: string[], siteId: string, tokenType: string): Promise<{ success: boolean; reason?: string; grantedSuggestions?: Array }>;
+}

package/src/models/suggestion-grant/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import SuggestionGrant from './suggestion-grant.model.js';
+import SuggestionGrantCollection from './suggestion-grant.collection.js';
+
+export {
+  SuggestionGrant,
+  SuggestionGrantCollection,
+};

package/src/models/suggestion-grant/suggestion-grant.collection.js

@@ -0,0 +1,177 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+
+import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
+
+/**
+ * SuggestionGrantCollection - Manages SuggestionGrant records (suggestion_grants table).
+ * Table is insert-only; inserts happen via grant_suggestions RPC. This collection
+ * provides read-only lookup by suggestion IDs.
+ *
+ * @class SuggestionGrantCollection
+ * @extends BaseCollection
+ */
+class SuggestionGrantCollection extends BaseCollection {
+  static COLLECTION_NAME = 'SuggestionGrantCollection';
+
+  /**
+   * Finds all grant rows for the given suggestion IDs (suggestion_id, grant_id only).
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to look up.
+   * @returns {Promise<Array<{suggestion_id: string, grant_id: string}>>}
+   * @throws {DataAccessError} - On query failure.
+   */
+  async findBySuggestionIds(suggestionIds) {
+    if (!Array.isArray(suggestionIds) || suggestionIds.length === 0) {
+      return [];
+    }
+    const { data, error } = await this.postgrestService
+      .from(this.tableName)
+      .select('suggestion_id,grant_id')
+      .in('suggestion_id', suggestionIds);
+
+    if (error) {
+      throw new DataAccessError('Failed to find grants by suggestion IDs', this, error);
+    }
+
+    return data ?? [];
+  }
+
+  /**
+   * Invokes the grant_suggestions RPC. Inserts suggestion_grants rows and consumes one token.
+   * RPC name and parameter shape live in this collection (suggestion_grants).
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to grant.
+   * @param {string} siteId - Site ID.
+   * @param {string} tokenType - Token type.
+   * @param {string} cycle - Token cycle (e.g. '2025-01').
+   * @returns {Promise<{ data: Array|null, error: object|null }>}
+   */
+  async invokeGrantSuggestionsRpc(suggestionIds, siteId, tokenType, cycle) {
+    return this.postgrestService.rpc('grant_suggestions', {
+      p_suggestion_ids: suggestionIds,
+      p_site_id: siteId,
+      p_token_type: tokenType,
+      p_cycle: cycle,
+    });
+  }
+
+  /**
+   * Splits suggestion IDs into those that are granted and those that are not.
+   * A suggestion is considered granted if it has at least one row in suggestion_grants.
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to check.
+   * @returns {Promise<{ grantedIds: string[], notGrantedIds: string[], grantIds: string[] }>}
+   * @throws {DataAccessError} - On invalid input or query failure.
+   */
+  async splitSuggestionsByGrantStatus(suggestionIds) {
+    if (!Array.isArray(suggestionIds)) {
+      throw new DataAccessError('splitSuggestionsByGrantStatus: suggestionIds must be an array', this);
+    }
+
+    const deduped = [...new Set(suggestionIds.filter((id) => hasText(id)))];
+
+    if (deduped.length === 0) {
+      return { grantedIds: [], notGrantedIds: [], grantIds: [] };
+    }
+
+    try {
+      const rows = await this.findBySuggestionIds(deduped);
+      const grantedIdSet = new Set(rows.map((r) => r.suggestion_id));
+      const grantedIds = deduped.filter((id) => grantedIdSet.has(id));
+      const notGrantedIds = deduped.filter((id) => !grantedIdSet.has(id));
+      const grantIds = [...new Set(rows.map((r) => r.grant_id).filter(Boolean))];
+
+      return { grantedIds, notGrantedIds, grantIds };
+    } catch (err) {
+      if (err instanceof DataAccessError) throw err;
+      this.log.error('splitSuggestionsByGrantStatus failed', err);
+      throw new DataAccessError('Failed to split suggestions by grant status', this, err);
+    }
+  }
+
+  /**
+   * Returns whether a single suggestion is granted (has at least one row in suggestion_grants).
+   *
+   * @async
+   * @param {string} suggestionId - Suggestion ID to check.
+   * @returns {Promise<boolean>} True if the suggestion is granted,
+   *   false otherwise or if id is empty.
+   */
+  async isSuggestionGranted(suggestionId) {
+    if (!hasText(suggestionId)) return false;
+    const { grantedIds } = await this.splitSuggestionsByGrantStatus([suggestionId]);
+    return grantedIds.length > 0;
+  }
+
+  /**
+   * Grants one or more suggestions by consuming a single token for the given token type.
+   * Resolves the current cycle token via TokenCollection#findBySiteIdAndTokenType
+   * (which auto-creates if missing), checks that at least one token remains, then calls the
+   * grant_suggestions RPC to atomically consume one token and insert suggestion grants for
+   * the entire list of IDs.
+   *
+   * @async
+   * @param {string[]} suggestionIds - Suggestion IDs to grant (one token consumed for the list).
+   * @param {string} siteId - The site ID that owns the token allocation.
+   * @param {string} tokenType - Token type (e.g. 'grant_cwv').
+   * @returns {Promise<{ success: boolean, reason?: string, grantedSuggestions?: Array }>}
+   * @throws {DataAccessError} - On missing inputs or RPC failure.
+   */
+  async grantSuggestions(suggestionIds, siteId, tokenType) {
+    if (!Array.isArray(suggestionIds) || suggestionIds.some((id) => !hasText(id))) {
+      throw new DataAccessError('grantSuggestions: suggestionIds must be an array of non-empty strings', this);
+    }
+    if (!hasText(siteId)) {
+      throw new DataAccessError('grantSuggestions: siteId is required', this);
+    }
+    if (!hasText(tokenType)) {
+      throw new DataAccessError('grantSuggestions: tokenType is required', this);
+    }
+
+    const tokenCollection = this.entityRegistry.getCollection('TokenCollection');
+    const token = await tokenCollection.findBySiteIdAndTokenType(siteId, tokenType);
+
+    if (!token || token.getRemaining() < 1) {
+      return { success: false, reason: 'no_tokens' };
+    }
+
+    const cycle = token.getCycle();
+    const rpcResult = await this.invokeGrantSuggestionsRpc(
+      suggestionIds,
+      siteId,
+      tokenType,
+      cycle,
+    );
+    const { data, error } = rpcResult;
+
+    if (error) {
+      this.log.error('grantSuggestions: RPC failed', error);
+      throw new DataAccessError('Failed to grant suggestions (grant_suggestions)', this, error);
+    }
+
+    const row = Array.isArray(data) && data.length > 0 ? data[0] : null;
+    if (!row || !row.success) {
+      return { success: false, reason: row?.reason || 'rpc_no_result' };
+    }
+
+    return { success: true, grantedSuggestions: row.granted_suggestions };
+  }
+}
+
+export default SuggestionGrantCollection;

package/src/models/suggestion-grant/suggestion-grant.model.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * SuggestionGrant - Record that a suggestion was granted (has a row in suggestion_grants).
+ * Table is insert-only; rows are created via grant_suggestions RPC.
+ *
+ * @class SuggestionGrant
+ * @extends BaseModel
+ */
+class SuggestionGrant extends BaseModel {
+  static ENTITY_NAME = 'SuggestionGrant';
+}
+
+export default SuggestionGrant;

package/src/models/suggestion-grant/suggestion-grant.schema.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isValidUUID } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import SuggestionGrant from './suggestion-grant.model.js';
+import SuggestionGrantCollection from './suggestion-grant.collection.js';
+
+/*
+ * SuggestionGrant: suggestion_grants table (insert-only via grant_suggestions RPC).
+ * Columns: id, grant_id, suggestion_id, site_id, token_id, token_type, created_at, granted_at.
+ * Table has no updated_at/updated_by; those defaults are ignored for PostgREST.
+ */
+
+const schema = new SchemaBuilder(SuggestionGrant, SuggestionGrantCollection)
+  .addAttribute('updatedAt', {
+    type: 'string', required: true, readOnly: true, postgrestIgnore: true,
+  })
+  .addAttribute('updatedBy', {
+    type: 'string', required: false, postgrestIgnore: true,
+  })
+  .addIndex({ composite: ['suggestionId'] }, { composite: [] })
+  .addAttribute('suggestionId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'suggestion_id',
+  })
+  .addAttribute('grantId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'grant_id',
+  })
+  .addAttribute('siteId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'site_id',
+  })
+  .addAttribute('tokenId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'token_id',
+  })
+  .addAttribute('tokenType', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    postgrestField: 'token_type',
+  })
+  .addAttribute('grantedAt', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    postgrestField: 'granted_at',
+  });
+
+export default schema.build();

package/src/models/token/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import Token from './token.model.js';
+import TokenCollection from './token.collection.js';
+
+export {
+  Token,
+  TokenCollection,
+};

package/src/models/token/token.collection.js

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { hasText, getTokenGrantConfig } from '@adobe/spacecat-shared-utils';
+
+import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
+
+/**
+ * TokenCollection - Manages Token entities (per-site, per-tokenType, per-cycle).
+ * Uses PostgREST table `tokens`.
+ *
+ * @class TokenCollection
+ * @extends BaseCollection
+ */
+class TokenCollection extends BaseCollection {
+  static COLLECTION_NAME = 'TokenCollection';
+
+  /**
+   * Finds a Token for the current cycle by siteId and tokenType. The cycle is
+   * derived from the token-grant-config's cycleFormat. If no token exists for
+   * the current cycle and options.createIfNotFound is true, creates one. The
+   * token total is the minimum of options.total (if supplied) and the config
+   * tokensPerCycle, clamped to at least 1.
+   *
+   * @param {string} siteId - Site ID (UUID).
+   * @param {string} tokenType - Token type (e.g. grant_cwv,
+   *   grant_broken_backlinks).
+   * @param {Object} [options={}] - Options.
+   * @param {boolean} [options.createIfNotFound=false] - If true, create a token when none exists.
+   * @param {number} [options.total] - Optional supplied total;
+   *   actual total is min(options.total, config.tokensPerCycle), at least 1.
+   * @returns {Promise<import('./token.model.js').default|null>} Token instance
+   *   (existing or newly created), or null when none exists and createIfNotFound is false.
+   */
+  async findBySiteIdAndTokenType(siteId, tokenType, options = {}) {
+    if (!hasText(siteId) || !hasText(tokenType)) {
+      throw new DataAccessError('TokenCollection.findBySiteIdAndTokenType: siteId and tokenType are required');
+    }
+    const config = getTokenGrantConfig(tokenType);
+    if (!config) {
+      throw new DataAccessError(`TokenCollection.findBySiteIdAndTokenType: no token grant config for tokenType: ${tokenType}`);
+    }
+    const { currentCycle: cycle } = config;
+    const existing = await this.findByIndexKeys({ siteId, tokenType, cycle }, { limit: 1 });
+    if (existing || options.createIfNotFound !== true) {
+      return existing || null;
+    }
+    const total = options.total != null
+      ? Math.max(1, Math.min(Number(options.total), config.tokensPerCycle))
+      : config.tokensPerCycle;
+    return this.create({
+      siteId,
+      tokenType,
+      cycle,
+      total,
+      used: 0,
+    });
+  }
+}
+
+export default TokenCollection;

package/src/models/token/token.model.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * Token - Tracks token allocation and consumption per site, token type (opportunity type),
+ * and cycle. Used to enforce per-opportunity monthly (or cycle) limits for granted suggestions.
+ *
+ * @class Token
+ * @extends BaseModel
+ */
+class Token extends BaseModel {
+  static ENTITY_NAME = 'Token';
+
+  /**
+   * Returns the number of tokens remaining in this cycle (total - used).
+   * @returns {number}
+   */
+  getRemaining() {
+    const total = this.getTotal();
+    const used = this.getUsed();
+    return Math.max(0, total - used);
+  }
+}
+
+export default Token;

package/src/models/token/token.schema.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isValidUUID } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import Token from './token.model.js';
+import TokenCollection from './token.collection.js';
+
+/*
+ * Token entity: per-site, per-tokenType (opportunity type), per-cycle token allocation.
+ * Postgres table: tokens with primary key id, unique (site_id, token_type, cycle).
+ * Data access: findBySiteIdAndTokenType(siteId, tokenType).
+ * Consume: one token per grant_suggestions call (whole list of IDs)
+ * via SuggestionGrantCollection.grantSuggestions().
+ */
+
+const schema = new SchemaBuilder(Token, TokenCollection)
+  .addIndex({ composite: ['siteId', 'tokenType'] }, { composite: ['cycle'] })
+  .addAttribute('siteId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUUID(value),
+    postgrestField: 'site_id',
+  })
+  .addAttribute('tokenType', {
+    type: 'string',
+    required: true,
+    postgrestField: 'token_type',
+  })
+  .addAttribute('cycle', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('total', {
+    type: 'number',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('used', {
+    type: 'number',
+    required: true,
+    default: 0,
+  });
+
+export default schema.build();

package/src/util/postgrest.utils.js

@@ -16,6 +16,7 @@ const DEFAULT_PAGE_SIZE = 1000;
 
 const ENTITY_TABLE_OVERRIDES = {
   LatestAudit: 'audits',
+  SuggestionGrant: 'suggestion_grants',
 };
 
 const camelToSnake = (value) => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();