@adobe/spacecat-shared-utils 1.106.1 → 1.107.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@adobe/spacecat-shared-utils-v1.107.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.106.1...@adobe/spacecat-shared-utils-v1.107.0) (2026-03-30)
+
+### Features
+
+* add onboard config and opportunity maps ([#1464](https://github.com/adobe/spacecat-shared/issues/1464)) ([9bd59f5](https://github.com/adobe/spacecat-shared/commit/9bd59f5e2b05f3fd29ea7568daf0e369bd4d2535))
+
 ## [@adobe/spacecat-shared-utils-v1.106.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.106.0...@adobe/spacecat-shared-utils-v1.106.1) (2026-03-28)
 
 ### Bug Fixes

package/package.json

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

package/src/index.js

@@ -141,3 +141,25 @@ export {
   getTokenTypeForOpportunity,
   getCurrentCycle,
 } from './token-grant-config.js';
+
+export {
+  AUDIT_OPPORTUNITY_MAP,
+  getOpportunitiesForAudit,
+  getAuditsForOpportunity,
+  getAllOpportunityTypes,
+  getAllAuditTypes,
+} from './opportunity/audit-mapping.js';
+
+export {
+  DEPENDENCY_SOURCES,
+  OPPORTUNITY_DEPENDENCY_MAP,
+  getDependenciesForOpportunity,
+  getOpportunitiesForSource,
+} from './opportunity/dependency-mapping.js';
+
+export {
+  OPPORTUNITY_TITLES,
+  getOpportunityTitle,
+} from './opportunity/opportunity-titles.js';
+
+export { computeAuditCompletion } from './opportunity/audit-completion.js';

package/src/opportunity/audit-completion.js

@@ -0,0 +1,65 @@
+/*
+ * 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.
+ */
+
+/**
+ * Computes which audit types are pending vs completed from already-fetched audit records.
+ *
+ * The onboardStartTime anchor is the same value written to onboardConfig.lastStartTime
+ * in the site config by the api-service and passed via SQS/step function message to the
+ * task-processor. Callers supply it from whichever source is available to them.
+ *
+ * An audit is pending if:
+ *   - No DB record exists for it yet, OR
+ *   - Its auditedAt timestamp predates or ties with onboardStartTime (<=).
+ *     An exact match indicates an in-flight audit captured before the run completed.
+ *
+ * If onboardStartTime is absent (site onboarded before this feature), any existing
+ * record is treated as completed — only a missing record counts as pending.
+ *
+ * Pure function — no DB calls.
+ *
+ * @param {string[]} auditTypes - Audit types to check
+ * @param {number|undefined} onboardStartTime - Onboard start timestamp in ms
+ * @param {Array} latestAudits - Already-fetched audit records (getAuditType, getAuditedAt)
+ * @returns {{ pendingAuditTypes: string[], completedAuditTypes: string[] }}
+ */
+export function computeAuditCompletion(auditTypes, onboardStartTime, latestAudits) {
+  const pendingAuditTypes = [];
+  const completedAuditTypes = [];
+  const auditsByType = {};
+
+  if (latestAudits) {
+    for (const audit of latestAudits) {
+      auditsByType[audit.getAuditType()] = audit;
+    }
+  }
+
+  for (const auditType of auditTypes) {
+    const audit = auditsByType[auditType];
+    if (!audit) {
+      pendingAuditTypes.push(auditType);
+    } else if (onboardStartTime) {
+      const auditedAt = new Date(audit.getAuditedAt()).getTime();
+      // NaN or timestamp predating/matching trigger → pending
+      if (Number.isNaN(auditedAt) || auditedAt <= onboardStartTime) {
+        pendingAuditTypes.push(auditType);
+      } else {
+        completedAuditTypes.push(auditType);
+      }
+    } else {
+      // No onboard start time — treat existing record as completed.
+      completedAuditTypes.push(auditType);
+    }
+  }
+
+  return { pendingAuditTypes, completedAuditTypes };
+}

package/src/opportunity/audit-mapping.js

@@ -0,0 +1,120 @@
+/*
+ * 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.
+ */
+
+/**
+ * Maps each audit type to the opportunity types it can generate.
+ * Derived from the HANDLERS registry in spacecat-audit-worker/src/index.js.
+ *
+ * Audits that are data-collection only (e.g. apex, paid, lhs-mobile, cdn-logs-*)
+ * and produce no opportunities are intentionally omitted.
+ *
+ * Key:   audit type string
+ * Value: array of opportunity type strings produced by that audit
+ */
+export const AUDIT_OPPORTUNITY_MAP = {
+  // Core SEO
+  'broken-backlinks': ['broken-backlinks'],
+  'broken-internal-links': ['broken-internal-links'],
+  canonical: ['canonical'],
+  hreflang: ['hreflang'],
+  'meta-tags': ['meta-tags'],
+  sitemap: ['sitemap'],
+  'sitemap-product-coverage': ['sitemap-product-coverage'],
+  'structured-data': ['structured-data'],
+  'redirect-chains': ['redirect-chains'],
+
+  // Performance
+  cwv: ['cwv'],
+  prerender: ['prerender'],
+
+  // Accessibility & content
+  accessibility: ['accessibility'],
+  'alt-text': ['alt-text'],
+  headings: ['headings'],
+  'no-cta-above-the-fold': ['no-cta-above-the-fold'],
+  readability: ['readability'],
+
+  // Forms — one audit, multiple opportunity types
+  'forms-opportunities': [
+    'high-form-views-low-conversions',
+    'high-page-views-low-form-nav',
+    'high-page-views-low-form-views',
+    'form-accessibility',
+  ],
+
+  // Experimentation
+  'experimentation-opportunities': ['high-organic-low-ctr'],
+
+  // Commerce
+  'product-metatags': ['product-metatags'],
+
+  // Security
+  'security-csp': ['security-csp'],
+  'security-vulnerabilities': ['security-vulnerabilities'],
+  'security-permissions': ['security-permissions'],
+  'security-permissions-redundant': ['security-permissions-redundant'],
+
+  // LLMO / content quality
+  'llm-blocked': ['llm-blocked'],
+  'llm-error-pages': ['llm-error-pages'],
+  faqs: ['faqs'],
+  'related-urls': ['related-urls'],
+  toc: ['toc'],
+
+  // Experimentation (ESS signals)
+  'experimentation-ess-daily': ['experimentation-ess-daily'],
+  'experimentation-ess-monthly': ['experimentation-ess-monthly'],
+
+  // Offsite / brand analysis
+  'cited-analysis': ['cited-analysis'],
+  'wikipedia-analysis': ['wikipedia-analysis'],
+  'reddit-analysis': ['reddit-analysis'],
+  'youtube-analysis': ['youtube-analysis'],
+};
+
+// ─── Query helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Returns all opportunity types that a given audit type can generate.
+ * @param {string} auditType
+ * @returns {string[]}
+ */
+export function getOpportunitiesForAudit(auditType) {
+  return AUDIT_OPPORTUNITY_MAP[auditType] || [];
+}
+
+/**
+ * Returns all audit types that produce a given opportunity type.
+ * @param {string} opportunityType
+ * @returns {string[]}
+ */
+export function getAuditsForOpportunity(opportunityType) {
+  return Object.entries(AUDIT_OPPORTUNITY_MAP)
+    .filter(([, opps]) => opps.includes(opportunityType))
+    .map(([auditType]) => auditType);
+}
+
+/**
+ * Returns all unique opportunity types across all audits.
+ * @returns {string[]}
+ */
+export function getAllOpportunityTypes() {
+  return [...new Set(Object.values(AUDIT_OPPORTUNITY_MAP).flat())];
+}
+
+/**
+ * Returns all audit types defined in the map.
+ * @returns {string[]}
+ */
+export function getAllAuditTypes() {
+  return Object.keys(AUDIT_OPPORTUNITY_MAP);
+}

package/src/opportunity/dependency-mapping.js

@@ -0,0 +1,122 @@
+/*
+ * 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.
+ */
+
+/**
+ * Dependency sources used by opportunities.
+ * RUM          — Real User Monitoring (Adobe RUM / helix-rum-js)
+ * AHREFSImport — Ahrefs import job (organic traffic, backlinks, keywords)
+ * GSC          — Google Search Console import
+ * scraping     — Page HTML scraping (spacecat-scraper / spacecat-content-scraper)
+ * ExternalAPI  — Third-party API call at audit run-time (Wikipedia, Reddit, YouTube)
+ * CrUX         — Chrome User Experience Report (field data from Google)
+ * PSI          — PageSpeed Insights (lab data via Lighthouse API)
+ */
+export const DEPENDENCY_SOURCES = /** @type {const} */ ({
+  RUM: 'RUM',
+  AHREFS_IMPORT: 'AHREFSImport',
+  GSC: 'GSC',
+  SCRAPING: 'scraping',
+  EXTERNAL_API: 'ExternalAPI',
+  CRUX: 'CrUX',
+  PSI: 'PSI',
+});
+
+/**
+ * Maps each opportunity type to the data sources it requires to be populated.
+ * A missing or empty import for any listed source means the opportunity
+ * cannot be generated or will have incomplete data.
+ *
+ * Key:   opportunity type string
+ * Value: array of DEPENDENCY_SOURCES values
+ */
+export const OPPORTUNITY_DEPENDENCY_MAP = {
+  // Performance
+  cwv: [DEPENDENCY_SOURCES.RUM, DEPENDENCY_SOURCES.CRUX, DEPENDENCY_SOURCES.PSI],
+  prerender: [DEPENDENCY_SOURCES.SCRAPING],
+
+  // SEO — traffic-driven
+  'high-organic-low-ctr': [DEPENDENCY_SOURCES.RUM, DEPENDENCY_SOURCES.GSC],
+
+  // SEO — link audits
+  'broken-backlinks': [DEPENDENCY_SOURCES.AHREFS_IMPORT, DEPENDENCY_SOURCES.SCRAPING],
+  'broken-internal-links': [DEPENDENCY_SOURCES.RUM, DEPENDENCY_SOURCES.SCRAPING],
+
+  // SEO — on-page / content
+  canonical: [DEPENDENCY_SOURCES.SCRAPING],
+  hreflang: [DEPENDENCY_SOURCES.SCRAPING],
+  'meta-tags': [DEPENDENCY_SOURCES.AHREFS_IMPORT, DEPENDENCY_SOURCES.SCRAPING],
+  sitemap: [DEPENDENCY_SOURCES.SCRAPING],
+  'sitemap-product-coverage': [DEPENDENCY_SOURCES.AHREFS_IMPORT, DEPENDENCY_SOURCES.SCRAPING],
+  'structured-data': [DEPENDENCY_SOURCES.SCRAPING],
+  'redirect-chains': [DEPENDENCY_SOURCES.SCRAPING],
+  headings: [DEPENDENCY_SOURCES.SCRAPING],
+
+  // Accessibility & content
+  accessibility: [DEPENDENCY_SOURCES.SCRAPING],
+  'alt-text': [DEPENDENCY_SOURCES.AHREFS_IMPORT, DEPENDENCY_SOURCES.SCRAPING],
+  'no-cta-above-the-fold': [DEPENDENCY_SOURCES.RUM, DEPENDENCY_SOURCES.SCRAPING],
+  readability: [DEPENDENCY_SOURCES.SCRAPING],
+
+  // Forms
+  'high-form-views-low-conversions': [DEPENDENCY_SOURCES.RUM],
+  'high-page-views-low-form-nav': [DEPENDENCY_SOURCES.RUM],
+  'high-page-views-low-form-views': [DEPENDENCY_SOURCES.RUM],
+  'form-accessibility': [DEPENDENCY_SOURCES.RUM, DEPENDENCY_SOURCES.SCRAPING],
+
+  // Commerce
+  'product-metatags': [DEPENDENCY_SOURCES.SCRAPING],
+
+  // Security
+  'security-csp': [DEPENDENCY_SOURCES.SCRAPING],
+  'security-vulnerabilities': [DEPENDENCY_SOURCES.SCRAPING],
+  'security-permissions': [DEPENDENCY_SOURCES.SCRAPING],
+  'security-permissions-redundant': [DEPENDENCY_SOURCES.SCRAPING],
+
+  // LLMO / content quality
+  'llm-blocked': [DEPENDENCY_SOURCES.SCRAPING],
+  'llm-error-pages': [DEPENDENCY_SOURCES.SCRAPING],
+  faqs: [DEPENDENCY_SOURCES.SCRAPING],
+  'related-urls': [DEPENDENCY_SOURCES.AHREFS_IMPORT],
+  toc: [DEPENDENCY_SOURCES.SCRAPING],
+
+  // Experimentation (ESS signals — organic traffic + RUM)
+  'experimentation-ess-daily': [DEPENDENCY_SOURCES.RUM, DEPENDENCY_SOURCES.GSC],
+  'experimentation-ess-monthly': [DEPENDENCY_SOURCES.RUM, DEPENDENCY_SOURCES.GSC],
+
+  // Offsite / brand analysis
+  'cited-analysis': [DEPENDENCY_SOURCES.EXTERNAL_API],
+  'wikipedia-analysis': [DEPENDENCY_SOURCES.EXTERNAL_API],
+  'reddit-analysis': [DEPENDENCY_SOURCES.EXTERNAL_API],
+  'youtube-analysis': [DEPENDENCY_SOURCES.EXTERNAL_API],
+};
+
+// ─── Query helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Returns the required data sources for a given opportunity type.
+ * @param {string} opportunityType
+ * @returns {string[]}
+ */
+export function getDependenciesForOpportunity(opportunityType) {
+  return OPPORTUNITY_DEPENDENCY_MAP[opportunityType] || [];
+}
+
+/**
+ * Returns all opportunity types that depend on a given data source.
+ * @param {string} source - One of DEPENDENCY_SOURCES values
+ * @returns {string[]}
+ */
+export function getOpportunitiesForSource(source) {
+  return Object.entries(OPPORTUNITY_DEPENDENCY_MAP)
+    .filter(([, deps]) => deps.includes(source))
+    .map(([opportunityType]) => opportunityType);
+}

package/src/opportunity/opportunity-titles.js

@@ -0,0 +1,90 @@
+/*
+ * 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.
+ */
+
+/**
+ * Human-readable display titles for each opportunity type.
+ *
+ * Key:   opportunity type string
+ * Value: display title string
+ */
+export const OPPORTUNITY_TITLES = {
+  // Performance
+  cwv: 'Core Web Vitals',
+  prerender: 'Prerender',
+
+  // Core SEO
+  'broken-backlinks': 'Broken Backlinks',
+  'broken-internal-links': 'Broken Internal Links',
+  canonical: 'Canonical',
+  hreflang: 'Hreflang',
+  'meta-tags': 'SEO Meta Tags',
+  sitemap: 'Sitemap',
+  'sitemap-product-coverage': 'Sitemap Product Coverage',
+  'structured-data': 'Structured Data',
+  'redirect-chains': 'Redirect Chains',
+
+  // Accessibility & content
+  accessibility: 'Accessibility',
+  'alt-text': 'Alt Text',
+  headings: 'Headings',
+  'no-cta-above-the-fold': 'No CTA Above the Fold',
+  readability: 'Readability',
+
+  // Forms
+  'high-form-views-low-conversions': 'High Form Views Low Conversions',
+  'high-page-views-low-form-nav': 'High Page Views Low Form Navigation',
+  'high-page-views-low-form-views': 'High Page Views Low Form Views',
+  'form-accessibility': 'Form Accessibility',
+
+  // Experimentation
+  'high-organic-low-ctr': 'High Organic Low CTR',
+
+  // Commerce
+  'product-metatags': 'Product Meta Tags',
+
+  // Security
+  'security-csp': 'Security CSP',
+  'security-vulnerabilities': 'Security Vulnerabilities',
+  'security-permissions': 'Security Permissions',
+  'security-permissions-redundant': 'Security Permissions Redundant',
+
+  // LLMO / content quality
+  'llm-blocked': 'LLM Blocked',
+  'llm-error-pages': 'LLM Error Pages',
+  faqs: 'FAQs',
+  'related-urls': 'Related URLs',
+  toc: 'Table of Contents',
+
+  // Experimentation (ESS signals)
+  'experimentation-ess-daily': 'Experimentation ESS Daily',
+  'experimentation-ess-monthly': 'Experimentation ESS Monthly',
+
+  // Offsite / brand analysis
+  'cited-analysis': 'Cited Analysis',
+  'wikipedia-analysis': 'Wikipedia Analysis',
+  'reddit-analysis': 'Reddit Analysis',
+  'youtube-analysis': 'YouTube Analysis',
+};
+
+/**
+ * Returns the human-readable title for a given opportunity type.
+ * Falls back to converting kebab-case to Title Case for unknown types.
+ * @param {string} opportunityType
+ * @returns {string}
+ */
+export function getOpportunityTitle(opportunityType) {
+  return OPPORTUNITY_TITLES[opportunityType]
+    ?? opportunityType
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+}