Merge remote-tracking branch 'origin/main' into code-apply-patch

# Conflicts:
#	package-lock.json
#	packages/spacecat-shared-cloud-manager-client/src/index.js

Author: rpapani

.github/CODEOWNERS

@@ -61,7 +61,7 @@ jobs:
       - name: Set up Node.js 22 (temporary - for bootstrap)
         uses: actions/setup-node@v6
         with:
-          node-version: '22.21.1'
+          node-version: '22.22.1'
 
       - name: Update NPM
         run: npm install -g npm@10.9.4

.github/workflows/main.yaml

@@ -1,2 +1,2 @@
-24.11.1
+24.14.0
 

.nvmrc

@@ -0,0 +1,248 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install all dependencies (root + all packages)
+npm install
+
+# Run all tests across all packages
+npm test
+
+# Run tests for a single package
+npm test -w packages/spacecat-shared-utils
+
+# Run integration tests (data-access only, requires Docker)
+npm run test:it -w packages/spacecat-shared-data-access
+
+# Lint all packages
+npm run lint
+
+# Lint a single package
+npm run lint -w packages/spacecat-shared-utils
+
+# Generate API docs
+npm run docs
+
+# Dry-run semantic release (on non-main branches)
+npm run semantic-release-dry
+
+# Clean node_modules and lock file
+npm run clean
+```
+
+Node >=22 <25 is required (see `.nvmrc` for exact version). The project is pure ESM (`"type": "module"`).
+
+Coverage enforcement: **100% lines/statements, 97% branches** per package (see each package's `.nycrc.json`).
+
+---
+
+## Architecture Overview
+
+This is the **foundation library layer** for all SpaceCat Node.js services. It's an npm workspaces monorepo (no lerna/nx) containing 22 packages that provide data access, API clients, utilities, and auth used by `spacecat-api-service`, `spacecat-audit-worker`, `spacecat-import-worker`, and other platform services.
+
+### Monorepo Structure
+
+```
+spacecat-shared/
+├── packages/                     # 22 npm workspace packages
+│   ├── spacecat-shared-data-access/   # Core data layer (PostgREST + Aurora PostgreSQL)
+│   ├── spacecat-shared-http-utils/    # HTTP response helpers + auth middleware
+│   ├── spacecat-shared-utils/         # General utilities (validation, S3, SQS, helpers)
+│   ├── spacecat-shared-rum-api-client/ # RUM Bundler API client
+│   ├── spacecat-shared-vault-secrets/ # HashiCorp Vault secrets (replaces helix-shared-secrets)
+│   ├── spacecat-shared-*-client/      # 13+ API clients (ahrefs, google, slack, etc.)
+│   ├── spacecat-shared-html-analyzer/ # HTML analysis utilities
+│   └── spacecat-shared-example/       # Example/template package
+├── docs/                         # Generated API docs
+├── eslint.config.js              # Root ESLint flat config
+├── .releaserc.cjs                # Root semantic-release config
+└── package.json                  # Monorepo root (private, workspaces: ./packages/*)
+```
+
+### Package Catalog
+
+| Category | Packages | Purpose |
+|----------|----------|---------|
+| **Data layer** | `data-access` | Entity models/collections backed by PostgreSQL via PostgREST |
+| **HTTP/Auth** | `http-utils` | HTTP response helpers, auth handlers (ScopedApiKey, LegacyApiKey, IMS) |
+| **Utilities** | `utils` | Validation, S3/SQS helpers, schemas, date functions |
+| **Secrets** | `vault-secrets` | HashiCorp Vault integration (AppRole auth, KV secrets) |
+| **HTML** | `html-analyzer` | HTML analysis and extraction |
+| **API clients** | `ahrefs-client`, `athena-client`, `brand-client`, `cloud-manager-client`, `content-client`, `drs-client`, `google-client`, `gpt-client`, `ims-client`, `launchdarkly-client`, `rum-api-client`, `scrape-client`, `slack-client`, `splunk-client`, `tier-client`, `tokowaka-client` | External service integrations |
+| **Example** | `example` | Template for creating new packages |
+
+### Package-Level CLAUDE.md Files
+
+Some packages have their own CLAUDE.md with deeper architectural guidance:
+
+- [`packages/spacecat-shared-data-access/CLAUDE.md`](packages/spacecat-shared-data-access/CLAUDE.md) — Entity pattern, SchemaBuilder DSL, PostgREST queries, integration tests
+- [`packages/spacecat-shared-vault-secrets/CLAUDE.md`](packages/spacecat-shared-vault-secrets/CLAUDE.md) — Vault pipeline, AppRole auth, E2E validation
+- [`packages/spacecat-shared-google-client/docs/CLAUDE.md`](packages/spacecat-shared-google-client/docs/CLAUDE.md) — GSC client, OAuth, environment variables
+
+---
+
+## Key Patterns
+
+### Per-Package File Structure
+
+Each package follows this layout:
+
+```
+packages/spacecat-shared-<name>/
+├── src/              # Source code
+│   └── index.js      # Package entry point (barrel exports)
+├── test/             # Tests (mirrors src/ structure)
+├── package.json      # Package metadata, dependencies, scripts
+├── .releaserc.cjs    # semantic-release config (extends monorepo)
+├── .nycrc.json       # c8 coverage config
+├── README.md
+└── CHANGELOG.md      # Auto-generated by semantic-release
+```
+
+### Entity Pattern (data-access)
+
+The data-access package defines entities with 4 files per entity:
+
+```
+src/models/<entity>/
+  <entity>.schema.js       # SchemaBuilder definition (attributes, references, indexes)
+  <entity>.model.js        # Extends BaseModel (business logic, constants)
+  <entity>.collection.js   # Extends BaseCollection (custom queries)
+  index.js                 # Re-exports model, collection, schema
+```
+
+See [`packages/spacecat-shared-data-access/CLAUDE.md`](packages/spacecat-shared-data-access/CLAUDE.md) for the SchemaBuilder DSL, attribute options, and field mapping details.
+
+### Field Mapping Convention
+
+Models use **camelCase**, the database uses **snake_case**. Mapping is automatic via `postgrest.utils.js`. Override with `postgrestField: 'custom_name'` on individual attributes.
+
+### TypeScript Declarations
+
+Packages provide `.d.ts` files for public APIs — no TypeScript source code. Type declarations live alongside the source files they describe.
+
+### API Client Pattern
+
+API clients typically follow this structure:
+
+```js
+export default class FooClient {
+  constructor(config, log) { /* ... */ }
+  async someOperation(params) { /* ... */ }
+}
+
+// Factory function exported from index.js
+export function createFooClient(config, log) {
+  return new FooClient(config, log);
+}
+```
+
+---
+
+## Testing
+
+**Framework:** Mocha + Chai + chai-as-promised + sinon + sinon-chai
+**Coverage:** c8 (per-package `.nycrc.json`)
+**HTTP mocking:** nock
+**Reporters:** mocha-multi-reporters (spec + xunit)
+
+### Running Tests
+
+```bash
+# All packages
+npm test
+
+# Single package
+npm test -w packages/spacecat-shared-utils
+
+# Integration tests (data-access only — requires Docker + ECR access)
+npm run test:it -w packages/spacecat-shared-data-access
+```
+
+### Test Conventions
+
+- Tests live in `test/` (or `test/unit/`) and mirror the `src/` directory structure
+- Use `describe`/`it` blocks with `expect` assertions
+- sinon stubs for external dependencies; nock for HTTP mocking
+- Each test file uses a sandbox: `const sandbox = sinon.createSandbox()` with `afterEach(() => sandbox.restore())`
+- Coverage thresholds are enforced per package
+
+### Integration Tests (data-access)
+
+Integration tests require the `mysticat-data-service` Docker image from ECR:
+
+```bash
+# ECR login (one-time)
+aws ecr get-login-password --profile spacecat-dev --region us-east-1 \
+  | docker login --username AWS --password-stdin 682033462621.dkr.ecr.us-east-1.amazonaws.com
+
+npm run test:it -w packages/spacecat-shared-data-access
+```
+
+---
+
+## Working with the Monorepo
+
+### Inter-Package Dependencies
+
+Some packages depend on others in the monorepo (e.g., `data-access` depends on `utils`). These are declared as regular npm dependencies with the published `@adobe/spacecat-shared-*` package name and version.
+
+### Running Commands for a Single Package
+
+Use the `-w` (workspace) flag:
+
+```bash
+npm test -w packages/spacecat-shared-<name>
+npm run lint -w packages/spacecat-shared-<name>
+```
+
+### Adding a New Package
+
+1. Copy `packages/spacecat-shared-example/` as a starting template
+2. Rename the directory to `spacecat-shared-<name>`
+3. Update `package.json`: name (`@adobe/spacecat-shared-<name>`), description, dependencies
+4. Update `.releaserc.cjs` (inherits from root)
+5. Implement source in `src/`, tests in `test/`
+6. Ensure 100% coverage with `.nycrc.json` thresholds
+7. The root `workspaces: ["./packages/*"]` auto-discovers it
+
+### Adding a New Entity (data-access)
+
+1. Create 4 files in `src/models/<entity>/`: `schema.js`, `model.js`, `collection.js`, `index.js`
+2. Register the entity in `src/models/index.js`
+3. The corresponding DB migration must be created in [mysticat-data-service](https://github.com/adobe/mysticat-data-service)
+4. Add unit tests in `test/unit/models/<entity>/`
+
+### Adding a New Import Type (data-access)
+
+1. Update three locations in `src/models/site/config.js`: `IMPORT_TYPES`, `IMPORT_TYPE_SCHEMAS`, `DEFAULT_IMPORT_CONFIGS`
+2. Update three corresponding assertions in `test/unit/models/site/config.test.js`
+
+See [`packages/spacecat-shared-data-access/CLAUDE.md`](packages/spacecat-shared-data-access/CLAUDE.md) for full details including code examples.
+
+---
+
+## Commits and Releases
+
+- **Conventional commits** are required — use `npm run commit` (commitizen) or write them manually
+- **Pre-commit hook** (husky + lint-staged) runs ESLint on staged `.js` files
+- **semantic-release** with `semantic-release-monorepo` handles per-package versioning
+- Release happens automatically on push to `main` — each package is released independently based on commits touching its files
+- **Branch:** `main` is the only release branch
+
+### After Publishing
+
+When a new version of a `spacecat-shared-*` package is published, update the dependency version in all consuming repos (`spacecat-api-service`, `spacecat-audit-worker`, `spacecat-import-worker`, etc.).
+
+---
+
+## Linting
+
+- **Config:** `eslint.config.js` (ESLint flat config)
+- **Base:** `@adobe/eslint-config-helix` (recommended + source + test presets)
+- **Parser:** `@babel/eslint-parser` with ESM + import assertions
+- **Test overrides:** `no-console: off`, `func-names: off`
+- **Ignored:** `.vscode`, `.idea`, `coverage`, `docs`, `vendor`, `dist`, `.releaserc.cjs`, `test/fixtures`

CLAUDE.md

@@ -14,5 +14,5 @@ $ npm install @adobe/spacecat-shared-http-utils
 $ npm install @adobe/spacecat-shared-utils
 ```
 
-## Usage
+## Usage 
 See the [API documentation](docs/API.md).

README.md

@@ -0,0 +1,39 @@
+# CWV Trends Audit — spacecat-shared Changes
+
+## Overview
+
+Adds the `CWV_TRENDS_AUDIT` audit type to `Audit.AUDIT_TYPES` in the `spacecat-shared-data-access` package, enabling the new CWV Trends Audit feature across the SpaceCat ecosystem.
+
+## Change
+
+**File:** `packages/spacecat-shared-data-access/src/models/audit/audit.model.js`
+
+```javascript
+static AUDIT_TYPES = {
+  // ... existing types ...
+  CWV_TRENDS_AUDIT: 'cwv-trends-audit',
+};
+```
+
+## Context
+
+The CWV Trends Audit is a weekly audit (`every-sunday`) that:
+
+- Reads 28 days of pre-imported CWV data from S3 (`metrics/cwv-trends/cwv-trends-daily-{date}.json`)
+- Classifies URLs as Good / Needs Improvement / Poor using standard CWV thresholds
+- Determines device type (mobile/desktop) from site handler configuration
+- Creates/updates device-specific opportunities: "Mobile Web Performance Trends Report" or "Desktop Web Performance Trends Report"
+- Syncs per-URL suggestions with `CONTENT_UPDATE` type
+
+## Dependent Repositories
+
+| Repository | Dependency | Action Required |
+|---|---|---|
+| `spacecat-audit-worker` | `@adobe/spacecat-shared-data-access` | Bump version after this package is published |
+| `spacecat-api-service` | `@adobe/spacecat-shared-data-access` | Bump version to recognize the new audit type |
+
+## Deployment Order
+
+1. Merge this PR → semantic-release publishes new `@adobe/spacecat-shared-data-access`
+2. Bump dependency in `spacecat-audit-worker` and `spacecat-api-service`
+3. Register audit: `registerAudit('cwv-trends-audit', false, 'every-sunday', [productCodes])`