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

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v4.22.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.21.1...@adobe/spacecat-shared-data-access-v4.22.0) (2026-08-14)
+
+### Features
+
+* schema changes for trial users entity to allow searching by external user id ([#1871](https://github.com/adobe/spacecat-shared/issues/1871)) ([3ecf546](https://github.com/adobe/spacecat-shared/commit/3ecf5466b41dcd32cf5dd591f8762fefd714af1f))
+
+## [@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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "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/trial-user/index.d.ts

@@ -43,9 +43,29 @@ export interface TrialUserCollection extends BaseCollection<TrialUser> {
   allByProviderAndExternalUserId(provider: ProviderType, externalId: string): Promise<TrialUser[]>;
   allByOrganizationId(organizationId: string): Promise<TrialUser[]>;
   allByEmailId(emailId: string): Promise<TrialUser[]>;
+  allByExternalUserId(externalUserId: string): Promise<TrialUser[]>;
+  allByExternalUserIdAndUpdatedAt(
+    externalUserId: string,
+    updatedAt: string
+  ): Promise<TrialUser[]>;
   findByProvider(provider: ProviderType): Promise<TrialUser | null>;
   findByProviderAndExternalUserId(provider: ProviderType, externalId: string):
     Promise<TrialUser | null>;
   findByOrganizationId(organizationId: string): Promise<TrialUser | null>;
   findByEmailId(emailId: string): Promise<TrialUser | null>;
+  /**
+   * externalUserId is optional and not enforced unique (no DB unique constraint), so this
+   * returns one arbitrary match when multiple trial users share the same externalUserId.
+   * Use allByExternalUserId if you need every matching record.
+   */
+  findByExternalUserId(externalUserId: string): Promise<TrialUser | null>;
+  /**
+   * externalUserId is optional and not enforced unique (no DB unique constraint), so this
+   * returns one arbitrary match when multiple trial users share the same externalUserId.
+   * Use allByExternalUserIdAndUpdatedAt if you need every matching record.
+   */
+  findByExternalUserIdAndUpdatedAt(
+    externalUserId: string,
+    updatedAt: string
+  ): Promise<TrialUser | null>;
 }

package/src/models/trial-user/trial-user.schema.js

@@ -53,6 +53,11 @@ const schema = new SchemaBuilder(TrialUser, TrialUserCollection)
     { composite: ['organizationId'] },
     { composite: ['updatedAt'] },
   )
+  // externalUserId is not enforced unique (no DB unique constraint) and is optional, so
+  // findByExternalUserId only returns one arbitrary match. Prefer allByExternalUserId
+  // unless the caller can guarantee uniqueness for their use case.
+  // Note: this schema is now at 4 of the 5-index cap enforced by SchemaBuilder
+  // (#buildIndexes) - budget the next lookup index accordingly.
   .addIndex(
     { composite: ['externalUserId'] },
     { composite: ['updatedAt'] },