@adobe/spacecat-shared-data-access 3.23.0 → 3.25.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v3.25.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.24.0...@adobe/spacecat-shared-data-access-v3.25.0) (2026-03-19)
+
+### Features
+
+* cross-org delegation entity models and AuthInfo extensions ([#1448](https://github.com/adobe/spacecat-shared/issues/1448)) ([b0cb091](https://github.com/adobe/spacecat-shared/commit/b0cb091432f15eb304e20263c0a18ec794d93bb9))
+
+## [@adobe/spacecat-shared-data-access-v3.24.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.23.0...@adobe/spacecat-shared-data-access-v3.24.0) (2026-03-19)
+
+### Features
+
+* SITES-40623 - token system in Spacecat ([#1414](https://github.com/adobe/spacecat-shared/issues/1414)) ([9c540ba](https://github.com/adobe/spacecat-shared/commit/9c540babf47984e15737bde509b54df9b5233c54))
+
 ## [@adobe/spacecat-shared-data-access-v3.23.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.22.0...@adobe/spacecat-shared-data-access-v3.23.0) (2026-03-18)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.23.0",
+  "version": "3.25.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@adobe/fetch": "^4.2.3",
-    "@adobe/spacecat-shared-utils": "1.101.0",
+    "@adobe/spacecat-shared-utils": "1.105.0",
     "@supabase/postgrest-js": "2.99.1",
     "@aws-sdk/client-s3": "^3.940.0",
     "@types/joi": "17.2.3",

package/src/models/access-grant-log/access-grant-log.collection.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 BaseCollection from '../base/base.collection.js';
+
+/**
+ * AccessGrantLogCollection - Collection of immutable audit log entries.
+ * Supports creation and querying only (no update/delete at the app layer).
+ *
+ * @class AccessGrantLogCollection
+ * @extends BaseCollection
+ */
+class AccessGrantLogCollection extends BaseCollection {
+  static COLLECTION_NAME = 'AccessGrantLogCollection';
+}
+
+export default AccessGrantLogCollection;

package/src/models/access-grant-log/access-grant-log.model.js

@@ -0,0 +1,31 @@
+/*
+ * 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';
+
+/**
+ * AccessGrantLog - Immutable audit log entry for cross-org delegation grant/revoke actions.
+ * site_id and organization_id are TEXT (not FK) — values survive entity deletion.
+ *
+ * @class AccessGrantLog
+ * @extends BaseModel
+ */
+class AccessGrantLog extends BaseModel {
+  static ENTITY_NAME = 'AccessGrantLog';
+
+  static GRANT_ACTIONS = {
+    GRANT: 'grant',
+    REVOKE: 'revoke',
+  };
+}
+
+export default AccessGrantLog;

package/src/models/access-grant-log/access-grant-log.schema.js

@@ -0,0 +1,62 @@
+/*
+ * 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 { isValidUUID } from '@adobe/spacecat-shared-utils';
+import { Entitlement } from '../entitlement/index.js';
+import SiteImsOrgAccess from '../site-ims-org-access/site-ims-org-access.model.js';
+import SchemaBuilder from '../base/schema.builder.js';
+import AccessGrantLog from './access-grant-log.model.js';
+import AccessGrantLogCollection from './access-grant-log.collection.js';
+
+const PERFORMED_BY_PATTERN = /^(ims:\S+|slack:\S+|system)$/;
+
+const schema = new SchemaBuilder(AccessGrantLog, AccessGrantLogCollection)
+  .allowUpdates(false)
+  .allowRemove(false)
+  // siteId, organizationId, and targetOrganizationId are plain addAttribute (not belongs_to)
+  // because the DB columns are TEXT, not FK. Audit logs must preserve UUIDs after entity deletion.
+  .addAttribute('siteId', {
+    type: 'string',
+    required: true,
+    validate: (v) => isValidUUID(v),
+  })
+  .addAttribute('organizationId', {
+    type: 'string',
+    required: true,
+    validate: (v) => isValidUUID(v),
+  })
+  .addAttribute('targetOrganizationId', {
+    type: 'string',
+    required: true,
+    validate: (v) => isValidUUID(v),
+  })
+  .addAttribute('productCode', {
+    type: Object.values(Entitlement.PRODUCT_CODES),
+    required: true,
+  })
+  .addAttribute('action', {
+    type: Object.values(AccessGrantLog.GRANT_ACTIONS),
+    required: true,
+  })
+  .addAttribute('role', {
+    type: Object.values(SiteImsOrgAccess.DELEGATION_ROLES),
+    required: true,
+  })
+  .addAttribute('performedBy', {
+    type: 'string',
+    required: true,
+    validate: (v) => PERFORMED_BY_PATTERN.test(v),
+  })
+  .addAllIndex(['organizationId'])
+  .addAllIndex(['siteId']);
+
+export default schema.build();

package/src/models/access-grant-log/index.d.ts

@@ -0,0 +1,37 @@
+/*
+ * 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, EntitlementProductCode,
+} from '../index';
+
+export type AccessGrantAction = 'grant' | 'revoke';
+export type AccessGrantRole = 'collaborator' | 'agency' | 'viewer';
+
+export interface AccessGrantLog extends BaseModel {
+  getSiteId(): string;
+  getOrganizationId(): string;
+  getTargetOrganizationId(): string;
+  getProductCode(): EntitlementProductCode;
+  getAction(): AccessGrantAction;
+  getRole(): AccessGrantRole;
+  getPerformedBy(): string;
+}
+
+export interface AccessGrantLogCollection extends
+    BaseCollection<AccessGrantLog> {
+  allByOrganizationId(organizationId: string): Promise<AccessGrantLog[]>;
+  allBySiteId(siteId: string): Promise<AccessGrantLog[]>;
+
+  findByOrganizationId(organizationId: string): Promise<AccessGrantLog | null>;
+  findBySiteId(siteId: string): Promise<AccessGrantLog | null>;
+}

package/src/models/access-grant-log/index.js

@@ -0,0 +1,15 @@
+/*
+ * 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 { default as AccessGrantLog } from './access-grant-log.model.js';
+export { default as AccessGrantLogCollection } from './access-grant-log.collection.js';
+export { default as AccessGrantLogSchema } from './access-grant-log.schema.js';

package/src/models/base/base.model.js

@@ -176,6 +176,20 @@ class BaseModel {
               }
 
               return null;
+            })
+            .catch((error) => {
+              // Gracefully skip dependents whose table/column is absent from the PostgREST
+              // schema cache (e.g. when the legacy test DB pre-dates this table). All other
+              // errors are re-thrown so they still surface as removal failures.
+              const msg = error?.cause?.message || error?.message || '';
+              if (
+                msg.includes('Could not find the')
+                && (msg.includes('table') || msg.includes('column'))
+                && msg.includes('schema cache')
+              ) {
+                return null;
+              }
+              throw error;
             }),
         );
       });

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

@@ -38,14 +38,18 @@ import SiteEnrollmentCollection from '../site-enrollment/site-enrollment.collect
 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 SuggestionGrantCollection from '../suggestion-grant/suggestion-grant.collection.js';
 import PageIntentCollection from '../page-intent/page-intent.collection.js';
 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 TokenCollection from '../token/token.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';
+import AccessGrantLogCollection from '../access-grant-log/access-grant-log.collection.js';
+import SiteImsOrgAccessCollection from '../site-ims-org-access/site-ims-org-access.collection.js';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
 import AsyncJobSchema from '../async-job/async-job.schema.js';
@@ -71,14 +75,18 @@ import SiteEnrollmentSchema from '../site-enrollment/site-enrollment.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 SuggestionGrantSchema from '../suggestion-grant/suggestion-grant.schema.js';
 import PageIntentSchema from '../page-intent/page-intent.schema.js';
 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 TokenSchema from '../token/token.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';
+import AccessGrantLogSchema from '../access-grant-log/access-grant-log.schema.js';
+import SiteImsOrgAccessSchema from '../site-ims-org-access/site-ims-org-access.schema.js';
 
 /**
  * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
@@ -199,14 +207,18 @@ EntityRegistry.registerEntity(SiteEnrollmentSchema, SiteEnrollmentCollection);
 EntityRegistry.registerEntity(SiteTopFormSchema, SiteTopFormCollection);
 EntityRegistry.registerEntity(SiteTopPageSchema, SiteTopPageCollection);
 EntityRegistry.registerEntity(SuggestionSchema, SuggestionCollection);
+EntityRegistry.registerEntity(SuggestionGrantSchema, SuggestionGrantCollection);
 EntityRegistry.registerEntity(PageIntentSchema, PageIntentCollection);
 EntityRegistry.registerEntity(ReportSchema, ReportCollection);
 EntityRegistry.registerEntity(TrialUserSchema, TrialUserCollection);
 EntityRegistry.registerEntity(TrialUserActivitySchema, TrialUserActivityCollection);
+EntityRegistry.registerEntity(TokenSchema, TokenCollection);
 EntityRegistry.registerEntity(PageCitabilitySchema, PageCitabilityCollection);
 EntityRegistry.registerEntity(PlgOnboardingSchema, PlgOnboardingCollection);
 EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollection);
 EntityRegistry.registerEntity(SentimentTopicSchema, SentimentTopicCollection);
+EntityRegistry.registerEntity(AccessGrantLogSchema, AccessGrantLogCollection);
+EntityRegistry.registerEntity(SiteImsOrgAccessSchema, SiteImsOrgAccessCollection);
 EntityRegistry.defaultEntities = { ...EntityRegistry.entities };
 
 export default EntityRegistry;

package/src/models/index.d.ts

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+export type * from './access-grant-log';
 export type * from './api-key';
 export type * from './async-job';
 export type * from './audit';
@@ -39,6 +40,7 @@ export type * from './sentiment-topic';
 export type * from './site';
 export type * from './site-candidate';
 export type * from './site-enrollment';
+export type * from './site-ims-org-access';
 export type * from './site-top-form';
 export type * from './site-top-page';
 export type * from './suggestion';

package/src/models/index.js

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+export * from './access-grant-log/index.js';
 export * from './api-key/index.js';
 export * from './async-job/index.js';
 export * from './audit/index.js';
@@ -32,14 +33,17 @@ export * from './scrape-job/index.js';
 export * from './scrape-url/index.js';
 export * from './site-candidate/index.js';
 export * from './site-enrollment/index.js';
+export * from './site-ims-org-access/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';
+export * from './suggestion-grant/index.js';
 export * from './page-intent/index.js';
 export * from './report/index.js';
 export * from './trial-user/index.js';
 export * from './trial-user-activity/index.js';
+export * from './token/index.js';
 export * from './page-citability/index.js';
 export * from './plg-onboarding/index.js';
 export * from './sentiment-guideline/index.js';

package/src/models/sentiment-topic/index.d.ts

@@ -16,18 +16,10 @@ import type { BaseCollection, BaseModel, Site } from '../index';
  * SentimentTopic entity representing a topic for sentiment analysis.
  * Composite primary key: siteId (PK) + topicId (SK)
  */
-export interface SentimentTopicUrl {
-  url: string;
-  timesCited: number;
-  category?: string;
-  subPrompts?: string[];
-}
-
 export interface SentimentTopic extends BaseModel {
   getTopicId(): string;
   getName(): string;
   getDescription(): string | undefined;
-  getUrls(): SentimentTopicUrl[];
   getEnabled(): boolean;
   getCreatedAt(): string;
   getCreatedBy(): string;
@@ -38,7 +30,6 @@ export interface SentimentTopic extends BaseModel {
 
   setName(name: string): SentimentTopic;
   setDescription(description: string): SentimentTopic;
-  setUrls(urls: SentimentTopicUrl[]): SentimentTopic;
   setEnabled(enabled: boolean): SentimentTopic;
   setUpdatedBy(updatedBy: string): SentimentTopic;
 }

package/src/models/sentiment-topic/sentiment-topic.schema.js

@@ -55,25 +55,6 @@ const schema = new SchemaBuilder(SentimentTopic, SentimentTopicCollection)
     type: 'string',
     required: false,
   })
-  .addAttribute('urls', {
-    type: 'list',
-    required: false,
-    default: [],
-    items: {
-      type: 'map',
-      properties: {
-        url: { type: 'string', required: true },
-        timesCited: { type: 'number', required: true },
-        category: { type: 'string', required: false },
-        subPrompts: {
-          type: 'list',
-          items: { type: 'string' },
-          required: false,
-          default: [],
-        },
-      },
-    },
-  })
   .addAttribute('enabled', {
     type: 'boolean',
     required: true,

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

@@ -43,6 +43,11 @@ const schema = new SchemaBuilder(Site, SiteCollection)
   .addReference('has_many', 'Opportunities')
   .addReference('has_many', 'SiteCandidates')
   .addReference('has_many', 'SiteEnrollments')
+  // TODO(Phase 2 audit gap): removeDependents silently removes all SiteImsOrgAccess records on
+  // site deletion without writing AccessGrantLog 'revoke' entries. Anyone auditing "why did
+  // agency X lose access to site Y" will find nothing in the log. Add a model-level pre-remove
+  // hook that writes revoke audit entries before this ships to production.
+  .addReference('has_many', 'SiteImsOrgAccesses', [], { removeDependents: true })
   .addReference('has_many', 'SiteTopForms')
   .addReference('has_many', 'SiteTopPages')
   .addReference('has_many', 'TrialUserActivities')

package/src/models/site-ims-org-access/index.d.ts

@@ -0,0 +1,65 @@
+/*
+ * 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, EntitlementProductCode, Organization, Site,
+} from '../index';
+
+export type SiteImsOrgAccessRole = 'collaborator' | 'agency' | 'viewer';
+
+export interface SiteImsOrgAccess extends BaseModel {
+  getSite(): Promise<Site>;
+  getOrganization(): Promise<Organization>;
+  getSiteId(): string;
+  /** organizationId is the delegate org receiving access (read-only, part of grant identity). */
+  getOrganizationId(): string;
+  /** targetOrganizationId is the site-owning org (read-only, part of grant identity). */
+  getTargetOrganizationId(): string;
+  /** productCode is read-only; changing scope requires a new grant. */
+  getProductCode(): EntitlementProductCode;
+  getRole(): SiteImsOrgAccessRole;
+  getGrantedBy(): string | null;
+  getExpiresAt(): string | null;
+  setRole(role: SiteImsOrgAccessRole): SiteImsOrgAccess;
+  setGrantedBy(grantedBy: string): SiteImsOrgAccess;
+  setExpiresAt(expiresAt: string): SiteImsOrgAccess;
+}
+
+export interface SiteImsOrgAccessGrantWithTarget {
+  grant: {
+    id: string;
+    siteId: string;
+    organizationId: string;
+    targetOrganizationId: string;
+    productCode: EntitlementProductCode;
+    role: SiteImsOrgAccessRole;
+    grantedBy: string | null;
+    expiresAt: string | null;
+  };
+  targetOrganization: {
+    id: string;
+    imsOrgId: string;
+  };
+}
+
+export interface SiteImsOrgAccessCollection extends
+    BaseCollection<SiteImsOrgAccess> {
+  allBySiteId(siteId: string): Promise<SiteImsOrgAccess[]>;
+  allByOrganizationId(organizationId: string): Promise<SiteImsOrgAccess[]>;
+  allByTargetOrganizationId(targetOrganizationId: string): Promise<SiteImsOrgAccess[]>;
+  allByOrganizationIdWithTargetOrganization(organizationId: string): Promise<SiteImsOrgAccessGrantWithTarget[]>;
+  allByOrganizationIdsWithTargetOrganization(organizationIds: string[]): Promise<SiteImsOrgAccessGrantWithTarget[]>;
+
+  findBySiteId(siteId: string): Promise<SiteImsOrgAccess | null>;
+  findByOrganizationId(organizationId: string): Promise<SiteImsOrgAccess | null>;
+  findByTargetOrganizationId(targetOrganizationId: string): Promise<SiteImsOrgAccess | null>;
+}

package/src/models/site-ims-org-access/index.js

@@ -0,0 +1,15 @@
+/*
+ * 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 { default as SiteImsOrgAccess } from './site-ims-org-access.model.js';
+export { default as SiteImsOrgAccessCollection } from './site-ims-org-access.collection.js';
+export { default as SiteImsOrgAccessSchema } from './site-ims-org-access.schema.js';