project-engine-client mock: AIO tag ids embed %3A (name-derived) and don't round-trip through URLs — blocks nested children-drill / PATCH-by-id IT

[rainer-friederich]

Summary

The @adobe/spacecat-shared-project-engine-client Counterfact mock derives an AIO tag's id from its name — tag-${encodeURIComponent(name)} (see mock/tag-id.js). For a category:<NAME> tag that id therefore embeds a literal %3A (the encoded colon), e.g. tag-category%3AFootwear.

That id round-trips faithfully through a JSON body, but not through a URL (query or path): the %3A is decoded back to : in transit, so the value a consumer sends no longer matches the stored id. As a result, the two id-in-URL nested-tag operations cannot be exercised against the mock:

• GET /v2/workspaces/{id}/projects/{project_id}/aio/tags?parent_id=<childId's parent> — drilling a parent's children by id returns empty (the decoded parent_id query value ≠ the stored id).
• PATCH /v2/workspaces/{id}/projects/{project_id}/aio/tags/{tag_id} — a re-parent/rename of an existing category:* tag 404s (the decoded tag_id path segment ≠ the stored id).

This is mock-only: real Semrush uses opaque UUID tag ids (no reserved characters), so both operations work end-to-end there. Verified with a live prod probe on 2026-07-01 (adobe-hackathon.semrush.com, workspace 0a496c87…): direct POST parent_id nests, GET ?parent_id=<uuid> returns the child with a path[] breadcrumb, and PATCH /aio/tags/{uuid} renames/re-parents → 200.

Impact

The nested-tag support added in #1758 is partially untestable against the mock. The spacecat-api-service consumer ( adobe/spacecat-api-service#2737 ) can only assert the JSON-body paths (nested create + derived children_count) against the mock; the children-drill-by-id and a successful PATCH-by-id are validated against live Semrush instead, and their IT assertions are omitted with a note.

Proposed fix

Make the mock's tag id opaque and URL-safe — a value with no reserved characters — so a stored id survives a URL round-trip:

• e.g. a short hash of the name (tag-<hex-digest>), or a UUID, instead of tag-${encodeURIComponent(name)}.
• Idempotency by name must be preserved (a repeated POST of the same name still reuses the id, as today), so a deterministic hash of the name is a natural fit.
• Note the documented trade-off already in the tags.js header: because ids are name-derived, a rename leaves the id keyed to the old name. A hash keeps that same property; it only removes the reserved-character problem. (If desired, this is also an opportunity to model opaque ids that stay stable across rename — but that is a larger change and not required to close this issue.)

Acceptance

With URL-safe ids, a consumer IT can assert, entirely against the mock:

• GET /aio/tags?parent_id=<parentId> returns the child, with children_count and a path[] breadcrumb.
• PATCH /aio/tags/{tag_id} on an existing tag returns 200 with the updated name / parent_id.

References

• Mock nested-tag support: feat(project-engine-client): model 1-level nested AIO tags in the mock #1758
• Consumer PR that surfaced this: feat(serenity): consume nested AIO tags (parentId create, tree read, PATCH re-parent) spacecat-api-service#2737
• Parent design: https://github.com/adobe/serenity-docs/issues/21

[rainer-friederich]

Additional mock adjustments needed: id-based prompt→tag attachment (beyond the %3A-in-URL fix)

This issue covers the tag-id URL round-trip (children-drill-by-id, PATCH-by-id). While validating the prompt-tagging side of the same nested-category effort (spec serenity-docs#21), a second, independent mock gap surfaced: the id-based prompt-tagging endpoints aren't mocked at all.

Why it matters. The nested design tags prompts to children by tag id (a bare child name creates a flat root tag; live-verified). The two id-based paths — live-confirmed against adobe-hackathon.semrush.com on 2026-07-01 — are:

• POST /aio/prompts (aio-create-prompt-v2, model.KeywordRequest {items, tag_ids}) — create prompt(s) with existing tag ids.
• PUT /aio/prompts/tags (aio-update-prompts-batch, model.BatchReferenceRequest {items:[{id, references, replace}]}) — attach existing tag ids to an existing prompt.

Current mock state (mock/counterfact/routes/v2/workspaces/{id}/projects/{project_id}/aio/):

• prompts.js exports only DELETE → no POST create-prompt-v2 honouring tag_ids.
• No prompts/tags.js → PUT /aio/prompts/tags is unmocked.
• Already fine: prompts/by_tags.js filters by tag_ids with OR and returns each prompt's tags[]; prompts/tagged.js is name-based/flat (faithful to live — keep it as the flat-root path; it must not be the path for children).

Proposed additions:

1. POST /aio/prompts in prompts.js — honour {items, tag_ids}: create one prompt per items[] text, resolve each tag_ids entry against the stored tag collection and materialise p.tags as the full tag object (id + name + parent_id), so a subsequent by_tags reflects the nesting. Return {items:[{id,name}], existing_count} (dedup by text, mirroring tagged.js).
2. prompts/tags.js — PUT honouring {items:[{id, references, replace}]}: find each prompt by id, set (replace:true) or merge its .tags to the referenced existing tag ids; 204.

Independent of this issue's %3A problem: both reference tag ids in the JSON body, not a URL, so they round-trip faithfully even with the current name-derived ids — they can be fully asserted against the mock now, without waiting on the URL-safe-id change. (Fixing the tag-id format here would additionally let a fixture drill children by id before attaching, but isn't a prerequisite.)

Consumers that need this to test end-to-end against the mock:

• elmo §5.3.5 prompt authoring — adobe/project-elmo-ui#2245
• api-service prompt-tag /serenity/* wrappers — flagged on feat(serenity): consume nested AIO tags (parentId create, tree read, PATCH re-parent) spacecat-api-service#2737 (follow-up under serenity: nested category tags (parent_id) — transport, create-tag parent, hierarchy-preserving read-merge spacecat-api-service#2733)
• mysticat-data-service migration §5.1.6 — adobe/mysticat-data-service#737

Happy to fold this into this issue's scope or split it into a sibling issue — whichever you prefer.

[rainer-friederich]

Closed with #1764