@adobe/spacecat-shared-data-access 3.23.0 → 3.25.0

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();