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

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@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
+
+* **data-access:** compound AND filter and orderBy column for postgrest queries ([#1874](https://github.com/adobe/spacecat-shared/issues/1874)) ([620b37e](https://github.com/adobe/spacecat-shared/commit/620b37eb1bc252c9bdd01661037de6fd7e0bfe35))
+
 ## [@adobe/spacecat-shared-data-access-v4.19.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.18.0...@adobe/spacecat-shared-data-access-v4.19.0) (2026-08-11)
 
 ### Features

package/CLAUDE.md

@@ -178,7 +178,7 @@ This is the same client instance used internally by entity collections — same
 async findByStatus(status) {
   return this.all(
     (attrs, op) => op.eq(attrs.status, status),
-    { limit: 100, order: { field: 'createdAt', direction: 'desc' } }
+    { limit: 100, orderBy: { attribute: 'createdAt', direction: 'desc' } }
   );
 }
 ```

package/package.json

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

package/src/models/base/base.collection.js

@@ -428,8 +428,25 @@ class BaseCollection {
       this.#logAndThrowError(`Failed to query [${this.entityName}]: query proxy [${options.index}] not found`);
     }
 
-    const orderFields = this.#getOrderFields(indexName, keys);
-    const ascending = options.order === 'asc';
+    const hasExplicitOrderBy = isObject(options.orderBy) && hasText(options.orderBy.attribute);
+    let explicitAscending;
+    if (hasExplicitOrderBy) {
+      const { toDbMap } = this.fieldMaps;
+      if (!Object.prototype.hasOwnProperty.call(toDbMap, options.orderBy.attribute)) {
+        this.#logAndThrowError(`Failed to query [${this.entityName}]: unknown orderBy attribute [${options.orderBy.attribute}]`);
+      }
+      const direction = options.orderBy.direction === undefined
+        ? 'asc'
+        : String(options.orderBy.direction).toLowerCase();
+      if (direction !== 'asc' && direction !== 'desc') {
+        this.#logAndThrowError(`Failed to query [${this.entityName}]: invalid orderBy direction [${options.orderBy.direction}]`);
+      }
+      explicitAscending = direction === 'asc';
+    }
+    const orderFields = hasExplicitOrderBy
+      ? [this.#toDbField(options.orderBy.attribute)]
+      : this.#getOrderFields(indexName, keys);
+    const ascending = hasExplicitOrderBy ? explicitAscending : options.order === 'asc';
     let query = this.postgrestService
       .from(this.tableName)
       .select(select);

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

@@ -33,6 +33,7 @@ export interface QueryOptions {
   index?: string;
   limit?: number;
   order?: string;
+  orderBy?: { attribute: string; direction?: 'asc' | 'desc' };
   attributes?: string[];
   cursor?: string;
   /**

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

package/src/util/postgrest.utils.js

@@ -152,6 +152,7 @@ const applyWhere = (query, whereFn, toDbMap) => {
     like: (field, value) => ({ type: 'like', field, value }),
     ilike: (field, value) => ({ type: 'ilike', field, value }),
     contains: (field, value) => ({ type: 'contains', field, value }),
+    and: (...conditions) => ({ type: 'and', conditions: conditions.filter(Boolean) }),
   };
 
   const expression = whereFn(attrs, op);
@@ -159,37 +160,43 @@ const applyWhere = (query, whereFn, toDbMap) => {
     return query;
   }
 
-  switch (expression.type) {
-    case 'eq':
-      return query.eq(expression.field, expression.value);
-    case 'ne':
-      return query.neq(expression.field, expression.value);
-    case 'gt':
-      return query.gt(expression.field, expression.value);
-    case 'gte':
-      return query.gte(expression.field, expression.value);
-    case 'lt':
-      return query.lt(expression.field, expression.value);
-    case 'lte':
-      return query.lte(expression.field, expression.value);
-    case 'in':
-      return query.in(
-        expression.field,
-        Array.isArray(expression.value) ? expression.value : [expression.value],
-      );
-    case 'is':
-      return query.is(expression.field, expression.value);
-    case 'like':
-      return query.like(expression.field, expression.value);
-    case 'ilike':
-      return query.ilike(expression.field, expression.value);
-    case 'contains': {
-      const value = Array.isArray(expression.value) ? expression.value : [expression.value];
-      return query.contains(expression.field, value);
+  const applyExpr = (q, expr) => {
+    switch (expr.type) {
+      case 'and':
+        return (expr.conditions || []).reduce((acc, cond) => applyExpr(acc, cond), q);
+      case 'eq':
+        return q.eq(expr.field, expr.value);
+      case 'ne':
+        return q.neq(expr.field, expr.value);
+      case 'gt':
+        return q.gt(expr.field, expr.value);
+      case 'gte':
+        return q.gte(expr.field, expr.value);
+      case 'lt':
+        return q.lt(expr.field, expr.value);
+      case 'lte':
+        return q.lte(expr.field, expr.value);
+      case 'in':
+        return q.in(
+          expr.field,
+          Array.isArray(expr.value) ? expr.value : [expr.value],
+        );
+      case 'is':
+        return q.is(expr.field, expr.value);
+      case 'like':
+        return q.like(expr.field, expr.value);
+      case 'ilike':
+        return q.ilike(expr.field, expr.value);
+      case 'contains': {
+        const value = Array.isArray(expr.value) ? expr.value : [expr.value];
+        return q.contains(expr.field, value);
+      }
+      default:
+        throw new Error(`Unsupported where operator: ${expr.type}`);
     }
-    default:
-      throw new Error(`Unsupported where operator: ${expression.type}`);
-  }
+  };
+
+  return applyExpr(query, expression);
 };
 
 export {