@adobe/spacecat-shared-data-access 3.81.0 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [@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
+
+* **data-access:** drop startedAt/result/error from Preflight schema (SITES-47254) (#1740)
+
+### Features
+
+* **data-access:** drop startedAt/result/error from Preflight schema (SITES-47254) ([#1740](https://github.com/adobe/spacecat-shared/issues/1740)) ([5b728bb](https://github.com/adobe/spacecat-shared/commit/5b728bb623060289221e744088b9762a8acfe519)), closes [#2713](https://github.com/adobe/spacecat-shared/issues/2713) [#2713](https://github.com/adobe/spacecat-shared/issues/2713) [post-#2713](https://github.com/adobe/post-/issues/2713)
+
 ## [@adobe/spacecat-shared-data-access-v3.81.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.80.0...@adobe/spacecat-shared-data-access-v3.81.0) (2026-07-02)
 
 ### Features

package/package.json

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

package/src/models/async-job/index.d.ts

@@ -12,6 +12,13 @@
 
 import type { BaseCollection, BaseModel } from '../base';
 
+// Note on nullable return types: `postgrest.utils.js::normalizeModelValue()`
+// maps DB NULL → JS `undefined` (the key is skipped on `this.record`
+// entirely), so auto-generated getters return `T | undefined` — never
+// `T | null` — for nullable columns. Callers checking `=== null` on these
+// will silently miss the unfinished-job branch. Existing declarations
+// that read `... | null` predate this PR; the lifecycle additions below
+// match the runtime contract.
 export interface AsyncJob extends BaseModel {
     getStatus(): string;
     getResultLocation(): string;
@@ -20,6 +27,8 @@ export interface AsyncJob extends BaseModel {
     getError(): { code: string; message: string; details?: object } | null;
     getMetadata(): object | null;
     getRecordExpiressAt(): number;
+    getStartedAt(): string | undefined;
+    getEndedAt(): string | undefined;
     setStatus(status: string): void;
     setResultLocation(location: string): void;
     setResultType(type: string): void;
@@ -27,6 +36,8 @@ export interface AsyncJob extends BaseModel {
     setError(error: { code: string; message: string; details?: object }): void;
     setMetadata(metadata: object): void;
     setExpiresAt(expiresAt: number): void;
+    setStartedAt(startedAt: string): void;
+    setEndedAt(endedAt: string): void;
 }
 
 export interface AsyncJobCollection extends BaseCollection<AsyncJob> {

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/preflight/index.d.ts

@@ -12,6 +12,7 @@
 
 import type { AsyncJob, BaseCollection, BaseModel, Site } from '../index.js';
 
+// SITES-47254: startedAt/result/error live on AsyncJob — fetch via getAsyncJob().
 export interface Preflight extends BaseModel {
     getSiteId(): string;
     getSite(): Promise<Site>;
@@ -20,18 +21,14 @@ export interface Preflight extends BaseModel {
     getUrl(): string;
     getStatus(): string;
     getCreatedBy(): { email: string; displayName?: string };
-    getStartedAt(): string | null;
-    getEndedAt(): string | null;
-    getResult(): object | null;
-    getError(): { code: string; message: string } | null;
+    // `string | undefined` (not `| null`) because normalizeModelValue maps
+    // DB NULL → undefined on read — see AsyncJob/index.d.ts header.
+    getEndedAt(): string | undefined;
 
     setUrl(url: string): Preflight;
     setStatus(status: 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'CANCELLED'): Preflight;
     setCreatedBy(createdBy: { email: string; displayName?: string }): Preflight;
-    setStartedAt(startedAt: string): Preflight;
     setEndedAt(endedAt: string): Preflight;
-    setResult(result: object): Preflight;
-    setError(error: { code: string; message: string }): Preflight;
 }
 
 export interface PreflightCollection extends BaseCollection<Preflight> {

package/src/models/preflight/preflight.schema.js

@@ -17,6 +17,11 @@ import SchemaBuilder from '../base/schema.builder.js';
 import Preflight from './preflight.model.js';
 import PreflightCollection from './preflight.collection.js';
 
+// SITES-47254: `startedAt`, `result`, and `error` live only on AsyncJob now —
+// the underlying preflights table no longer carries them. Consumers fetch the
+// joined AsyncJob (e.g., `await preflight.getAsyncJob()`) for lifecycle
+// internals; `status` and `endedAt` remain here as a denormalized cache the
+// projector keeps in sync.
 const schema = new SchemaBuilder(Preflight, PreflightCollection)
   .addReference('belongs_to', 'Site', [], { required: true })
   .addReference('belongs_to', 'AsyncJob', [], { required: true })
@@ -30,34 +35,22 @@ const schema = new SchemaBuilder(Preflight, PreflightCollection)
     required: true,
     default: Preflight.Status.IN_PROGRESS,
   })
-  // `createdBy` and `error` use type 'any' (matching neighbor `result`) because
-  // ElectroDB's `map` type requires a `properties` schema for every sub-key,
-  // and the validate function below already enforces the precise shape — a
-  // duplicate `properties` declaration adds nothing. Declaring `type: 'map'`
-  // here without `properties` was the original definition and throws
-  // `InvalidAttributeDefinition` at Service construction, blocking any
-  // downstream consumer that builds a v1 `new Service(EntityRegistry.getEntities())`
-  // (e.g. spacecat-api-service `fixes.test.js`).
+  // `createdBy` uses type 'any' because ElectroDB's `map` type requires a
+  // `properties` schema for every sub-key, and the validate function below
+  // already enforces the precise shape — a duplicate `properties` declaration
+  // adds nothing. Declaring `type: 'map'` here without `properties` was the
+  // original definition and throws `InvalidAttributeDefinition` at Service
+  // construction, blocking any downstream consumer that builds a v1
+  // `new Service(EntityRegistry.getEntities())` (e.g. spacecat-api-service
+  // `fixes.test.js`).
   .addAttribute('createdBy', {
     type: 'any',
     required: true,
     validate: (value) => isObject(value) && typeof value.email === 'string' && value.email.length > 0,
   })
-  .addAttribute('startedAt', {
-    type: 'string',
-    validate: (value) => !value || isIsoDate(value),
-  })
   .addAttribute('endedAt', {
     type: 'string',
     validate: (value) => !value || isIsoDate(value),
-  })
-  .addAttribute('result', {
-    type: 'any',
-    validate: (value) => !value || isObject(value),
-  })
-  .addAttribute('error', {
-    type: 'any',
-    validate: (value) => !value || (isObject(value) && typeof value.code === 'string' && value.code.length > 0 && typeof value.message === 'string' && value.message.length > 0),
   });
 
 export default schema.build();