@adobe/spacecat-shared-utils 1.110.0 → 1.112.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-utils-v1.112.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.111.0...@adobe/spacecat-shared-utils-v1.112.0) (2026-04-02)
+
+### Features
+
+* **spacecat-shared-utils:** add sub-path exports for slim imports ([#1486](https://github.com/adobe/spacecat-shared/issues/1486)) ([4e15c66](https://github.com/adobe/spacecat-shared/commit/4e15c6631f5f660283178d61891bf4773a6b564f))
+
+## [@adobe/spacecat-shared-utils-v1.111.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.110.0...@adobe/spacecat-shared-utils-v1.111.0) (2026-04-01)
+
+### Features
+
+* LLMO-3758 info-gain ([#1488](https://github.com/adobe/spacecat-shared/issues/1488)) ([cc6bcc1](https://github.com/adobe/spacecat-shared/commit/cc6bcc16921e98f46b79efdff272004672fb455e))
+
 ## [@adobe/spacecat-shared-utils-v1.110.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.109.0...@adobe/spacecat-shared-utils-v1.110.0) (2026-04-01)
 
 ### Features

package/README.md

@@ -121,6 +121,28 @@ This library includes a comprehensive test suite to ensure the reliability of th
 npm test
 ```
 
+## Sub-path Exports
+
+To avoid pulling in the full dependency tree (~110MB), import from a sub-path:
+
+| Import | Dependencies |
+|--------|-------------|
+| `@adobe/spacecat-shared-utils` | All (~110MB) |
+| `@adobe/spacecat-shared-utils/core` | None — pure JS only |
+| `@adobe/spacecat-shared-utils/aws` | `@aws-sdk/*`, `aws-xray-sdk`, `@adobe/fetch` ⚠ **Side effect:** initializes HTTP connection pool at import time — requires outbound internet access |
+| `@adobe/spacecat-shared-utils/locale` | `cheerio`, `world-countries`, `franc-min`, `iso-639-3`, `@adobe/fetch` ⚠ **Side effect:** initializes HTTP connection pool at import time — requires outbound internet access |
+| `@adobe/spacecat-shared-utils/calendar` | `date-fns` |
+| `@adobe/spacecat-shared-utils/schemas` | `zod` |
+| `@adobe/spacecat-shared-utils/constants` | None — pure data |
+
+### TypeScript
+
+Sub-path exports require `"moduleResolution": "node16"`, `"nodenext"`, or `"bundler"` in `tsconfig.json`. Legacy `"moduleResolution": "node"` does not resolve sub-path exports.
+
+### Maintenance
+
+Any new `src/` file that contains top-level imperative code (anything beyond `import`/`export` statements) must be added to the `sideEffects` array in `package.json`.
+
 ## License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE.txt) file for details.

package/package.json

@@ -1,14 +1,43 @@
 {
   "name": "@adobe/spacecat-shared-utils",
-  "version": "1.110.0",
+  "version": "1.112.0",
   "description": "Shared modules of the Spacecat Services - utils",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "browser": "./src/browser.js",
       "default": "./src/index.js"
+    },
+    "./core": {
+      "types": "./src/core.d.ts",
+      "default": "./src/core.js"
+    },
+    "./aws": {
+      "types": "./src/aws.d.ts",
+      "default": "./src/aws.js"
+    },
+    "./locale": {
+      "types": "./src/locale.d.ts",
+      "default": "./src/locale.js"
+    },
+    "./calendar": {
+      "types": "./src/calendar.d.ts",
+      "default": "./src/calendar.js"
+    },
+    "./schemas": {
+      "types": "./src/schemas.d.ts",
+      "default": "./src/schemas.js"
+    },
+    "./constants": {
+      "types": "./src/constants.d.ts",
+      "default": "./src/constants.js"
     }
   },
+  "sideEffects": [
+    "./src/adobe-fetch.js",
+    "./src/url-helpers.js"
+  ],
   "engines": {
     "node": ">=22.0.0 <25.0.0",
     "npm": ">=10.9.0 <12.0.0"
@@ -16,6 +45,7 @@
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "scripts": {
+    "pretest": "node scripts/check-subpath-deps.js",
     "test": "c8 mocha",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
@@ -43,6 +73,7 @@
   "devDependencies": {
     "@adobe/helix-shared-wrap": "2.0.2",
     "@types/validator": "^13.15.2",
+    "esbuild": "0.27.4",
     "chai": "6.2.2",
     "chai-as-promised": "8.0.2",
     "esmock": "2.7.3",

package/src/aws.d.ts

@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+
+export {
+  s3Wrapper, getObjectFromKey,
+  sqsWrapper, sqsEventAdapter,
+  instrumentAWSClient, getTraceId, addTraceIdHeader,
+  logWrapper, isAWSLambda,
+  fetch, resetFetchContext, clearFetchCache,
+  tracingFetch, SPACECAT_USER_AGENT,
+  getStoredMetrics, storeMetrics, calculateCPCValue,
+} from './index.js';

package/src/aws.js

@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+
+/**
+ * @sideeffect Importing this module initializes the @adobe/fetch HTTP connection pool
+ * (h1() or h2() based on HELIX_FETCH_FORCE_HTTP1) at module load time via adobe-fetch.js,
+ * before any fetch() call is made. In a VPC Lambda with restricted egress or no NAT gateway,
+ * this can cause a silent hang at import time. Ensure your Lambda has outbound internet
+ * access before importing this module.
+ */
+export { s3Wrapper, getObjectFromKey } from './s3.js';
+export { sqsWrapper, sqsEventAdapter } from './sqs.js';
+export { instrumentAWSClient, getTraceId, addTraceIdHeader } from './xray.js';
+export { logWrapper } from './log-wrapper.js';
+export { isAWSLambda } from './runtimes.js';
+export { fetch, resetFetchContext, clearFetchCache } from './adobe-fetch.js';
+export { tracingFetch, SPACECAT_USER_AGENT } from './tracing-fetch.js';
+export { getStoredMetrics, storeMetrics, calculateCPCValue } from './metrics-store.js';

package/src/calendar.d.ts

@@ -0,0 +1,17 @@
+/*
+ * 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.
+ */
+
+export {
+  getDateRanges, getLastNumberOfWeeks, getWeekInfo,
+  getMonthInfo, getTemporalCondition,
+  isoCalendarWeek, isoCalendarWeekSunday, isoCalendarWeekMonday,
+} from './index.js';

package/src/calendar.js

@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+
+export {
+  getDateRanges,
+  getLastNumberOfWeeks,
+  getWeekInfo,
+  getMonthInfo,
+  getTemporalCondition,
+  isoCalendarWeek,
+  isoCalendarWeekSunday,
+  isoCalendarWeekMonday,
+} from './calendar-week-helper.js';

package/src/constants.d.ts

@@ -0,0 +1,13 @@
+/*
+ * 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.
+ */
+
+export { OPPORTUNITY_TYPES, DEFAULT_CPC_VALUE } from './index.js';

package/src/constants.js

@@ -70,6 +70,7 @@ export const OPPORTUNITY_TYPES = /** @type {const} */ ({
   REDDIT_ANALYSIS: 'reddit-analysis',
   WIKIPEDIA_ANALYSIS: 'wikipedia-analysis',
   YOUTUBE_ANALYSIS: 'youtube-analysis',
+  INFO_GAIN: 'info-gain',
 });
 
 export const DEFAULT_CPC_VALUE = 1.5;

package/src/core.d.ts

@@ -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.
+ */
+
+export {
+  arrayEquals, dateAfterDays, deepEqual, hasText,
+  isArray, isBoolean, isInteger, isIsoDate, isIsoTimeOffsetsDate,
+  isNonEmptyArray, isNonEmptyObject, isNumber, isObject, isString,
+  isValidDate, isValidHelixPreviewUrl, isValidIMSOrgId, isValidUrl,
+  isValidUUID, toBoolean,
+} from './index.js';

package/src/core.js

@@ -0,0 +1,34 @@
+/*
+ * 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.
+ */
+
+export {
+  arrayEquals,
+  dateAfterDays,
+  deepEqual,
+  hasText,
+  isArray,
+  isBoolean,
+  isInteger,
+  isIsoDate,
+  isIsoTimeOffsetsDate,
+  isNonEmptyArray,
+  isNonEmptyObject,
+  isNumber,
+  isObject,
+  isString,
+  isValidDate,
+  isValidHelixPreviewUrl,
+  isValidIMSOrgId,
+  isValidUrl,
+  isValidUUID,
+  toBoolean,
+} from './functions.js';

package/src/email.js

@@ -0,0 +1,22 @@
+/*
+ * 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 isEmail from 'validator/lib/isEmail.js';
+
+/**
+ * Validates whether the given string is a valid email address.
+ * @param {string} email - The string to validate.
+ * @returns {boolean} True if the given string is a valid email address, false otherwise.
+ */
+export function isValidEmail(email) {
+  return typeof email === 'string' && isEmail(email);
+}

package/src/functions.js

@@ -10,8 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-import isEmail from 'validator/lib/isEmail.js';
-
 // Precompile regular expressions
 const REGEX_ISO_DATE = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z/;
 const REGEX_TIME_OFFSET_DATE = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}(Z|[+-]\d{2}:\d{2})/;
@@ -262,15 +260,6 @@ function isValidIMSOrgId(imsOrgId) {
   return IMS_ORG_ID_REGEX.test(imsOrgId);
 }
 
-/**
- * Validates whether the given string is a valid email address.
- * @param {string} email - The string to validate.
- * @returns {boolean} True if the given string is a valid email address, false otherwise.
- */
-function isValidEmail(email) {
-  return typeof email === 'string' && isEmail(email);
-}
-
 /**
  * Validates whether the given string is a valid Helix preview URL.
  * Preview URLs have the format: https://ref--site--owner.domain
@@ -333,7 +322,6 @@ export {
   isObject,
   isString,
   isValidDate,
-  isValidEmail,
   isValidUrl,
   isValidUUID,
   isValidIMSOrgId,

package/src/index.d.ts

@@ -332,6 +332,10 @@ export function getObjectFromKey(
  */
 export function calculateCPCValue(context: object, siteId: string): Promise<number>;
 
+export function isAWSLambda(): boolean;
+export function resetFetchContext(): void;
+export function clearFetchCache(): void;
+
 export function s3Wrapper(fn: (request: object, context: object) => Promise<Response>):
   (request: object, context: object) => Promise<Response>;
 
@@ -349,6 +353,38 @@ export function isoCalendarWeekSunday(date: Date): Date;
 
 export function isoCalendarWeekMonday(date: Date): Date;
 
+interface DateRange {
+  year: number;
+  month: number;
+  startTime: string;
+  endTime: string;
+}
+
+interface WeekInfo {
+  week: number;
+  year: number;
+  month: number;
+  temporalCondition: string;
+}
+
+interface MonthInfo {
+  month: number;
+  year: number;
+  temporalCondition: string;
+}
+
+export function getDateRanges(week?: number, year?: number): DateRange[];
+export function getWeekInfo(inputWeek?: number | null, inputYear?: number | null): WeekInfo;
+export function getMonthInfo(inputMonth?: number | null, inputYear?: number | null): MonthInfo;
+export function getTemporalCondition(options?: {
+  week?: number;
+  month?: number;
+  year?: number;
+  numSeries?: number;
+  log?: object | null;
+}): string;
+export function getLastNumberOfWeeks(number: number): { week: number; year: number }[];
+
 /**
  * Extracts URLs from a suggestion based on the opportunity type.
  * @param opts - Options object
@@ -419,5 +455,5 @@ export * as llmoConfig from './llmo-config.js';
 export * as llmoStrategy from './llmo-strategy.js';
 export * as schemas from './schemas.js';
 
-export { type detectLocale } from './locale-detect/index.js';
-export { type detectBotBlocker } from './bot-blocker-detect/index.js';
+export { detectLocale } from './locale-detect/index.js';
+export { detectBotBlocker } from './bot-blocker-detect/index.js';

package/src/index.js

@@ -26,7 +26,6 @@ export {
   isObject,
   isString,
   isValidDate,
-  isValidEmail,
   isValidUrl,
   isValidUUID,
   isValidIMSOrgId,
@@ -34,6 +33,8 @@ export {
   toBoolean,
 } from './functions.js';
 
+export { isValidEmail } from './email.js';
+
 export {
   resolveSecretsName,
   resolveCustomerSecretsName,

package/src/locale.d.ts

@@ -0,0 +1,13 @@
+/*
+ * 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.
+ */
+
+export { detectLocale } from './index.js';

package/src/locale.js

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+
+/**
+ * @sideeffect Importing this module initializes the @adobe/fetch HTTP connection pool
+ * (h1() or h2() based on HELIX_FETCH_FORCE_HTTP1) at module load time, before any
+ * detectLocale() call is made. In a VPC Lambda with restricted egress or no NAT gateway,
+ * this can cause a silent hang at import time. Ensure your Lambda has outbound internet
+ * access before importing this module.
+ */
+export { detectLocale } from './locale-detect/locale-detect.js';

package/src/opportunity/audit-mapping.js

@@ -79,6 +79,9 @@ export const AUDIT_OPPORTUNITY_MAP = {
   'wikipedia-analysis': ['wikipedia-analysis'],
   'reddit-analysis': ['reddit-analysis'],
   'youtube-analysis': ['youtube-analysis'],
+
+  // LLMO customer / GEO content catalog
+  'llmo-customer-analysis': ['info-gain'],
 };
 
 // ─── Query helpers ───────────────────────────────────────────────────────────

package/src/opportunity/dependency-mapping.js

@@ -97,6 +97,7 @@ export const OPPORTUNITY_DEPENDENCY_MAP = {
   'wikipedia-analysis': [DEPENDENCY_SOURCES.EXTERNAL_API],
   'reddit-analysis': [DEPENDENCY_SOURCES.EXTERNAL_API],
   'youtube-analysis': [DEPENDENCY_SOURCES.EXTERNAL_API],
+  'info-gain': [DEPENDENCY_SOURCES.SCRAPING, DEPENDENCY_SOURCES.EXTERNAL_API],
 };
 
 // ─── Query helpers ───────────────────────────────────────────────────────────

package/src/opportunity/opportunity-titles.js

@@ -73,6 +73,7 @@ export const OPPORTUNITY_TITLES = {
   'wikipedia-analysis': 'Wikipedia Analysis',
   'reddit-analysis': 'Reddit Analysis',
   'youtube-analysis': 'YouTube Analysis',
+  'info-gain': 'Information Gain',
 };
 
 /**

package/src/schemas.d.ts

@@ -0,0 +1,21 @@
+/*
+ * 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 * as z from 'zod';
+
+// NOTE: This file declares types directly rather than re-exporting from ./index.js
+// because index.d.ts exposes schemas as a namespace (export * as schemas), not as
+// flat named exports. The ZodEffects<ZodObject<any>> type is lossy — it erases the
+// specific schema shape, so consumers get no field-level autocomplete or type errors.
+// See "Unify .d.ts declaration strategy" in the design spec's Future Improvements.
+export declare const llmoConfig: z.ZodEffects<z.ZodObject<any>>;
+export type LLMOConfig = z.output<typeof llmoConfig>;

package/src/url-extractors.js

@@ -200,6 +200,33 @@ function extractUrlsFromOpportunity(opts) {
           }
         }
         break;
+      case OPPORTUNITY_TYPES.INFO_GAIN:
+        {
+          const pushCatalogRow = (row) => {
+            const entry = row?.data && typeof row.data === 'object' ? row.data : row;
+            if (!entry || typeof entry !== 'object') {
+              return;
+            }
+            const reportUrl = entry?.report?.url;
+            if (reportUrl && typeof reportUrl === 'string') {
+              urls.push(reportUrl);
+            }
+            const discovered = entry?.discoveredOpportunities;
+            if (Array.isArray(discovered)) {
+              discovered.forEach((opp) => {
+                const targetUrl = opp?.targetUrl;
+                if (targetUrl && typeof targetUrl === 'string') {
+                  urls.push(targetUrl);
+                }
+              });
+            }
+          };
+          const embeddedSuggestions = data?.suggestions;
+          if (Array.isArray(embeddedSuggestions)) {
+            embeddedSuggestions.forEach(pushCatalogRow);
+          }
+        }
+        break;
       default:
         break;
     }