@adobe/spacecat-shared-data-access 4.20.0 → 4.21.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v4.21.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.21.0...@adobe/spacecat-shared-data-access-v4.21.1) (2026-08-14)
+
+### Bug Fixes
+
+* **data-access:** publish brand semrushWorkspaceId mirror removal (SITES-49202) ([#1880](https://github.com/adobe/spacecat-shared/issues/1880)) ([80a296a](https://github.com/adobe/spacecat-shared/commit/80a296af1b4f49ffa66aba80d677a5e6b42f3856)), closes [#1867](https://github.com/adobe/spacecat-shared/issues/1867) [#1867](https://github.com/adobe/spacecat-shared/issues/1867) [#1867](https://github.com/adobe/spacecat-shared/issues/1867)
+
+## [@adobe/spacecat-shared-data-access-v4.21.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.20.0...@adobe/spacecat-shared-data-access-v4.21.0) (2026-08-13)
+
+### Features
+
+* **data-access:** paginated sites query filtered by entitlement tier/productCode ([#1877](https://github.com/adobe/spacecat-shared/issues/1877)) ([00e5e59](https://github.com/adobe/spacecat-shared/commit/00e5e592f1d4990e1578deb8287e84f3f0d0cf1b))
+
 ## [@adobe/spacecat-shared-data-access-v4.20.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.19.0...@adobe/spacecat-shared-data-access-v4.20.0) (2026-08-12)
 
 ### Features

package/package.json

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

package/src/models/brand/brand.collection.js

@@ -15,8 +15,9 @@ import BaseCollection from '../base/base.collection.js';
 /**
  * BrandCollection - collection of Brand rows. `findById` (the brand UUID) is
  * the primary access path for serenity dual-mode resolution;
- * `findBySemrushWorkspaceId` (from the addAllIndex below) is used to repair a
- * pointer when a sub-workspace is found to have been deleted out-of-band.
+ * `findBySemrushSubWorkspaceId` (from the addAllIndex on the schema) is used to
+ * repair a pointer when a sub-workspace is found to have been deleted
+ * out-of-band.
  *
  * @class BrandCollection
  * @extends BaseCollection

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

@@ -16,17 +16,24 @@ import BaseModel from '../base/base.model.js';
  * Brand - an Adobe brand, stored in the `brands` table in mysticat-data-service
  * and served over PostgREST. Intentionally minimal: it surfaces only the fields
  * the serenity sub-workspace provisioning flows read/write
- * (`semrushWorkspaceId`, `status`, `name`). Brands are created and fully
+ * (`semrushSubWorkspaceId`, `status`, `name`). Brands are created and fully
  * managed elsewhere (Brandalf sync, onboarding); this entity is a read +
  * targeted-patch surface, not a create surface.
  *
- * `semrushWorkspaceId` is the dual-mode switch: NULL = the brand is not
+ * `semrushSubWorkspaceId` is the dual-mode switch: NULL = the brand is not
  * connected to a Semrush sub-workspace (resolves against the org parent
  * workspace — "flat" mode); set = the brand has its own Semrush sub-workspace.
  * Deactivation empties the sub-workspace and clears this pointer (the
  * sub-workspace itself is never deleted). See serenity-docs
  * brand-semrush-provisioning-v2-phase1-sync.md §6.
  *
+ * NOTE: there is no brand-level `semrushWorkspaceId` accessor. The deprecated
+ * read-only mirror (attribute, index, `findBySemrushWorkspaceId`,
+ * `allBySemrushWorkspaceId`, `setSemrushWorkspaceId`) was removed in SITES-49202;
+ * `semrushSubWorkspaceId` above is the write-of-record. The identically-named
+ * `Organization.semrushWorkspaceId` is a DISTINCT field and stays — do not
+ * reintroduce a brand mirror by symbol-name sweep.
+ *
  * @class Brand
  * @extends BaseModel
  */
@@ -39,23 +46,6 @@ 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

@@ -28,37 +28,23 @@ const schema = new SchemaBuilder(Brand, BrandCollection)
   })
   // reference_status enum on the brands table. Not `required`: this entity
   // never creates a brand, and a targeted PATCH (e.g. setting only
-  // semrushWorkspaceId) must not be forced to also send status. The validator
+  // semrushSubWorkspaceId) must not be forced to also send status. The validator
   // still rejects an out-of-enum value when status IS written
   // (activate → 'active', deactivate → 'pending').
   .addAttribute('status', {
     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
+  // connected). Same minimum guard the distinct `Organization` entity applies
+  // to its own `semrushWorkspaceId` field (the brand has no such field — its
+  // deprecated mirror was removed in SITES-49202): 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. This is now the write-of-record (see semrushWorkspaceId
-  // above for the deprecated BC mirror).
+  // never user input. This is the write-of-record for the brand → Semrush
+  // sub-workspace pointer.
   .addAttribute('semrushSubWorkspaceId', {
     type: 'string',
     validate: (value) => value == null || hasText(value),
@@ -72,15 +58,9 @@ 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 the
-  // deprecated brands.semrush_workspace_id (mysticat-data-service migration
-  // 20260615102123), so findBySemrushWorkspaceId returns at most one row.
-  // 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
+  // Uniqueness guarantee on the write-of-record column
   // (brands.semrush_sub_workspace_id, mysticat-data-service migration
-  // 20260702091920).
+  // 20260702091920), so findBySemrushSubWorkspaceId returns at most one row.
   .addAllIndex(['semrushSubWorkspaceId']);
 
 export default schema.build();

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

@@ -17,24 +17,13 @@ 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/site/site.collection.js

@@ -14,6 +14,13 @@ import { hasText, isValidHelixPreviewUrl, isValidUrl } from '@adobe/spacecat-sha
 
 import DataAccessError from '../../errors/data-access.error.js';
 import BaseCollection from '../base/base.collection.js';
+import {
+  applyWhere,
+  decodeCursor,
+  DEFAULT_PAGE_SIZE,
+  encodeCursor,
+  toDbField,
+} from '../../util/postgrest.utils.js';
 
 import Site, { AEM_CS_HOST, getAuthoringType } from './site.model.js';
 
@@ -206,6 +213,133 @@ class SiteCollection extends BaseCollection {
     return sites;
   }
 
+  /**
+   * Returns sites filtered by entitlement tier and/or product code, paginated,
+   * and composable with a caller-supplied `where` and `orderBy` — all in a
+   * SINGLE PostgREST query via a two-level inner-join embed
+   * (sites -> site_enrollments -> entitlements).
+   *
+   * PostgREST resource embedding NESTS matching children under each parent row
+   * (it does not flatten into a cartesian product), so `.range()` offset
+   * pagination stays correct over DISTINCT parent sites even when a site has
+   * multiple matching enrollments. `!inner` at both embed levels turns the
+   * embedded filter into an INNER JOIN, excluding sites with no matching
+   * enrollment/entitlement (a plain embedded filter is a LEFT JOIN on older
+   * PostgREST servers, which would return non-matching sites with an empty
+   * embed instead of dropping them).
+   *
+   * Kept symmetric with `Site.all(..., { returnCursor: true, limit })`: it
+   * honors the EXACT `limit` passed (no silent cap, no +1) because the
+   * api-service caller does N+1 hasMore detection (passes `limit =
+   * effectiveLimit + 1` and slices), and returns `{ data, cursor }` when
+   * `returnCursor` is set, else a bare array. This lets the controller call it
+   * almost identically to `Site.all`.
+   *
+   * @param {object} [filter]
+   * @param {string} [filter.tier] - Entitlement tier (e.g. 'PAID', 'FREE_TRIAL').
+   * @param {string} [filter.productCode] - Entitlement product code (e.g. 'LLMO').
+   *   At least one of `tier` / `productCode` is required.
+   * @param {object} [options]
+   * @param {Function} [options.where] - Caller `where` fn `(attrs, op) => expr`
+   *   applied to the sites table (e.g. baseURL substring / deliveryType / isLive).
+   * @param {object} [options.orderBy] - `{ attribute, direction }`; defaults to
+   *   `updatedAt` desc. Always followed by an `id` tiebreaker for stable paging.
+   * @param {number} [options.limit] - Max parent rows to return (exact). A
+   *   non-positive or non-integer value falls back to DEFAULT_PAGE_SIZE.
+   * @param {string} [options.cursor] - Base64 offset cursor (see decodeCursor).
+   * @param {boolean} [options.returnCursor] - Return `{ data, cursor }` shape.
+   * @returns {Promise<Site[] | { data: Site[], cursor: string|null }>}
+   */
+  async allByEnrollmentFiltered(
+    { tier, productCode } = {},
+    {
+      where, orderBy, limit, cursor, returnCursor,
+    } = {},
+  ) {
+    if (!hasText(tier) && !hasText(productCode)) {
+      throw new DataAccessError('tier or productCode is required', this);
+    }
+
+    // The embed must be selected for PostgREST to filter on it. The nested
+    // array PostgREST returns per site is stripped below before hydrating the
+    // Site model (the Site model has no such attribute).
+    const select = '*, site_enrollments!inner(entitlements!inner(tier, product_code))';
+
+    let query = this.postgrestService
+      .from(this.tableName)
+      .select(select);
+
+    if (hasText(tier)) {
+      query = query.eq('site_enrollments.entitlements.tier', tier);
+    }
+    if (hasText(productCode)) {
+      query = query.eq('site_enrollments.entitlements.product_code', productCode);
+    }
+
+    // Caller-supplied where composes on the sites table
+    // (base_url / delivery_type / is_live).
+    query = applyWhere(query, where, this.fieldMaps.toDbMap);
+
+    // Ordering mirrors base.collection #queryPage: a primary sort (default
+    // updatedAt desc) plus a stable id tiebreaker so page boundaries never
+    // straddle equal sort keys. An explicit orderBy is validated the same way
+    // Site.all does — a clear error beats an opaque PostgREST 400 (unknown
+    // column) or a silently-wrong sort direction.
+    const hasOrderBy = hasText(orderBy?.attribute);
+    let orderField = 'updated_at';
+    let ascending = false;
+    if (hasOrderBy) {
+      const { toDbMap } = this.fieldMaps;
+      if (!Object.prototype.hasOwnProperty.call(toDbMap, orderBy.attribute)) {
+        throw new DataAccessError(`unknown orderBy attribute: ${orderBy.attribute}`, this);
+      }
+      const direction = orderBy.direction === undefined
+        ? 'asc'
+        : String(orderBy.direction).toLowerCase();
+      if (direction !== 'asc' && direction !== 'desc') {
+        throw new DataAccessError(`invalid orderBy direction: ${orderBy.direction}`, this);
+      }
+      orderField = toDbField(orderBy.attribute, toDbMap);
+      ascending = direction === 'asc';
+    }
+    query = query.order(orderField, { ascending });
+    const idField = this.fieldMaps.toDbMap[this.idName];
+    if (idField !== orderField) {
+      query = query.order(idField, { ascending });
+    }
+
+    // Honor the exact (positive) limit (no cap, no +1) so the api-service N+1
+    // hasMore detection stays symmetric with Site.all's postgrest path. A
+    // non-positive or non-integer limit falls back to DEFAULT_PAGE_SIZE so a
+    // caller-supplied 0/negative can't produce an inverted PostgREST range.
+    const effectiveLimit = Number.isInteger(limit) && limit > 0 ? limit : DEFAULT_PAGE_SIZE;
+    const offset = decodeCursor(cursor);
+    query = query.range(offset, offset + effectiveLimit - 1);
+
+    const { data, error } = await query;
+    if (error) {
+      this.log.error(`[SiteCollection] Failed to query sites by enrollment filter - ${error.message}`, error);
+      throw new DataAccessError('Failed to query sites by enrollment filter', this, error);
+    }
+
+    const instances = (data || []).map((row) => {
+      // Drop the embed PostgREST nests on each parent row so it cannot leak
+      // onto the hydrated Site record.
+      const siteRow = { ...row };
+      delete siteRow.site_enrollments;
+      return this.createInstanceFromRow(siteRow);
+    });
+
+    if (returnCursor) {
+      const nextCursor = instances.length === effectiveLimit
+        ? encodeCursor(offset + effectiveLimit)
+        : null;
+      return { data: instances, cursor: nextCursor };
+    }
+
+    return instances;
+  }
+
   async allByOrganizationIdAndProjectName(organizationId, projectName) {
     if (!hasText(organizationId)) {
       throw new DataAccessError('organizationId is required', this);