feat(SITES-47203): add baseUrlContains substring search to GET /sites

[habansal]

Summary

Extends the existing GET /sites controller (src/controllers/sites.js, getAll) with an optional baseUrlContains query param for case-insensitive substring search on a site's baseURL. Part of SITES-47203 (the ESS backoffice consumes this to let users find sites by partial URL).

Endpoint contract

GET /sites?baseUrlContains=<substr>[&limit=<n>]

• baseUrlContains (string, optional): case-insensitive substring matched against baseURL. Must be >= 3 chars after trimming. LIKE wildcards (%, _, \) are escaped and matched literally.
• limit (int, optional): bounds result size. Defaults to 50, clamped to 500 (MAX_LIMIT). Non-positive/non-integer -> 400.

Response (200): non-cursor envelope

{ "sites": [ /* slim site DTOs */ ], "pagination": { "limit": 50, "hasMore": false, "baseUrlContains": "<query>" } }

hasMore is derived by fetching limit + 1 rows. There is no cursor on this path (not cursor-iterable).

Errors:

• 400 - baseUrlContains shorter than 3 chars (baseUrlContains must be at least 3 characters)
• 400 - invalid limit (limit must be a positive integer)
• 403 - caller lacks admin access / S2S site:readAll

Behavior preserved

The new branch runs after the admin/S2S site:readAll authz check (403 still enforced) and before the existing cursor-paginated and legacy flat-array branches. Those paths are unchanged.

Tests

Added a GET /sites - baseUrlContains substring search suite covering: ilike where builder + order:'asc' + limit=N+1, hasMore true/false with body trimming, wildcard escaping, slim DTO shape, cursor-shaped result fallback, < 3 char -> 400, invalid limit -> 400, MAX_LIMIT clamp, and 403 for a non-admin/non-S2S caller. Existing getAll tests still pass.

Also documented the param in docs/openapi/sites-api.yaml.

Test plan

• npx mocha --spec=test/controllers/sites.test.js - 381 passing
• eslint on changed files - clean
• npm run docs:lint - API description valid

🤖 Generated with Claude Code

---

Update — local review fixes applied

Hardened after a local multi-specialist review (code/API/security/SRE/QA/spec). Added: a deploy-ordering discriminator (pagination.baseUrlContains echo) so clients can detect an older API that ignored the param; unconditional [sites][baseUrlContains] observability logging (no raw query); a max-length guard (≤256); a named SEARCH_DEFAULT_LIMIT; and tests for empty-results, the echo, the 3-char boundary, and over-length. ADR-006 updated with the deploy-ordering rationale.

⚠️ Deploy ordering: the Backoffice client always sends limit, so an older deployment of this API would ignore baseUrlContains and return unfiltered cursor results. Deploy this PR before or together with the Backoffice consumer (OneAdobe/experience-success-studio-backoffice#332).

Jira: https://jira.corp.adobe.com/browse/SITES-47203

---

Update — offset pagination + param rename

• Renamed the search param baseUrlLike → baseUrlContains (clearer intent; avoids leaking the SQL ilike into the public contract). The pagination.baseUrlContains echo was renamed to match.
• Added offset pagination: GET /sites?baseUrlContains=<q>&limit=<N>&offset=<M> → { sites, pagination: { limit, offset, hasMore, baseUrlContains } }. offset defaults to 0, must be a non-negative integer. (The data-access layer exposes no public offset, so the controller builds the same offset-encoded cursor inline — documented in ADR-006.)
• ADR-006, OpenAPI, and tests updated. 385 mocha passing; it-postgres covers an offset paging case.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

This PR will trigger a minor release when merged.

[habansal]

✅ Full test plan validated end-to-end (including live dev)

Verified at every layer:

• Unit: API mocha 377 / backoffice jest — green
• Integration (CI it-postgres): real Postgres + PostgREST — green
• UI e2e (Playwright): 4/4
• Live wired smoke on dev /ci (real client → Fastly → Lambda → PostgREST → real dev Postgres): 13/13 pass
  • real substring filtering (baseUrlLike=adobe → actual adobe sites), pagination.baseUrlLike echo present, no cursor
  • min length: 2-char → 400, 3-char → 200
  • wildcard escaping: %adobe → 0 matches
  • no-match → empty + hasMore:false + echo
  • limit capped at 500; default 50; limit=1 → hasMore:true
  • GET /sites/:id lookup ✓ and GET /sites/by-base-url/<b64> exact ✓

Also observed the deploy-ordering hazard live (old /ci deploy returned unfiltered results with no echo) — the client fail-loud guard handles exactly that. Full trail on SITES-47203.

[MysticatBot]

Hey @habansal,

Verdict: Request changes - two blocking issues around param-combination behavior and error resilience.
Complexity: HIGH - medium diff; API surface risk flag.
Changes: Adds optional baseUrlLike substring search to GET /sites with input validation, LIKE wildcard escaping, N+1 hasMore pagination, and a deploy-ordering echo (6 files).
Note: Recommend a human read before merge - this change amends an architectural decision record and modifies the OpenAPI contract. The bot review is a complement to, not a replacement for, a human read here.
Note: CI checks are currently failing (codecov/patch: 2 lines missing coverage).

Must fix before merge

1. [Important] Silent cursor discard when combined with baseUrlLike - src/controllers/sites.js:461 (details inline)
2. [Important] No resilience handling for unexpected Site.all return shape - src/controllers/sites.js:487 (details inline)

Non-blocking (4): minor issues and suggestions

• nit: order: 'asc' relies on the data-access layer's default sort column rather than specifying one explicitly; ITs prove stability but the assumption is implicit and fragile if the shared library changes its default - src/controllers/sites.js:485
• nit: OpenAPI minLength: 3 / maxLength: 256 on baseUrlLike describe post-trim semantics but apply pre-trim in the schema; a value like " ab " passes the schema but fails the server - docs/openapi/sites-api.yaml:176
• suggestion: Close the codecov gap by adding a unit test that exercises the baseUrlLike path with S2S auth context (the if (s2sResult.allowed) log branch) - src/controllers/sites.js:491
• suggestion: Add the effective limit to the unconditional observability log (limit=50) to distinguish "capped at limit" from "exact match count" in production - src/controllers/sites.js:497

---

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

[MysticatBot]

Hey @habansal,

Verdict: Request changes - two documentation inaccuracies in the new ADR need correction before merge.
Complexity: HIGH - large diff; API surface.
Changes: Adds optional baseUrlLike substring search to GET /sites with input validation, LIKE wildcard escaping, N+1 hasMore pagination, and a deploy-ordering echo (6 files).
Note: Recommend a human read before merge - this change amends an architectural decision record and modifies the OpenAPI contract. The bot review is a complement to, not a replacement for, a human read here.

Must fix before merge

1. [Important] ADR-006 documents wrong where clause signature - docs/decisions/006-sites-base-url-search.md:38 (details inline)
2. [Important] ADR-006 omits baseUrlLike echo from documented response shape - docs/decisions/006-sites-base-url-search.md:44 (details inline)

Non-blocking (4): minor issues and suggestions

• nit: order: 'asc' without an explicit orderBy field relies on the data-access layer's default sort column; the integration tests prove stability but the assumption is implicit - src/controllers/sites.js:485
• nit: OpenAPI minLength: 3 / maxLength: 256 describe post-trim semantics but schema validators enforce pre-trim; a value like " ab " passes the schema but fails the server - docs/openapi/sites-api.yaml:170
• nit: ADR-006 introduces undefined "UbI" acronym on line 13 that is never referenced again - docs/decisions/006-sites-base-url-search.md:13
• suggestion: Close the codecov gap by adding a unit test exercising the baseUrlLike path with S2S auth context (the if (s2sResult.allowed) log branch) - src/controllers/sites.js:515

Previously flagged, now resolved

• Cursor + baseUrlLike combination now explicitly rejected with 400 (guard + test added)
• Unexpected Site.all return shape now handled with try/catch, shape guard, warning log, and tests

---

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

[MysticatBot]

Hey @habansal,

Verdict: Approve - all prior blocking findings addressed; ADR corrections are accurate.
Complexity: HIGH - large diff; API surface.
Changes: Adds optional baseUrlLike substring search to GET /sites with input validation, LIKE wildcard escaping, N+1 hasMore pagination, and a deploy-ordering echo (6 files).
Note: Recommend a human read before merge - this change adds an architectural decision record and modifies the OpenAPI contract. The bot review is a complement to, not a replacement for, a human read here.
Note: CI checks are currently pending - confirm they pass before merge.

Previously flagged, now resolved

• Silent cursor discard when combined with baseUrlLike now explicitly rejected with 400
• Unexpected Site.all return shape now handled with try/catch, shape guard, and warning log
• ADR where clause signature corrected to (attr, op) => op.ilike(attr.baseURL, ...)
• ADR response shape now includes the baseUrlLike deploy-ordering echo
• ADR "UbI" typo corrected to "UI"
• ADR now documents order: 'asc' tiebreaker behavior via base.collection's #getOrderFields

---

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

[MysticatBot]

Hey @habansal,

Verdict: Approve - new commit closes the codecov gap on the S2S auth path as suggested; no new concerns.
Complexity: HIGH - large diff; API surface.
Changes: Adds optional baseUrlLike substring search to GET /sites with input validation, LIKE wildcard escaping, N+1 hasMore pagination, and a deploy-ordering echo (6 files).
Note: Recommend a human read before merge - this change adds an architectural decision record and modifies the OpenAPI contract. The bot review is a complement to, not a replacement for, a human read here.
Note: CI checks are currently pending - confirm they pass before merge.

Previously flagged, now resolved

• Codecov S2S auth-path coverage gap now closed with dedicated site:readAll + baseUrlLike test

---

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

[MysticatBot]

Hey @habansal,

Verdict: Approve - new commit cleanly adds offset pagination and renames the param; no blocking concerns.
Complexity: HIGH - large diff; API surface.
Changes: Renames baseUrlLike to baseUrlContains, adds offset-based pagination via internal cursor construction, and updates ADR-006/OpenAPI/tests accordingly (6 files).
Note: Recommend a human read before merge - this change adds an architectural decision record and modifies the OpenAPI contract. The bot review is a complement to, not a replacement for, a human read here.

Non-blocking (3): minor issues and suggestions

• nit: parseInt silently truncates floats (e.g. offset=2.5 becomes 2, limit=3.7 becomes 3) rather than rejecting them, which diverges from the documented "must be an integer" contract - src/controllers/sites.js:492
• suggestion: Reject offset when provided without baseUrlContains (currently silently ignored, falling through to the cursor path). The OpenAPI spec documents this scoping, but a 400 would prevent confused clients from getting unfiltered results when they intended a search - src/controllers/sites.js:458
• suggestion: Add an integration test for offset beyond total results (e.g. offset=9999) to assert the expected { sites: [], hasMore: false } response and catch any future data-access regressions on out-of-bounds offsets - test/it/shared/tests/sites.js

Previously flagged, now resolved

• Silent cursor discard when combined with baseUrlLike now explicitly rejected with 400 (renamed to baseUrlContains)
• Unexpected Site.all return shape now handled with try/catch, shape guard, and warning log
• ADR where clause signature corrected
• ADR response shape now includes the echo field
• Codecov S2S auth-path coverage gap closed
• ADR renamed throughout from baseUrlLike to baseUrlContains with offset documentation added

---

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