feat: add support for searching trial users by external user id

[vivesing]

Summary

Goal: Expose the newly added external_user_id DB index (mysticat-data-service) through the JS data-access layer for TrialUser.

related to index added in DB https://github.com/adobe/mysticat-data-service/pull/886

Files changed

File	Change
packages/spacecat-shared-data-access/src/models/trial-user/trial-user.schema.js	Added a new index: { composite: ['externalUserId'] } / { composite: ['updatedAt'] }
packages/spacecat-shared-data-access/test/it/trial-user/trial-user.test.js	Added integration test 'gets a trial user by external user id' covering TrialUser.findByExternalUserId(...)

What this generates

The new schema index auto-generates these methods on TrialUserCollection:

• findByExternalUserId(externalUserId)
• allByExternalUserId(externalUserId)
• findByExternalUserIdAndUpdatedAt(externalUserId, updatedAt)
• allByExternalUserIdAndUpdatedAt(externalUserId, updatedAt)

Test coverage

• New: IT test exercising findByExternalUserId, following the existing findByEmailId / allByOrganizationId pattern in the same file.
• Automatic: test/it/postgrest/all-collections-methods-coverage.test.js generically sweeps all allBy*/findBy* accessors, so it picks up the new methods without any manual entry.
• Not added: entity-specific unit tests — this codebase only unit-tests hand-written custom collection methods, not schema-generated findBy*/allBy* accessors.

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @vivesing,

⚠ Degraded review - no spec document was found for this change (searched the PR links, the touched repos docs, the architecture/guidelines docs, and linked Jira). This review covers code-level quality but could not validate the change against an agreed design, so confidence is reduced. Add a spec link (PR template section 4) and re-request review for a full-confidence pass.

Verdict: Approve - clean, mechanical, pattern-following addition with no issues found.
Complexity: LOW - trivial diff; Database/Schema signal.
Changes: Adds a composite index on externalUserId (with updatedAt sort key) to the TrialUser schema and an integration test for the generated findByExternalUserId method (2 files).

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 0m 56s | Cost: $2.12 | Commit: eb8133428b72b3c505d232a26508f48250422ae3
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[calvarezg]

Hey @vivesing,

⚠ Degraded review - no spec document was found for this change (searched the PR links, the touched repos' docs, the architecture/guidelines docs, and linked Jira). This review covers code-level quality but could not validate the change against an agreed design, so confidence is reduced. Add a spec link (PR template section 4) and re-request review for a full-confidence pass.

Verdict: Comment - the schema change is correct and pattern-following; one type-declaration gap plus a few non-blocking notes.
Complexity: LOW - trivial diff; Database/Schema signal.
Changes: Adds a composite index on externalUserId (sort key updatedAt) to the TrialUser schema and one IT test for the generated findByExternalUserId (2 files).

Should fix before merge

1. [Important] The new index generates findByExternalUserId/allByExternalUserId at runtime, but src/models/trial-user/index.d.ts declares neither - TS consumers of the new accessor get no type signature. The sibling organizationId and emailId indexes both declare their find/all pairs in that file, so this is an incomplete change against the file's own convention. Note: this repo has no tsc/type-check step in CI, so the gap does not fail CI here; it surfaces as a compile error in a downstream TypeScript consumer. (details inline)

Non-blocking (3): suggestions and nits

• suggestion: findByExternalUserId is a singular accessor over a nullable, non-unique field (the updatedAt sort key implies one-to-many). On a duplicate or absent externalUserId it returns one arbitrary row with no signal. Decide and document whether externalUserId is unique per trial user; if it is not, callers should prefer allByExternalUserId. - packages/spacecat-shared-data-access/src/models/trial-user/trial-user.schema.js:57
• nit: the IT test covers only the happy path; add a not-found assertion (expect(await TrialUser.findByExternalUserId('nonexistent-id')).to.be.null) to pin the not-found contract. - packages/spacecat-shared-data-access/test/it/trial-user/trial-user.test.js:24
• nit: this brings the trial-user schema to 4 indexes against a hard cap of 5 (enforced in schema.builder.js at module import, not at deploy) - the next lookup index added will throw at service startup. - packages/spacecat-shared-data-access/src/models/trial-user/trial-user.schema.js:57

Out of scope, worth tracking

• Cross-repo deploy ordering: the physical Postgres index lives upstream in mysticat-data-service (886, merged). Confirm it exists in each environment before consumers call findByExternalUserId, otherwise lookups fall back to a full table scan.
• Authorization for lookup-by-external-id is enforced by the API-service caller, not this library. Confirm the calling route applies the usual access control.

[vivesing]

@calvarezg , review comments addressed in #1871

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-data-access-v4.19.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀