feat(project-engine-client): add GET /v1/url/resolve to the vendored client + mock

[rainer-friederich]

1. Abstract

Adds the Semrush Project Engine GET /v1/url/resolve endpoint to the vendored spacecat-shared-project-engine-client — its generated types, the spec overlay, and the stateful Counterfact mock. This is §1 of the cross-repo brand-URL normalization spec.

2. Reasoning

When we add a brand URL to a Semrush AIO project we currently send the raw URL verbatim (e.g. https://www.lovesac.com). Semrush stores brand URLs in a canonical, scheme-less form (lovesac.com) and its own frontend normalizes first by calling the Project Engine URL-resolve endpoint before writing. Sending the raw URL produces a duplicate/mismatched brand-URL entry that does not line up with the canonical benchmark Semrush already holds. Fixing that requires the endpoint to exist in the vendored typed client first — this PR is that prerequisite. Reported by the Semrush team in the Elements-wrappers review thread (2026-07-02/03); the live contract was captured directly against prod.

3. High-level overview of the changes

Models a live endpoint that is absent from the vendored swagger, following the established overlay + regenerate + mock pattern (precedent CR1/CR8). No consumer-facing client code changes — the client is a thin generic openapi-fetch wrapper, so once the path is in the generated types a caller just does client.GET('/v1/url/resolve', { params: { query: { primary_url } } }).

• Spec overlay (CR16): adds a model.UrlResolveResponse schema ({ domain, primary_url, is_valid }, all required) and the GET /v1/url/resolve path (query param primary_url required, 200/400/401 responses). Regenerating from the overlay updates src/generated/types.ts and the pydantic models; the regen also catches up a previously-stale pydantic artifact (a CR14 field that had only been regenerated into the TS types).
• Mock behaviour (before → after): the endpoint did not exist → the mock now canonicalizes primary_url. It strips the scheme and a leading www. while preserving any other subdomain and the path (http://www.lovesac.com/products → lovesac.com/products; blog.hubspot.com stays blog.hubspot.com); domain is the registrable apex (subdomain stripped too). Unresolvable/garbage input returns { domain: '', primary_url: '', is_valid: false } at HTTP 200 — never an error — matching the live trap that consumers must check is_valid.
• The canonicalization is a pure, unit-tested helper (mock/url-resolve.js) exposed on the mock context like the existing tagId/parentIdField helpers, rather than logic buried in the coverage-excluded route handler.
• Endpoint inventory in docs/mock-usage.md updated to list the new route.

Two intentional, documented mock simplifications: the apex is the last two dot-labels (so a multi-part public suffix like example.co.uk collapses to co.uk, unlike live's PSL), and an empty primary_url= returns 200 is_valid:false rather than 400 (Counterfact enforces the required presence — a missing param still 400s — but not the string minLength).

4. Required information

• Spec: https://github.com/adobe/serenity-docs/issues/25
• Other: brand-URL normalization tracked alongside the Serenity mapping-table work https://github.com/adobe/serenity-docs/issues/23

5. Affected / used mysticat-workspace projects

• spacecat-api-service — will consume this endpoint (§2 of the spec): a new resolveUrl transport method + resolve-before-write on the brand-URL CREATE/EDIT paths. Blocked on this package being released (contract dependency).
• mysticat-data-service — the Serenity migration CLI (§3, on the feat/customer_onboarding branch / Add Page Authentication Token Retrieval Functionality #737) will add the same resolve_url call. Also blocked on this release.

6. Additional information outside the code

• Booted the stateful Counterfact mock (npm run test:e2e) and drove the new /v1/url/resolve route end-to-end through the real createSerenityProjectEngineApiClient — verified the canonical case, the subdomain/path-preserving case, the is_valid:false garbage case (HTTP 200), and the missing-vs-empty primary_url request-validation behaviour.
• The live contract behind the mock was captured directly against prod Project Engine (https://adobe-hackathon.semrush.com) with a real IMS bearer (serenity-docs#25 §0) — method, param, response shape, error codes, and the is_valid:false empty-string trap are ground truth, not assumptions.

7. Test plan

• (a) Local: unit suite plus the offline overlay freshness gate (asserts CR16 both applies and is necessary against the vendored swagger), and the MOCK_E2E=1 end-to-end suite driving the booted mock through the typed client — all exercised locally.
• (b) Per-env: this package ships no runtime service, so there is no eph/dev/stage/prod deploy to verify. After merge, semantic-release publishes a new npm version and the GHCR mock Docker image republishes on the release tag; consumers verify by bumping @adobe/spacecat-shared-project-engine-client and calling client.GET('/v1/url/resolve', { params: { query: { primary_url } } }) against the published mock image in their integration tests.

8. Deployment & merge order

• This PR is the hard prerequisite for the rest of serenity-docs#25 — it must merge and release (npm + GHCR mock image) first.
• After release: the api-service change (§2) bumps the dependency and adds the resolve-before-write; the migration CLI change (§3) does the same. Both are related and neither can build/test until this version publishes.

Ordered sequence: merge + release this PR → api-service §2 + migration §3 bump the dep and proceed in parallel.

🤖 Generated with Claude Code

[MysticatBot]

Hey @rainer-friederich,

Verdict: Approve - well-structured addition following established patterns, no blocking issues.
Complexity: HIGH - medium diff; API surface signal.
Changes: Adds the Semrush Project Engine GET /v1/url/resolve endpoint to the vendored client via spec overlay CR16, generated types, a pure mock canonicalizer, and comprehensive tests (16 files).

Non-blocking (4): minor issues and suggestions

• nit: No test pinning query-string/fragment stripping behavior - mock/url-resolve.js:76 uses parsed.pathname which excludes query/hash by design, but no test proves resolveUrl('https://lovesac.com/products?ref=123#top') strips them. One assertion would document the decision and catch a future refactor to .href or .path.
• nit: No test for port stripping - mock/url-resolve.js:57 uses .hostname (not .host), so ports are implicitly dropped. A test for resolveUrl('https://www.lovesac.com:8443/path') would pin this.
• nit: Trailing-slash semantics undocumented - https://lovesac.com/products/ preserves the trailing slash since parsed.pathname returns /products/ which is not /. Whether live preserves or strips is unstated; a test documenting the choice prevents surprise.
• suggestion: Add a composition-seam assertion (createUrlResolveMock(resolveUrl('garbage')) yields { domain: '', primary_url: '', is_valid: false }) to lock the contract between the pure function and the factory without booting the server. The route handler (the glue) is coverage-excluded, so this is the cheapest way to catch a factory-default drift.

Note: CI "Test" check is still pending - confirm it passes before merge.

---

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

[github-actions]

This PR will trigger a minor release when merged.

[rainer-friederich]

Addressed the review's 4 non-blocking items in cb636ef (all test-only — no behaviour change).

MysticatBot:

• nit: query-string/fragment stripping untested — done. Added an assertion that https://lovesac.com/products?ref=123#top → lovesac.com/products (query + fragment dropped by design, since the canonicalizer reads parsed.pathname).
• nit: port stripping untested — done. Added https://www.lovesac.com:8443/path → lovesac.com/path, pinning the .hostname (not .host) choice.
• nit: trailing-slash semantics undocumented — done. Added a test pinning the mock's behaviour (/products/ is preserved; only a bare root / is dropped), with a comment noting live trailing-slash handling is unverified so the test documents the mock's deliberate choice.
• suggestion: composition-seam assertion — done. Added createUrlResolveMock(resolveUrl(...)) for both a valid and a garbage input, locking the pure-function ↔ factory-default contract that the coverage-excluded route handler relies on, without booting the server.

CI "Test" check: will confirm green before considering this ready.

[MysticatBot]

Hey @rainer-friederich,

Verdict: Approve - all four prior nits addressed cleanly; no new concerns.
Complexity: HIGH - large diff; API surface signal.
Changes: Adds the Semrush Project Engine GET /v1/url/resolve endpoint to the vendored client via spec overlay CR16, generated types, a pure mock canonicalizer, and comprehensive tests (16 files).

Note: CI "Test" and "E2E" checks are still pending - confirm green before merge.

Previously flagged, now resolved

• Query-string/fragment stripping now pinned by test (url-resolve.test.js:59)
• Port stripping now pinned by test (url-resolve.test.js:66)
• Trailing-slash semantics documented by test (url-resolve.test.js:73)
• Composition-seam assertion added for valid and invalid paths (url-resolve.test.js:80)

---

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

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-project-engine-client-v1.8.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀