@adobe/spacecat-shared-data-access 2.35.0 → 2.36.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-data-access-v2.36.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.35.0...@adobe/spacecat-shared-data-access-v2.36.0) (2025-07-17)
+
+
+### Features
+
+* page intent entity ([#856](https://github.com/adobe/spacecat-shared/issues/856)) ([9e6f709](https://github.com/adobe/spacecat-shared/commit/9e6f70925dc8b9467081e2a1a1b23968a2089638))
+
 # [@adobe/spacecat-shared-data-access-v2.35.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.34.1...@adobe/spacecat-shared-data-access-v2.35.0) (2025-07-17)
 
 

package/package.json

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

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

@@ -31,6 +31,7 @@ import SiteCandidateCollection from '../site-candidate/site-candidate.collection
 import SiteCollection from '../site/site.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';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
 import AsyncJobSchema from '../async-job/async-job.schema.js';
@@ -50,6 +51,7 @@ import SiteSchema from '../site/site.schema.js';
 import SiteCandidateSchema from '../site-candidate/site-candidate.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';
 
 /**
  * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
@@ -150,5 +152,6 @@ EntityRegistry.registerEntity(SiteSchema, SiteCollection);
 EntityRegistry.registerEntity(SiteCandidateSchema, SiteCandidateCollection);
 EntityRegistry.registerEntity(SiteTopPageSchema, SiteTopPageCollection);
 EntityRegistry.registerEntity(SuggestionSchema, SuggestionCollection);
+EntityRegistry.registerEntity(PageIntentSchema, PageIntentCollection);
 
 export default EntityRegistry;

package/src/models/index.js

@@ -29,3 +29,4 @@ export * from './site-candidate/index.js';
 export * from './site-top-page/index.js';
 export * from './site/index.js';
 export * from './suggestion/index.js';
+export * from './page-intent/index.js';

package/src/models/page-intent/README.md

@@ -0,0 +1,65 @@
+# PageIntent Entity
+
+## Use Case
+
+The `PageIntent` entity captures the intent and topical classification of individual pages within a site.
+
+- **Page intent** (`INFORMATIONAL`, `NAVIGATIONAL`, `TRANSACTIONAL`, `COMMERCIAL`) helps determine how users interact with each page.
+- **Topic** (arbitrary string, changes per site, like `firefly`, `photoshop`, `express`) groups pages into thematic buckets.
+
+You can:
+1. **Record page metadata** as pages are discovered or crawled.
+2. **Query all pages** for a given site (`siteId`) to analyze overall content strategy.
+3. **Fetch a single page** by its unique URL to inspect or update its intent/topic.
+
+## PageIntent Schema Overview
+
+The `PageIntent` entity persists each page’s metadata. Key attributes include:
+
+- **`pageIntentId`** (UUID v4) – primary key for the record.
+- **`siteId`** (UUID v4) – foreign key to the Site entity.
+- **`url`** (string) – unique full URL of the page.
+- **`pageIntent`** (enum) – one of:
+    - `INFORMATIONAL`
+    - `NAVIGATIONAL`
+    - `TRANSACTIONAL`
+    - `COMMERCIAL`
+- **`topic`** (string) – arbitrary topic label for the page.
+- **`createdAt`, `updatedAt`** (ISO timestamp) – automatically maintained by ElectroDB.
+
+## Best Practices
+
+- **Uniqueness**: enforce URL uniqueness to avoid duplicate page records.
+- **Indexing**:
+    - Use `siteId` index to fetch all pages in a site quickly.
+    - Use unique `url` index to locate or upsert a specific page.
+- **Defaults & Validation**:
+    - Validate `url` format with a URL‐validator.
+    - Validate `siteId` as UUID v4.
+    - Default `updatedBy` to your automation user (e.g. `spacecat`).
+
+## Usage Example
+
+```js
+const { PageIntent } = dataAccess;
+
+// 1. Create a new page intent record
+const pi = await PageIntent.create({
+  siteId:     'b1ec63c4-87de-4500-bbc9-276039e4bc10',
+  url:        'https://www.adobe.com/firefly/overview.html',
+  pageIntent: 'INFORMATIONAL',
+  topic:      'firefly',
+});
+
+// 2. Query all pages for a site
+const all = await PageIntent.allBySiteId(pi.getSiteId());
+console.log(`Found ${all.length} pages for this site`);
+
+// 3. Fetch a single page by URL
+const single = await PageIntent.findByUrl(pi.getUrl());
+console.log(`Intent: ${single.getPageIntent()}, Topic: ${single.getTopic()}`);
+
+// 4. Update a page’s intent/topic
+single.setPageIntent('NAVIGATIONAL');
+single.setTopic('firefly-navigation');
+await single.save();

package/src/models/page-intent/index.d.ts

@@ -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.
+ */
+
+import type { BaseCollection, BaseModel, Site } from '../index.js';
+
+export interface PageIntent extends BaseModel {
+    getSiteId(): string;
+    getSite(): Promise<Site>;
+    getUrl(): string;
+    getPageIntent(): string;
+    getTopic(): string;
+
+    setSiteId(siteId: string): PageIntent;
+    setUrl(url: string): PageIntent;
+    setPageIntent(pageIntent: string): PageIntent;
+    setTopic(topic: string): PageIntent;
+}
+
+export interface PageIntentCollection extends BaseCollection<PageIntent> {
+    allBySiteId(siteId: string): Promise<PageIntent[]>;
+    findBySiteId(siteId: string): Promise<PageIntent | null>;
+
+    allByUrl(url: string): Promise<PageIntent[]>;
+    findByUrl(url: string): Promise<PageIntent | null>;
+}

package/src/models/page-intent/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 PageIntent from './page-intent.model.js';
+import PageIntentCollection from './page-intent.collection.js';
+
+export {
+  PageIntent,
+  PageIntentCollection,
+};

package/src/models/page-intent/page-intent.collection.js

@@ -0,0 +1,25 @@
+/*
+ * 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 BaseCollection from '../base/base.collection.js';
+
+/**
+ * PageIntentCollection - Manages PageIntent entities.
+ *
+ * @class PageIntentCollection
+ * @extends BaseCollection
+ */
+class PageIntentCollection extends BaseCollection {
+  // add custom collection-level methods here, if needed
+}
+
+export default PageIntentCollection;

package/src/models/page-intent/page-intent.model.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.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * PageIntent - Represents a page’s intent & topic within a site.
+ *
+ * @class PageIntent
+ * @extends BaseModel
+ */
+class PageIntent extends BaseModel {
+  static DEFAULT_UPDATED_BY = 'spacecat';
+
+  static PAGE_INTENTS = {
+    INFORMATIONAL: 'INFORMATIONAL',
+    NAVIGATIONAL: 'NAVIGATIONAL',
+    TRANSACTIONAL: 'TRANSACTIONAL',
+    COMMERCIAL: 'COMMERCIAL',
+  };
+
+  // add any custom methods or overrides here
+}
+
+export default PageIntent;

package/src/models/page-intent/page-intent.schema.js

@@ -0,0 +1,60 @@
+/*
+ * 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 { isValidUrl } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import PageIntent from './page-intent.model.js';
+import PageIntentCollection from './page-intent.collection.js';
+
+/*
+  Schema: https://electrodb.dev/en/modeling/schema/
+  Attributes: https://electrodb.dev/en/modeling/attributes/
+  Indexes: https://electrodb.dev/en/modeling/indexes/
+*/
+
+const schema = new SchemaBuilder(PageIntent, PageIntentCollection)
+  // link back to Site entity
+  .addReference('belongs_to', 'Site')
+
+  // page’s full URL (must be unique)
+  .addAttribute('url', {
+    type: 'string',
+    required: true,
+    validate: (value) => isValidUrl(value),
+  })
+
+  // one of INFORMATIONAL, NAVIGATIONAL, TRANSACTIONAL, COMMERCIAL
+  .addAttribute('pageIntent', {
+    type: Object.values(PageIntent.PAGE_INTENTS),
+    required: true,
+  })
+
+  // arbitrary topic string like “firefly” or “photoshop”
+  .addAttribute('topic', {
+    type: 'string',
+    required: true,
+  })
+
+  // optionally track who last updated
+  .addAttribute('updatedBy', {
+    type: 'string',
+    default: PageIntent.DEFAULT_UPDATED_BY,
+  })
+
+  // allow fetching the single record by its URL
+  .addIndex(
+    { composite: ['url'] },
+    { composite: ['updatedAt'] },
+  );
+
+export default schema.build();

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

@@ -43,6 +43,7 @@ const schema = new SchemaBuilder(Site, SiteCollection)
   .addReference('has_many', 'Opportunities')
   .addReference('has_many', 'SiteCandidates')
   .addReference('has_many', 'SiteTopPages')
+  .addReference('has_many', 'PageIntents')
   .addAttribute('baseURL', {
     type: 'string',
     required: true,