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

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@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.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

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);