@adobe/spacecat-shared-data-access 4.0.0 → 4.1.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v4.1.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.1.0...@adobe/spacecat-shared-data-access-v4.1.1) (2026-07-06)
+
+### Bug Fixes
+
+* add new phases to IVE states ([#1768](https://github.com/adobe/spacecat-shared/issues/1768)) ([91c5182](https://github.com/adobe/spacecat-shared/commit/91c5182cfbba5d9d9fcb7a53e45598bbccf93e19))
+
+## [@adobe/spacecat-shared-data-access-v4.1.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.0.0...@adobe/spacecat-shared-data-access-v4.1.0) (2026-07-06)
+
+### Features
+
+* **data-access:** mapping-table site_id/deletedAt + Brand workspace-id rename ([#1763](https://github.com/adobe/spacecat-shared/issues/1763)) ([c91faf0](https://github.com/adobe/spacecat-shared/commit/c91faf009b2643c5451a9912a627426ce97be0d1)), closes [#765](https://github.com/adobe/spacecat-shared/issues/765) [adobe/mysticat-data-service#765](https://github.com/adobe/mysticat-data-service/issues/765) [adobe/spacecat-api-service#2739](https://github.com/adobe/spacecat-api-service/issues/2739) [#765](https://github.com/adobe/spacecat-shared/issues/765) [mysticat-data-service#765](https://github.com/adobe/mysticat-data-service/issues/765)
+
 ## [@adobe/spacecat-shared-data-access-v4.0.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.81.0...@adobe/spacecat-shared-data-access-v4.0.0) (2026-07-03)
 
 ### ⚠ BREAKING CHANGES

package/package.json

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

package/src/models/brand/brand.model.js

@@ -39,6 +39,23 @@ class Brand extends BaseModel {
    * `pending`; customer offboard writes `deleted`.
    */
   static STATUSES = Object.freeze(['pending', 'active', 'deleted', 'ignored']);
+
+  /**
+   * Deprecated BC-compat setter. `semrushWorkspaceId` is `readOnly: true` in
+   * the schema (mirrored by the mysticat-data-service sync trigger), so no
+   * setter is auto-generated for it — this manual method exists purely so an
+   * existing external caller of `setSemrushWorkspaceId` does not get a
+   * semver-breaking runtime error on upgrade. Delegates to the real
+   * write-of-record attribute. Remove once every direct caller has migrated
+   * to `setSemrushSubWorkspaceId` (see brand.schema.js).
+   *
+   * @deprecated Use setSemrushSubWorkspaceId instead.
+   * @param {string|null} value
+   * @returns {Brand}
+   */
+  setSemrushWorkspaceId(value) {
+    return this.setSemrushSubWorkspaceId(value);
+  }
 }
 
 export default Brand;

package/src/models/brand/brand.schema.js

@@ -35,14 +35,31 @@ const schema = new SchemaBuilder(Brand, BrandCollection)
     type: Brand.STATUSES,
     validate: (value) => value == null || Brand.STATUSES.includes(value),
   })
+  // DEPRECATED (serenity-docs brand-semrush-mapping-maintenance.md §10
+  // rename, write-of-record cutover): read-only mirror of
+  // semrushSubWorkspaceId below, maintained entirely by the
+  // mysticat-data-service brands_sync_semrush_workspace_id trigger
+  // (migration 20260702094229). No schema-generated setter — app code must
+  // write semrushSubWorkspaceId instead. brand.model.js still defines a
+  // manual, deprecated setSemrushWorkspaceId() that delegates to
+  // setSemrushSubWorkspaceId(), so an existing external caller of the old
+  // setter is not broken (a bare readOnly flip here would be a semver-breaking
+  // removal for any @adobe/spacecat-shared-data-access consumer). Will be
+  // retired (attribute, column, and trigger) once every direct external
+  // reader has migrated.
+  .addAttribute('semrushWorkspaceId', {
+    type: 'string',
+    readOnly: true,
+  })
   // Brand → Semrush sub-workspace. Nullable (NULL = no sub-workspace
   // connected). Same minimum guard as organizations.semrushWorkspaceId: the
   // shared `hasText` rejects the empty string (and non-strings) while letting
   // null/undefined short-circuit. Note hasText does NOT trim, so a
   // whitespace-only value would pass — acceptable here because this column is
   // only ever written by the activate flow with a real Semrush workspace UUID,
-  // never user input.
-  .addAttribute('semrushWorkspaceId', {
+  // never user input. This is now the write-of-record (see semrushWorkspaceId
+  // above for the deprecated BC mirror).
+  .addAttribute('semrushSubWorkspaceId', {
     type: 'string',
     validate: (value) => value == null || hasText(value),
   })
@@ -55,9 +72,15 @@ const schema = new SchemaBuilder(Brand, BrandCollection)
     type: 'any',
     validate: (value) => value == null || (typeof value === 'object' && !Array.isArray(value)),
   })
-  // Uniqueness is enforced at the DB level via the UNIQUE constraint on
-  // brands.semrush_workspace_id (mysticat-data-service migration
+  // Uniqueness is enforced at the DB level via the UNIQUE constraint on the
+  // deprecated brands.semrush_workspace_id (mysticat-data-service migration
   // 20260615102123), so findBySemrushWorkspaceId returns at most one row.
-  .addAllIndex(['semrushWorkspaceId']);
+  // Kept for BC lookups against the mirrored column; new code should prefer
+  // findBySemrushSubWorkspaceId below.
+  .addAllIndex(['semrushWorkspaceId'])
+  // Same uniqueness guarantee on the write-of-record column
+  // (brands.semrush_sub_workspace_id, mysticat-data-service migration
+  // 20260702091920).
+  .addAllIndex(['semrushSubWorkspaceId']);
 
 export default schema.build();

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

@@ -17,13 +17,24 @@ import type {
 export interface Brand extends BaseModel {
   getName(): string;
   getStatus(): string;
+  // Deprecated BC mirror (brands.semrush_workspace_id), maintained by the
+  // mysticat-data-service sync trigger. No schema-generated setter; the
+  // deprecated setSemrushWorkspaceId below is a manual delegate defined in
+  // brand.model.js, kept only for backward compatibility. Use
+  // getSemrushSubWorkspaceId/setSemrushSubWorkspaceId instead. See
+  // brand.schema.js.
   getSemrushWorkspaceId(): string | null;
+  getSemrushSubWorkspaceId(): string | null;
   setName(value: string): Brand;
   setStatus(value: string): Brand;
+  setSemrushSubWorkspaceId(value: string | null): Brand;
+  /** @deprecated Use setSemrushSubWorkspaceId instead. */
   setSemrushWorkspaceId(value: string | null): Brand;
 }
 
 export interface BrandCollection extends BaseCollection<Brand> {
   allBySemrushWorkspaceId(semrushWorkspaceId: string): Promise<Brand[]>;
   findBySemrushWorkspaceId(semrushWorkspaceId: string): Promise<Brand | null>;
+  allBySemrushSubWorkspaceId(semrushSubWorkspaceId: string): Promise<Brand[]>;
+  findBySemrushSubWorkspaceId(semrushSubWorkspaceId: string): Promise<Brand | null>;
 }

package/src/models/brand-semrush-project/brand-semrush-project.collection.js

@@ -10,11 +10,31 @@
  * governing permissions and limitations under the License.
  */
 
+import { isValidUUID } from '@adobe/spacecat-shared-utils';
+
 import BaseCollection from '../base/base.collection.js';
+import DataAccessError from '../../errors/data-access.error.js';
+import { DEFAULT_PAGE_SIZE } from '../../util/postgrest.utils.js';
+
+const BRAND_FK = 'brand_to_semrush_projects_brand_id_fkey';
+
+// Safety cutoff for #fetchOrgRows' pagination loop. The per-FK base-collection
+// queries this package generates elsewhere are naturally bounded (one brand's
+// rows); this org-level fan-out is not, so an unexpectedly large org (or a
+// runaway loop from an accessor bug) is capped rather than growing memory
+// unbounded. Not expected to be hit in practice — see the truncation log.
+const MAX_ORG_ROWS = 50_000;
 
 /**
  * BrandSemrushProjectCollection - collection of BrandSemrushProject rows.
  *
+ * Tombstone contract: only `allByOrganizationId` filters `deletedAt` by
+ * default. Every other accessor here (including the auto-generated
+ * `allByBrandId` / `findBySemrushProjectId`) returns tombstoned rows
+ * alongside live ones — there is no package-level soft-delete scope. Callers
+ * that need only live rows must filter explicitly, or use the sanctioned
+ * accessor. See serenity-docs brand-semrush-mapping-maintenance.md §7.2.
+ *
  * @class BrandSemrushProjectCollection
  * @extends BaseCollection
  */
@@ -26,6 +46,10 @@ class BrandSemrushProjectCollection extends BaseCollection {
    * null. Used by spacecat-api-service POST /v2/orgs/.../serenity/markets to
    * 409 on a duplicate slice before calling the upstream.
    *
+   * Returns tombstoned rows too (see class doc) — flat mode never tombstones,
+   * so this only matters for sub-workspace callers, which do not use this
+   * method today.
+   *
    * @param {string} brandId
    * @param {number} geoTargetId Google Ads Geo Target ID.
    * @param {string} languageCode BCP-47 primary subtag.
@@ -34,6 +58,122 @@ class BrandSemrushProjectCollection extends BaseCollection {
   async findBySlice(brandId, geoTargetId, languageCode) {
     return this.findByIndexKeys({ brandId, geoTargetId, languageCode });
   }
+
+  /**
+   * Returns identity rows (brand/project/slice/site, plus the embedded
+   * sub-workspace id) for every mapping row under the given organization, via
+   * a single PostgREST embedded-join query (INNER JOIN on brand_id FK) — one
+   * round trip, no per-brand fan-out. This is the sanctioned read path for
+   * cross-team consumers (spec §7.2): it deliberately returns plain frozen
+   * identity DTOs, not model instances, so a consumer cannot update/remove
+   * through it or reach beyond the projected columns.
+   *
+   * Tombstones are filtered by default (`deletedAt IS NULL`) — pass
+   * `{ includeDeleted: true }` to see them (e.g. for history/debugging).
+   *
+   * @param {string} organizationId - UUID of the organization.
+   * @param {object} [options]
+   * @param {boolean} [options.includeDeleted=false]
+   * @returns {Promise<Array<{
+   *   brandId: string,
+   *   semrushProjectId: string,
+   *   geoTargetId: number,
+   *   languageCode: string,
+   *   siteId: string|null,
+   *   organizationId: string|null,
+   *   semrushSubWorkspaceId: string|null,
+   * }>>}
+   */
+  async allByOrganizationId(organizationId, { includeDeleted = false } = {}) {
+    if (!organizationId || !isValidUUID(organizationId)) {
+      throw new DataAccessError(
+        'organizationId is required and must be a valid UUID',
+        { entityName: this.entityName, tableName: this.tableName },
+      );
+    }
+
+    // `!inner` is explicit rather than relying on the implicit INNER-JOIN-on-
+    // embedded-filter behavior added in PostgREST v11 — on an older server the
+    // same `.eq('brands.organization_id', ...)` filter alone is a LEFT JOIN,
+    // returning every mapping row with `brands: null` for non-matching
+    // organizations instead of excluding them.
+    // eslint-disable-next-line max-len
+    const select = `brand_id, semrush_project_id, semrush_location_id, language, site_id, brands!${BRAND_FK}!inner(organization_id, semrush_sub_workspace_id)`;
+    let query = this.postgrestService.from(this.tableName).select(select)
+      .eq('brands.organization_id', organizationId);
+    if (!includeDeleted) {
+      query = query.is('deleted_at', null);
+    }
+
+    return this.#fetchOrgRows(query);
+  }
+
+  /**
+   * Offset-paginates `query` and returns plain frozen identity DTOs.
+   *
+   * This deliberately rolls its own offset loop instead of reusing the
+   * cursor-based helper in `postgrest.utils.js`: that helper hydrates model
+   * instances through the base collection, whereas this accessor's contract
+   * (spec §7.2) is to return frozen, read-only identity DTOs from an
+   * embedded-join projection. Offset pagination over a fully-ordered query is
+   * sufficient here and keeps the projected columns / freeze in one place.
+   *
+   * @param {object} query - PostgREST query builder
+   * @returns {Promise<Array<object>>}
+   * @private
+   */
+  async #fetchOrgRows(query) {
+    const allResults = [];
+    let offset = 0;
+    let keepGoing = true;
+    // Secondary sort on semrush_project_id: brand_id alone does not give a
+    // stable page boundary when one brand has many projects (rows within a
+    // brand could otherwise straddle a page split in a different order on
+    // each call). semrush_project_id is unique per row, so this fully
+    // determines row order.
+    const orderedQuery = query.order('brand_id').order('semrush_project_id');
+
+    while (keepGoing) {
+      // `.range()` returns a NEW builder rather than mutating in place (true
+      // for the current supabase-js / postgrest-js lineage), so re-deriving
+      // each page from the shared `orderedQuery` is safe. A client fork that
+      // mutated in place would break this loop.
+      // eslint-disable-next-line no-await-in-loop
+      const { data, error } = await orderedQuery.range(offset, offset + DEFAULT_PAGE_SIZE - 1);
+
+      if (error) {
+        this.log.error(`[${this.entityName}] Failed to query mapping rows by organization - ${error.message}`, error);
+        throw new DataAccessError(
+          'Failed to query mapping rows by organization',
+          { entityName: this.entityName, tableName: this.tableName },
+          error,
+        );
+      }
+
+      if (!data || data.length === 0) {
+        keepGoing = false;
+      } else {
+        allResults.push(...data);
+        offset += DEFAULT_PAGE_SIZE;
+        if (allResults.length >= MAX_ORG_ROWS) {
+          this.log.warn(`[${this.entityName}] allByOrganizationId truncated at ${MAX_ORG_ROWS} rows`);
+          keepGoing = false;
+        } else {
+          keepGoing = data.length >= DEFAULT_PAGE_SIZE;
+        }
+      }
+    }
+
+    return allResults.map((row) => Object.freeze({
+      brandId: row.brand_id,
+      semrushProjectId: row.semrush_project_id,
+      geoTargetId: row.semrush_location_id,
+      languageCode: row.language,
+      siteId: row.site_id ?? null,
+      organizationId: row.brands?.organization_id ?? null,
+      semrushSubWorkspaceId: row.brands?.semrush_sub_workspace_id ?? null,
+    }));
+  }
 }
 
 export default BrandSemrushProjectCollection;

package/src/models/brand-semrush-project/brand-semrush-project.schema.js

@@ -10,7 +10,9 @@
  * governing permissions and limitations under the License.
  */
 
-import { hasText, isValidUUID } from '@adobe/spacecat-shared-utils';
+import {
+  hasText, isIsoDate, isValidUUID,
+} from '@adobe/spacecat-shared-utils';
 
 import SchemaBuilder from '../base/schema.builder.js';
 import BrandSemrushProject from './brand-semrush-project.model.js';
@@ -68,6 +70,25 @@ const schema = new SchemaBuilder(BrandSemrushProject, BrandSemrushProjectCollect
     validate: (value) => hasText(value) && LANGUAGE_TAG_REGEX.test(value),
     postgrestField: 'language',
   })
-  .addAllIndex(['semrushProjectId']);
+  .addAllIndex(['semrushProjectId'])
+  // Market-mirror Site for this project. Nullable — the mirror is created
+  // best-effort and may lag the row. Not unique: mirror Sites are per
+  // (brand, domain), so many projects of a brand sharing a domain share one
+  // Site. See serenity-docs brand-semrush-mapping-maintenance.md §5.1.
+  .addAttribute('siteId', {
+    type: 'string',
+    validate: (value) => !value || isValidUUID(value),
+  })
+  // Soft-delete tombstone. NULL = live (project exists in the child
+  // workspace, draft or live). Set = the project was deleted upstream —
+  // Semrush data does not survive deletion, so this is the only remaining
+  // record it existed. Mirrors the ApiKey.deletedAt precedent
+  // (api-key.schema.js) — no package-level soft-delete scope exists, so
+  // every accessor except `allByOrganizationId` (collection.js) returns
+  // tombstones; callers that need only live rows must filter explicitly.
+  .addAttribute('deletedAt', {
+    type: 'string',
+    validate: (value) => !value || isIsoDate(value),
+  });
 
 export default schema.build();

package/src/models/brand-semrush-project/index.d.ts

@@ -25,9 +25,27 @@ export interface BrandSemrushProject extends BaseModel {
   getSemrushProjectId(): string;
   getGeoTargetId(): number;
   getLanguageCode(): string;
+  getSiteId(): string | undefined;
+  getDeletedAt(): string | undefined;
   setSemrushProjectId(value: string): BrandSemrushProject;
   setGeoTargetId(value: number): BrandSemrushProject;
   setLanguageCode(value: string): BrandSemrushProject;
+  setSiteId(value: string): BrandSemrushProject;
+  setDeletedAt(value: string): BrandSemrushProject;
+}
+
+export interface BrandSemrushProjectOrgRow {
+  brandId: string;
+  semrushProjectId: string;
+  geoTargetId: number;
+  languageCode: string;
+  siteId: string | null;
+  // Expected non-null under the select's `!inner` join (which excludes
+  // non-matching parents), but kept nullable to match the defensive runtime
+  // mapping (`row.brands?.organization_id ?? null`) — see
+  // brand-semrush-project.collection.js's #fetchOrgRows.
+  organizationId: string | null;
+  semrushSubWorkspaceId: string | null;
 }
 
 export interface BrandSemrushProjectCollection extends
@@ -41,4 +59,8 @@ export interface BrandSemrushProjectCollection extends
     geoTargetId: number,
     languageCode: string,
   ): Promise<BrandSemrushProject | null>;
+  allByOrganizationId(
+    organizationId: string,
+    options?: { includeDeleted?: boolean },
+  ): Promise<BrandSemrushProjectOrgRow[]>;
 }

package/src/models/geo-experiment/geo-experiment.model.js

@@ -29,6 +29,9 @@ class GeoExperiment extends BaseModel {
   };
 
   static PHASES = {
+    INITIATED: 'initiated',
+    PROMPT_GENERATION_STARTED: 'prompt_generation_started',
+    PROMPT_GENERATION_COMPLETED: 'prompt_generation_completed',
     PRE_ANALYSIS_STARTED: 'pre_analysis_started',
     PRE_ANALYSIS_DONE: 'pre_analysis_done',
     DEPLOYMENT_STARTED: 'deployment_started',