@adobe/spacecat-shared-data-access 2.40.2 → 2.42.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v2.42.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.41.0...@adobe/spacecat-shared-data-access-v2.42.0) (2025-07-29)
+
+
+### Features
+
+* added `status` field in reports ([#883](https://github.com/adobe/spacecat-shared/issues/883)) ([f6e9fcd](https://github.com/adobe/spacecat-shared/commit/f6e9fcd1e8e5eabb731c4cdbd89654fc725c9837))
+
+# [@adobe/spacecat-shared-data-access-v2.41.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.40.2...@adobe/spacecat-shared-data-access-v2.41.0) (2025-07-28)
+
+
+### Features
+
+* add top form model ([#863](https://github.com/adobe/spacecat-shared/issues/863)) ([66138ce](https://github.com/adobe/spacecat-shared/commit/66138ced4a0b0e3c68bf0aaec02b7adaafb0503d))
+
 # [@adobe/spacecat-shared-data-access-v2.40.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.40.1...@adobe/spacecat-shared-data-access-v2.40.2) (2025-07-28)
 
 

package/package.json

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

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

@@ -29,6 +29,7 @@ import ScrapeJobCollection from '../scrape-job/scrape-job.collection.js';
 import ScrapeUrlCollection from '../scrape-url/scrape-url.collection.js';
 import SiteCandidateCollection from '../site-candidate/site-candidate.collection.js';
 import SiteCollection from '../site/site.collection.js';
+import SiteTopFormCollection from '../site-top-form/site-top-form.collection.js';
 import SiteTopPageCollection from '../site-top-page/site-top-page.collection.js';
 import SuggestionCollection from '../suggestion/suggestion.collection.js';
 import PageIntentCollection from '../page-intent/page-intent.collection.js';
@@ -50,6 +51,7 @@ import ScrapeJobSchema from '../scrape-job/scrape-job.schema.js';
 import ScrapeUrlSchema from '../scrape-url/scrape-url.schema.js';
 import SiteSchema from '../site/site.schema.js';
 import SiteCandidateSchema from '../site-candidate/site-candidate.schema.js';
+import SiteTopFormSchema from '../site-top-form/site-top-form.schema.js';
 import SiteTopPageSchema from '../site-top-page/site-top-page.schema.js';
 import SuggestionSchema from '../suggestion/suggestion.schema.js';
 import PageIntentSchema from '../page-intent/page-intent.schema.js';
@@ -152,6 +154,7 @@ EntityRegistry.registerEntity(ScrapeJobSchema, ScrapeJobCollection);
 EntityRegistry.registerEntity(ScrapeUrlSchema, ScrapeUrlCollection);
 EntityRegistry.registerEntity(SiteSchema, SiteCollection);
 EntityRegistry.registerEntity(SiteCandidateSchema, SiteCandidateCollection);
+EntityRegistry.registerEntity(SiteTopFormSchema, SiteTopFormCollection);
 EntityRegistry.registerEntity(SiteTopPageSchema, SiteTopPageCollection);
 EntityRegistry.registerEntity(SuggestionSchema, SuggestionCollection);
 EntityRegistry.registerEntity(PageIntentSchema, PageIntentCollection);

package/src/models/index.d.ts

@@ -26,6 +26,7 @@ export type * from './scrape-job';
 export type * from './scrape-url';
 export type * from './site';
 export type * from './site-candidate';
+export type * from './site-top-form';
 export type * from './site-top-page';
 export type * from './suggestion';
 export type * from './report';

package/src/models/index.js

@@ -26,6 +26,7 @@ export * from './organization/index.js';
 export * from './scrape-job/index.js';
 export * from './scrape-url/index.js';
 export * from './site-candidate/index.js';
+export * from './site-top-form/index.js';
 export * from './site-top-page/index.js';
 export * from './site/index.js';
 export * from './suggestion/index.js';

package/src/models/report/report.schema.js

@@ -48,6 +48,11 @@ const schema = new SchemaBuilder(Report, ReportCollection)
     required: false,
     default: () => '',
     validate: (value) => !value || (isString(value) && value.length >= 0),
+  })
+  .addAttribute('status', {
+    type: ['processing', 'success', 'failed'],
+    required: true,
+    default: 'processing',
   });
 
 export default schema.build();

package/src/models/site/config.js

@@ -25,6 +25,7 @@ export const IMPORT_TYPES = {
   CWV_DAILY: 'cwv-daily',
   CWV_WEEKLY: 'cwv-weekly',
   TRAFFIC_ANALYSIS: 'traffic-analysis',
+  TOP_FORMS: 'top-forms',
 };
 
 export const IMPORT_DESTINATIONS = {
@@ -138,6 +139,12 @@ export const IMPORT_TYPE_SCHEMAS = {
     week: Joi.number().integer().optional(),
     ...IMPORT_BASE_KEYS,
   }),
+  [IMPORT_TYPES.TOP_FORMS]: Joi.object({
+    type: Joi.string().valid(IMPORT_TYPES.TOP_FORMS).required(),
+    ...IMPORT_BASE_KEYS,
+    limit: Joi.number().integer().min(1).max(2000)
+      .optional(),
+  }),
 };
 
 export const DEFAULT_IMPORT_CONFIGS = {
@@ -208,6 +215,12 @@ export const DEFAULT_IMPORT_CONFIGS = {
     sources: ['rum'],
     enabled: true,
   },
+  'top-forms': {
+    type: 'top-forms',
+    destinations: ['default'],
+    sources: ['rum'],
+    enabled: true,
+  },
 };
 
 export const configSchema = Joi.object({

package/src/models/site/index.d.ts

@@ -36,6 +36,7 @@ export type IMPORT_TYPES = {
   readonly ORGANIC_KEYWORDS: 'organic-keywords';
   readonly ORGANIC_TRAFFIC: 'organic-traffic';
   readonly TOP_PAGES: 'top-pages';
+  readonly TOP_FORMS: 'top-forms';
 };
 
 export type IMPORT_DESTINATIONS = {
@@ -47,7 +48,7 @@ export type IMPORT_SOURCES = {
   readonly GSC: 'google';
 };
 
-export type ImportType = 'organic-keywords' | 'organic-traffic' | 'top-pages';
+export type ImportType = 'organic-keywords' | 'organic-traffic' | 'top-pages' | 'top-forms';
 export type ImportDestination = 'default';
 export type ImportSource = 'ahrefs' | 'google';
 

package/src/models/site/site.schema.js

@@ -42,6 +42,7 @@ const schema = new SchemaBuilder(Site, SiteCollection)
   .addReference('has_one', 'LatestAudit', ['auditType'], { required: false })
   .addReference('has_many', 'Opportunities')
   .addReference('has_many', 'SiteCandidates')
+  .addReference('has_many', 'SiteTopForms')
   .addReference('has_many', 'SiteTopPages')
   .addReference('has_many', 'PageIntents')
   .addAttribute('baseURL', {

package/src/models/site-top-form/index.d.ts

@@ -0,0 +1,39 @@
+/*
+ * 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 { BaseCollection, BaseModel, Site } from '../index';
+
+export interface SiteTopForm extends BaseModel {
+  getFormSource(): string;
+  getImportedAt(): string;
+  getSite(): Promise<Site>;
+  getSiteId(): string;
+  getSource(): string;
+  getTraffic(): number | undefined;
+  getUrl(): string;
+  setFormSource(formSource: string): SiteTopForm;
+  setImportedAt(importedAt: string): SiteTopForm;
+  setSiteId(siteId: string): SiteTopForm;
+  setSource(source: string): SiteTopForm;
+  setTraffic(traffic: number): SiteTopForm;
+  setUrl(url: string): SiteTopForm;
+}
+
+export interface SiteTopFormCollection extends BaseCollection<SiteTopForm> {
+  allBySiteId(siteId: string): Promise<SiteTopForm[]>;
+  allBySiteIdAndSource(siteId: string, source: string): Promise<SiteTopForm[]>;
+  findBySiteId(siteId: string): Promise<SiteTopForm | null>;
+  findBySiteIdAndSource(siteId: string, source: string): Promise<SiteTopForm | null>;
+  findByUrlAndFormSource(url: string, formSource: string): Promise<SiteTopForm | null>;
+  removeByUrlAndFormSource(url: string, formSource: string): Promise<void>;
+  removeForSiteId(siteId: string, source: string): Promise<void>;
+}

package/src/models/site-top-form/index.js

@@ -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.
+ */
+
+import SiteTopForm from './site-top-form.model.js';
+import SiteTopFormCollection from './site-top-form.collection.js';
+
+export {
+  SiteTopForm,
+  SiteTopFormCollection,
+};

package/src/models/site-top-form/site-top-form.collection.js

@@ -0,0 +1,61 @@
+/*
+ * 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, isNonEmptyArray } from '@adobe/spacecat-shared-utils';
+
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * SiteTopFormCollection - A collection class responsible for managing SiteTopForm entities.
+ * Extends the BaseCollection to provide specific methods for interacting with SiteTopForm records.
+ *
+ * @class SiteTopFormCollection
+ * @extends BaseCollection
+ */
+class SiteTopFormCollection extends BaseCollection {
+  async removeForSiteId(siteId, source) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    let topFormsToRemove;
+
+    if (hasText(source)) {
+      topFormsToRemove = await this.allBySiteIdAndSource(siteId, source);
+    } else {
+      topFormsToRemove = await this.allBySiteId(siteId);
+    }
+
+    const topFormIdsToRemove = topFormsToRemove.map((topForm) => topForm.getId());
+
+    if (isNonEmptyArray(topFormIdsToRemove)) {
+      await this.removeByIds(topFormIdsToRemove);
+    }
+  }
+
+  async removeByUrlAndFormSource(url, formSource) {
+    if (!hasText(url)) {
+      throw new Error('URL is required');
+    }
+    if (!hasText(formSource)) {
+      throw new Error('FormSource is required');
+    }
+
+    const formToRemove = await this.findByUrlAndFormSource(url, formSource);
+
+    if (formToRemove) {
+      await this.removeByIds([formToRemove.getId()]);
+    }
+  }
+}
+
+export default SiteTopFormCollection;

package/src/models/site-top-form/site-top-form.model.js

@@ -0,0 +1,26 @@
+/*
+ * 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 BaseModel from '../base/base.model.js';
+
+/**
+ * SiteTopForm - A class representing a SiteTopForm entity.
+ * Provides methods to access and manipulate SiteTopForm-specific data.
+ *
+ * @class SiteTopForm
+ * @extends BaseModel
+ */
+class SiteTopForm extends BaseModel {
+  // add your custom methods or overrides here
+}
+
+export default SiteTopForm;

package/src/models/site-top-form/site-top-form.schema.js

@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+
+/* c8 ignore start */
+
+import { isInteger, isIsoDate, isValidUrl } from '@adobe/spacecat-shared-utils';
+
+import { validate as uuidValidate } from 'uuid';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import SiteTopForm from './site-top-form.model.js';
+import SiteTopFormCollection from './site-top-form.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(SiteTopForm, SiteTopFormCollection)
+  .addReference('belongs_to', 'Site', ['source', 'traffic'])
+  .addAttribute('siteId', {
+    type: 'string',
+    required: true,
+    validate: (value) => uuidValidate(value),
+  })
+  .addAttribute('url', {
+    type: 'string',
+    required: true,
+    validate: (value) => isValidUrl(value),
+  })
+  .addAttribute('formSource', {
+    type: 'string',
+    required: true,
+  })
+  .addAttribute('traffic', {
+    type: 'number',
+    required: false,
+    default: 0,
+    validate: (value) => isInteger(value),
+  })
+  .addAttribute('source', {
+    type: 'string',
+    required: true,
+  })
+  .addAttribute('importedAt', {
+    type: 'string',
+    required: true,
+    default: () => new Date().toISOString(),
+    validate: (value) => isIsoDate(value),
+  })
+  .addIndex(
+    { composite: ['url', 'formSource'] },
+    { composite: ['traffic'] },
+  );
+
+export default schema.build();