@adobe/spacecat-shared-utils 1.103.0 → 1.105.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-utils-v1.105.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.104.0...@adobe/spacecat-shared-utils-v1.105.0) (2026-03-19)
+
+### Features
+
+* **spacecat-shared-utils:** SITES-40623 - add token grant config and exports ([#1420](https://github.com/adobe/spacecat-shared/issues/1420)) ([a14e001](https://github.com/adobe/spacecat-shared/commit/a14e0012f43ad4a13c4f9347bd64f66a5fc535f8))
+
+## [@adobe/spacecat-shared-utils-v1.104.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.103.0...@adobe/spacecat-shared-utils-v1.104.0) (2026-03-19)
+
+### Features
+
+* add experimentation topics field to llmo config model ([#1450](https://github.com/adobe/spacecat-shared/issues/1450)) ([ffcb886](https://github.com/adobe/spacecat-shared/commit/ffcb886e26895c5a0da02c9da9007b0eb6fe3f37))
+
 ## [@adobe/spacecat-shared-utils-v1.103.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.102.1...@adobe/spacecat-shared-utils-v1.103.0) (2026-03-18)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-utils",
-  "version": "1.103.0",
+  "version": "1.105.0",
   "description": "Shared modules of the Spacecat Services - utils",
   "type": "module",
   "exports": {

package/src/index.d.ts

@@ -371,6 +371,50 @@ export function extractUrlsFromOpportunity(opts: {
   opportunity: any;
 }): string[];
 
+/** Token grant entry: tokens per cycle and cycle format (e.g. YYYY-MM). */
+export interface TokenGrantEntry {
+  tokensPerCycle: number;
+  cycleFormat: string;
+}
+
+/** Per-opportunity grant config keyed by opportunity name. */
+export const OPPORTUNITY_GRANT_CONFIG: Record<string, TokenGrantEntry>;
+
+/** Cumulative token grant config keyed by token type. */
+export const TOKEN_GRANT_CONFIG: Record<string, TokenGrantEntry>;
+
+/**
+ * Converts an opportunity name to its token type key.
+ * @param opportunityName - e.g. "broken-backlinks".
+ * @returns e.g. "grant_broken_backlinks".
+ */
+export function getTokenTypeForOpportunity(
+  opportunityName: string
+): string;
+
+/**
+ * Returns the grant config for a token type.
+ * @param tokenType - e.g. "grant_cwv".
+ */
+export function getTokenGrantConfig(
+  tokenType: string
+): (TokenGrantEntry & { currentCycle: string }) | undefined;
+
+/**
+ * Returns the grant config for an opportunity name.
+ * @param opportunityName - e.g. "broken-backlinks".
+ */
+export function getTokenGrantConfigByOpportunity(
+  opportunityName: string
+): (TokenGrantEntry & { currentCycle: string; tokenType: string }) | undefined;
+
+/**
+ * Computes the current cycle string for a given cycleFormat
+ * using UTC time.
+ * Supported placeholders: YYYY (4-digit year), MM (zero-padded month).
+ */
+export function getCurrentCycle(cycleFormat: string): string;
+
 export * as llmoConfig from './llmo-config.js';
 export * as llmoStrategy from './llmo-strategy.js';
 export * as schemas from './schemas.js';

package/src/index.js

@@ -132,3 +132,12 @@ export {
   GRANULARITY_KEY_BUILDERS,
   ISSUE_GRANULARITY_MAP,
 } from './aggregation/aggregation-strategies.js';
+
+export {
+  TOKEN_GRANT_CONFIG,
+  OPPORTUNITY_GRANT_CONFIG,
+  getTokenGrantConfig,
+  getTokenGrantConfigByOpportunity,
+  getTokenTypeForOpportunity,
+  getCurrentCycle,
+} from './token-grant-config.js';

package/src/schemas.js

@@ -51,6 +51,7 @@ const prompt = z.object({
   origin: z.union([z.literal('human'), z.literal('ai'), z.string()]),
   source: z.union([z.literal('config'), z.literal('api'), z.string()]),
   status: z.union([z.literal('completed'), z.literal('processing'), z.string()]).optional(),
+  source_url: z.string().optional(),
   ...auditFields,
 });
 
@@ -107,6 +108,7 @@ export const llmoConfig = z.object({
   categories: z.record(z.uuid(), category),
   topics: z.record(z.uuid(), topic),
   aiTopics: z.record(z.uuid(), topic).optional(),
+  experimentationTopics: z.record(z.uuid(), topic).optional(),
   brands: z.object({
     aliases: z.array(
       z.object({

package/src/token-grant-config.js

@@ -0,0 +1,113 @@
+/*
+ * 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 './functions.js';
+
+const TOKEN_TYPE_PREFIX = 'grant_';
+
+/**
+ * Converts an opportunity name to its corresponding token type key.
+ * Replaces hyphens with underscores and prepends the grant prefix.
+ * @param {string} opportunityName - e.g. "broken-backlinks".
+ * @returns {string} e.g. "grant_broken_backlinks".
+ */
+export function getTokenTypeForOpportunity(opportunityName) {
+  return `${TOKEN_TYPE_PREFIX}${opportunityName.replace(/-/g, '_')}`;
+}
+
+/**
+ * Per-opportunity grant configuration. Keys are opportunity names
+ * (matching OPPORTUNITY_TYPES values). Token type keys are derived
+ * automatically via getTokenTypeForOpportunity().
+ */
+const OPPORTUNITY_GRANT_CONFIG = Object.freeze({
+  cwv: Object.freeze({
+    tokensPerCycle: 3,
+    cycleFormat: 'YYYY-MM',
+  }),
+  'broken-backlinks': Object.freeze({
+    tokensPerCycle: 3,
+    cycleFormat: 'YYYY-MM',
+  }),
+  'alt-text': Object.freeze({
+    tokensPerCycle: 3,
+    cycleFormat: 'YYYY-MM',
+  }),
+});
+
+export { OPPORTUNITY_GRANT_CONFIG };
+
+/**
+ * Cumulative token grant configuration keyed by token type.
+ * Includes entries generated from OPPORTUNITY_GRANT_CONFIG plus
+ * any standalone (non-opportunity) token types added below.
+ *
+ * NOTE: For limited use cases this config lives here in code.
+ * When the number of token types grows or needs to be managed
+ * dynamically, consider migrating to a dedicated database table
+ * (e.g. token_grant_configs) in mysticat-data-service.
+ */
+const TOKEN_GRANT_CONFIG = Object.freeze({
+  // Auto-generated from OPPORTUNITY_GRANT_CONFIG
+  ...Object.fromEntries(
+    Object.entries(OPPORTUNITY_GRANT_CONFIG).map(
+      ([name, cfg]) => [getTokenTypeForOpportunity(name), cfg],
+    ),
+  ),
+  // Add standalone (non-opportunity) token types here, e.g.:
+  // some_standalone_type: Object.freeze({ ... }),
+});
+
+export { TOKEN_GRANT_CONFIG };
+
+/**
+ * Computes the current cycle string for a given cycleFormat using UTC time.
+ * Supported placeholders: YYYY (4-digit year), MM (zero-padded month).
+ * @param {string} cycleFormat - e.g. "YYYY-MM".
+ * @returns {string} e.g. "2026-03".
+ */
+export function getCurrentCycle(cycleFormat) {
+  const now = new Date();
+  return cycleFormat
+    .replace('YYYY', String(now.getUTCFullYear()))
+    .replace('MM', String(now.getUTCMonth() + 1).padStart(2, '0'));
+}
+
+/**
+ * Returns the grant config for a token type, including the
+ * computed current cycle.
+ * @param {string} tokenType - e.g. "grant_cwv".
+ * @returns {{ tokensPerCycle: number,
+ *   cycleFormat: string, currentCycle: string }|undefined}
+ */
+export function getTokenGrantConfig(tokenType) {
+  if (!hasText(tokenType)) return undefined;
+  const entry = TOKEN_GRANT_CONFIG[tokenType];
+  if (!entry) return undefined;
+  return { ...entry, currentCycle: getCurrentCycle(entry.cycleFormat) };
+}
+
+/**
+ * Returns the grant config for an opportunity name, including
+ * the computed current cycle and the derived token type.
+ * @param {string} opportunityName - e.g. "broken-backlinks".
+ * @returns {{ tokensPerCycle: number, cycle: string,
+ *   cycleFormat: string, currentCycle: string,
+ *   tokenType: string }|undefined}
+ */
+export function getTokenGrantConfigByOpportunity(opportunityName) {
+  if (!hasText(opportunityName)) return undefined;
+  const tokenType = getTokenTypeForOpportunity(opportunityName);
+  const config = getTokenGrantConfig(tokenType);
+  if (!config) return undefined;
+  return { ...config, tokenType };
+}