@adobe/spacecat-shared-data-access 3.15.1 → 3.17.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v3.17.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.16.0...@adobe/spacecat-shared-data-access-v3.17.0) (2026-03-12)
+
+### Features
+
+* **data-access:** add cross-tenant query documentation for PlgOnboarding ([#1432](https://github.com/adobe/spacecat-shared/issues/1432)) ([d16c1ea](https://github.com/adobe/spacecat-shared/commit/d16c1ea95dff54ce801cd80e4177c3de853886c5))
+
+## [@adobe/spacecat-shared-data-access-v3.16.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.15.1...@adobe/spacecat-shared-data-access-v3.16.0) (2026-03-12)
+
+### Features
+
+* Added cwv-trends-daily import type ([#1375](https://github.com/adobe/spacecat-shared/issues/1375)) ([14148bb](https://github.com/adobe/spacecat-shared/commit/14148bbcdebc330ad0e4fea2534779c14f3ab30d))
+
 ## [@adobe/spacecat-shared-data-access-v3.15.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.15.0...@adobe/spacecat-shared-data-access-v3.15.1) (2026-03-11)
 
 ### Bug Fixes

package/CLAUDE.md

@@ -214,6 +214,70 @@ const liveSites = await dataAccess.Site.all(
 | `S3_CONFIG_BUCKET` | No | Only for `Configuration` entity |
 | `AWS_REGION` | No | Only for `Configuration` entity |
 
+## Site Config: Import Types
+
+Site configuration lives in `src/models/site/config.js` and defines the available import types, their validation schemas, and default configs. This is one of the most frequently changed files in the package.
+
+### Adding a New Import Type
+
+Update three locations in `src/models/site/config.js`:
+
+**1. Add the constant to `IMPORT_TYPES`:**
+
+```js
+export const IMPORT_TYPES = {
+  // ... existing types
+  MY_NEW_IMPORT: 'my-new-import',
+};
+```
+
+**2. Add the Joi validation schema to `IMPORT_TYPE_SCHEMAS`:**
+
+```js
+export const IMPORT_TYPE_SCHEMAS = {
+  // ... existing schemas
+  [IMPORT_TYPES.MY_NEW_IMPORT]: Joi.object({
+    type: Joi.string().valid(IMPORT_TYPES.MY_NEW_IMPORT).required(),
+    ...IMPORT_BASE_KEYS,
+    // Add optional type-specific fields here (e.g., geo, limit, year, week)
+  }),
+};
+```
+
+`IMPORT_BASE_KEYS` includes `enabled`, `destinations`, and `sources`. Only add extra fields if the import type needs them.
+
+**3. Add the default config to `DEFAULT_IMPORT_CONFIGS`:**
+
+```js
+export const DEFAULT_IMPORT_CONFIGS = {
+  // ... existing defaults
+  'my-new-import': {
+    type: 'my-new-import',
+    destinations: ['default'],
+    sources: ['rum'],   // or 'ahrefs', 'google'
+    enabled: true,
+  },
+};
+```
+
+### Test Updates
+
+In `test/unit/models/site/config.test.js`, add:
+
+1. **Enable import test** — verify `config.enableImport('my-new-import')` produces the expected default config
+2. **Validation error string** — the long `.to.equal(...)` assertion for invalid import type errors must include the new type
+3. **Validation error details** — the `.to.eql([...])` array of expected error detail objects must include the new type
+
+### Available Sources
+
+| Source | Constant | Used by |
+|--------|----------|---------|
+| `'ahrefs'` | `IMPORT_SOURCES.AHREFS` | Keyword, traffic, backlink imports |
+| `'google'` | `IMPORT_SOURCES.GSC` | Google Search Console imports |
+| `'rum'` | `IMPORT_SOURCES.RUM` | RUM/CWV/engagement imports |
+
+---
+
 ## Special Entities
 
 - **Configuration**: S3-backed (not PostgREST). Requires `S3_CONFIG_BUCKET`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/base/entity.registry.js

@@ -43,6 +43,7 @@ import ReportCollection from '../report/report.collection.js';
 import TrialUserCollection from '../trial-user/trial-user.collection.js';
 import TrialUserActivityCollection from '../trial-user-activity/trial-user-activity.collection.js';
 import PageCitabilityCollection from '../page-citability/page-citability.collection.js';
+import PlgOnboardingCollection from '../plg-onboarding/plg-onboarding.collection.js';
 import SentimentGuidelineCollection from '../sentiment-guideline/sentiment-guideline.collection.js';
 import SentimentTopicCollection from '../sentiment-topic/sentiment-topic.collection.js';
 
@@ -75,6 +76,7 @@ import ReportSchema from '../report/report.schema.js';
 import TrialUserSchema from '../trial-user/trial-user.schema.js';
 import TrialUserActivitySchema from '../trial-user-activity/trial-user-activity.schema.js';
 import PageCitabilitySchema from '../page-citability/page-citability.schema.js';
+import PlgOnboardingSchema from '../plg-onboarding/plg-onboarding.schema.js';
 import SentimentGuidelineSchema from '../sentiment-guideline/sentiment-guideline.schema.js';
 import SentimentTopicSchema from '../sentiment-topic/sentiment-topic.schema.js';
 
@@ -202,6 +204,7 @@ EntityRegistry.registerEntity(ReportSchema, ReportCollection);
 EntityRegistry.registerEntity(TrialUserSchema, TrialUserCollection);
 EntityRegistry.registerEntity(TrialUserActivitySchema, TrialUserActivityCollection);
 EntityRegistry.registerEntity(PageCitabilitySchema, PageCitabilityCollection);
+EntityRegistry.registerEntity(PlgOnboardingSchema, PlgOnboardingCollection);
 EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollection);
 EntityRegistry.registerEntity(SentimentTopicSchema, SentimentTopicCollection);
 EntityRegistry.defaultEntities = { ...EntityRegistry.entities };

package/src/models/index.d.ts

@@ -29,6 +29,7 @@ export type * from './opportunity';
 export type * from './organization';
 export type * from './page-citability';
 export type * from './page-intent';
+export type * from './plg-onboarding';
 export type * from './project';
 export type * from './report';
 export type * from './scrape-job';

package/src/models/index.js

@@ -41,5 +41,6 @@ export * from './report/index.js';
 export * from './trial-user/index.js';
 export * from './trial-user-activity/index.js';
 export * from './page-citability/index.js';
+export * from './plg-onboarding/index.js';
 export * from './sentiment-guideline/index.js';
 export * from './sentiment-topic/index.js';

package/src/models/plg-onboarding/index.d.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2026 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 { BaseCollection, BaseModel } from '../index';
+
+export type PlgOnboardingStatus =
+  | 'IN_PROGRESS'
+  | 'ONBOARDED'
+  | 'ERROR'
+  | 'WAITING_FOR_IP_ALLOWLISTING'
+  | 'WAITLISTED';
+
+export interface PlgOnboarding extends BaseModel {
+  getImsOrgId(): string;
+  getDomain(): string;
+  getBaseURL(): string;
+  getStatus(): PlgOnboardingStatus;
+  getSiteId(): string | null;
+  getOrganizationId(): string | null;
+  getSteps(): object | null;
+  getError(): object | null;
+  getBotBlocker(): object | null;
+  getWaitlistReason(): string | null;
+  getCompletedAt(): string | null;
+  setStatus(status: PlgOnboardingStatus): PlgOnboarding;
+  setSiteId(siteId: string): PlgOnboarding;
+  setOrganizationId(organizationId: string): PlgOnboarding;
+  setSteps(steps: object): PlgOnboarding;
+  setError(error: object): PlgOnboarding;
+  setBotBlocker(botBlocker: object): PlgOnboarding;
+  setWaitlistReason(waitlistReason: string): PlgOnboarding;
+  setCompletedAt(completedAt: string): PlgOnboarding;
+}
+
+export interface PlgOnboardingCollection extends BaseCollection<PlgOnboarding> {
+  allByImsOrgId(imsOrgId: string): Promise<PlgOnboarding[]>;
+  findByImsOrgId(imsOrgId: string): Promise<PlgOnboarding | null>;
+  allByImsOrgIdAndUpdatedAt(imsOrgId: string, updatedAt: string): Promise<PlgOnboarding[]>;
+  findByImsOrgIdAndUpdatedAt(imsOrgId: string, updatedAt: string): Promise<PlgOnboarding | null>;
+  allByImsOrgIdAndDomain(imsOrgId: string, domain: string): Promise<PlgOnboarding[]>;
+  findByImsOrgIdAndDomain(imsOrgId: string, domain: string): Promise<PlgOnboarding | null>;
+  allByStatus(status: PlgOnboardingStatus): Promise<PlgOnboarding[]>;
+  findByStatus(status: PlgOnboardingStatus): Promise<PlgOnboarding | null>;
+  allByStatusAndUpdatedAt(status: PlgOnboardingStatus, updatedAt: string): Promise<PlgOnboarding[]>;
+  findByStatusAndUpdatedAt(status: PlgOnboardingStatus, updatedAt: string): Promise<PlgOnboarding | null>;
+  allByBaseURL(baseURL: string): Promise<PlgOnboarding[]>;
+  findByBaseURL(baseURL: string): Promise<PlgOnboarding | null>;
+  allByBaseURLAndStatus(baseURL: string, status: PlgOnboardingStatus): Promise<PlgOnboarding[]>;
+  findByBaseURLAndStatus(baseURL: string, status: PlgOnboardingStatus): Promise<PlgOnboarding | null>;
+}

package/src/models/plg-onboarding/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2026 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 PlgOnboarding from './plg-onboarding.model.js';
+import PlgOnboardingCollection from './plg-onboarding.collection.js';
+
+export {
+  PlgOnboarding,
+  PlgOnboardingCollection,
+};

package/src/models/plg-onboarding/plg-onboarding.collection.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2026 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 BaseCollection from '../base/base.collection.js';
+
+/**
+ * PlgOnboardingCollection - A collection class responsible for managing
+ * PlgOnboarding entities.
+ *
+ * Note: allByStatus and allByBaseURL return cross-tenant results
+ * intended for internal/admin use only.
+ *
+ * @class PlgOnboardingCollection
+ * @extends BaseCollection
+ */
+class PlgOnboardingCollection extends BaseCollection {
+  static COLLECTION_NAME = 'PlgOnboardingCollection';
+}
+
+export default PlgOnboardingCollection;

package/src/models/plg-onboarding/plg-onboarding.model.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2026 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';
+
+/**
+ * PlgOnboarding - A class representing a PLG onboarding entity.
+ * Tracks the self-service onboarding lifecycle for ASO customers.
+ *
+ * @class PlgOnboarding
+ * @extends BaseModel
+ */
+class PlgOnboarding extends BaseModel {
+  static ENTITY_NAME = 'PlgOnboarding';
+
+  static IMS_ORG_ID_PATTERN = /^[a-z0-9]{24}@AdobeOrg$/i;
+
+  static DOMAIN_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+
+  static STATUSES = {
+    IN_PROGRESS: 'IN_PROGRESS',
+    ONBOARDED: 'ONBOARDED',
+    ERROR: 'ERROR',
+    WAITING_FOR_IP_ALLOWLISTING: 'WAITING_FOR_IP_ALLOWLISTING',
+    WAITLISTED: 'WAITLISTED',
+  };
+}
+
+export default PlgOnboarding;

package/src/models/plg-onboarding/plg-onboarding.schema.js

@@ -0,0 +1,113 @@
+/*
+ * Copyright 2026 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 {
+  isIsoDate, isObject, isValidUrl, isValidUUID,
+} from '@adobe/spacecat-shared-utils';
+import SchemaBuilder from '../base/schema.builder.js';
+import PlgOnboarding from './plg-onboarding.model.js';
+import PlgOnboardingCollection from './plg-onboarding.collection.js';
+
+/*
+Schema Doc: https://electrodb.dev/en/modeling/schema/
+Attribute Doc: https://electrodb.dev/en/modeling/attributes/
+Indexes Doc: https://electrodb.dev/en/modeling/indexes/
+*/
+
+const schema = new SchemaBuilder(PlgOnboarding, PlgOnboardingCollection)
+  .addAttribute('imsOrgId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => PlgOnboarding.IMS_ORG_ID_PATTERN.test(value),
+  })
+  .addAttribute('domain', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => PlgOnboarding.DOMAIN_PATTERN.test(value) && value.length <= 253,
+  })
+  .addAttribute('baseURL', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUrl(value),
+  })
+  .addAttribute('status', {
+    type: Object.values(PlgOnboarding.STATUSES),
+    required: true,
+    default: PlgOnboarding.STATUSES.IN_PROGRESS,
+  })
+  .addAttribute('siteId', {
+    type: 'string',
+    required: false,
+    validate: (value) => !value || isValidUUID(value),
+  })
+  .addAttribute('organizationId', {
+    type: 'string',
+    required: false,
+    validate: (value) => !value || isValidUUID(value),
+  })
+  .addAttribute('steps', {
+    type: 'map',
+    properties: {
+      orgResolved: { type: 'boolean' },
+      rumVerified: { type: 'boolean' },
+      siteCreated: { type: 'boolean' },
+      siteResolved: { type: 'boolean' },
+      configUpdated: { type: 'boolean' },
+      auditsEnabled: { type: 'boolean' },
+      entitlementCreated: { type: 'boolean' },
+    },
+  })
+  .addAttribute('error', {
+    type: 'any',
+    validate: (value) => !value || isObject(value),
+  })
+  .addAttribute('botBlocker', {
+    type: 'map',
+    properties: {
+      type: { type: 'string' },
+      ipsToAllowlist: { type: 'list', items: { type: 'string' } },
+      userAgent: { type: 'string' },
+    },
+  })
+  .addAttribute('waitlistReason', {
+    type: 'string',
+    required: false,
+  })
+  .addAttribute('completedAt', {
+    type: 'string',
+    validate: (value) => !value || isIsoDate(value),
+  })
+  // Index: by imsOrgId (PK=imsOrgId, SK=updatedAt) → allByImsOrgId / findByImsOrgId
+  .addIndex(
+    { composite: ['imsOrgId'] },
+    { composite: ['updatedAt'] },
+  )
+  // Index: by imsOrgId+domain (PK=imsOrgId, SK=domain) → findByImsOrgIdAndDomain
+  .addIndex(
+    { composite: ['imsOrgId'] },
+    { composite: ['domain'] },
+  )
+  // Index: by status (PK=status, SK=updatedAt) → allByStatus
+  .addIndex(
+    { composite: ['status'] },
+    { composite: ['updatedAt'] },
+  )
+  // Index: by baseURL (PK=baseURL, SK=status) → findByBaseURL
+  .addIndex(
+    { composite: ['baseURL'] },
+    { composite: ['status'] },
+  );
+
+export default schema.build();

package/src/models/site/config.js

@@ -33,6 +33,8 @@ export const IMPORT_TYPES = {
   TOP_FORMS: 'top-forms',
   CODE: 'code',
   USER_ENGAGEMENT: 'user-engagement',
+  CWV_TRENDS_DAILY: 'cwv-trends-daily',
+  CWV_TRENDS_ONBOARD: 'cwv-trends-onboard',
 };
 
 export const IMPORT_DESTINATIONS = {
@@ -170,6 +172,14 @@ export const IMPORT_TYPE_SCHEMAS = {
     type: Joi.string().valid(IMPORT_TYPES.USER_ENGAGEMENT).required(),
     ...IMPORT_BASE_KEYS,
   }),
+  [IMPORT_TYPES.CWV_TRENDS_DAILY]: Joi.object({
+    type: Joi.string().valid(IMPORT_TYPES.CWV_TRENDS_DAILY).required(),
+    ...IMPORT_BASE_KEYS,
+  }),
+  [IMPORT_TYPES.CWV_TRENDS_ONBOARD]: Joi.object({
+    type: Joi.string().valid(IMPORT_TYPES.CWV_TRENDS_ONBOARD).required(),
+    ...IMPORT_BASE_KEYS,
+  }),
 };
 
 export const DEFAULT_IMPORT_CONFIGS = {
@@ -258,6 +268,18 @@ export const DEFAULT_IMPORT_CONFIGS = {
     sources: ['rum'],
     enabled: true,
   },
+  'cwv-trends-daily': {
+    type: 'cwv-trends-daily',
+    destinations: ['default'],
+    sources: ['rum'],
+    enabled: true,
+  },
+  'cwv-trends-onboard': {
+    type: 'cwv-trends-onboard',
+    destinations: ['default'],
+    sources: ['rum'],
+    enabled: true,
+  },
 };
 
 export const configSchema = Joi.object({

package/src/service/index.d.ts

@@ -30,6 +30,7 @@ import type { OpportunityCollection } from '../models/opportunity';
 import type { OrganizationCollection } from '../models/organization';
 import type { PageCitabilityCollection } from '../models/page-citability';
 import type { PageIntentCollection } from '../models/page-intent';
+import type { PlgOnboardingCollection } from '../models/plg-onboarding';
 import type { ProjectCollection } from '../models/project';
 import type { ReportCollection } from '../models/report';
 import type { ScrapeJobCollection } from '../models/scrape-job';
@@ -78,6 +79,7 @@ export interface DataAccess {
   Organization: OrganizationCollection;
   PageCitability: PageCitabilityCollection;
   PageIntent: PageIntentCollection;
+  PlgOnboarding: PlgOnboardingCollection;
   Project: ProjectCollection;
   Report: ReportCollection;
   ScrapeJob: ScrapeJobCollection;