feat(brands): self-serve activate-brand endpoint | LLMO-5605

[igor-grubic]

1. Abstract

Adds POST /v2/orgs/{spaceCatId}/brands/{brandId}/activate — the explicit, customer-triggered "make this brand live" action: resolves the onboarded primary site, sets the brand active with baseSiteId in the same write, optionally generates AI prompts, and ensures the recurring brand-presence schedule. LLMO-5605, Piece 2.

2. Reasoning

Piece 2 of self-serve domain onboarding (LLMO-3749 / LLMO-5605). After Piece 1 stands up the site entity, the customer needs an explicit action to activate a (e.g. pending) brand whose primary URL is already onboarded — optionally kicking off AI-prompt generation and the recurring brand-presence schedule.

3. High-level overview of the changes

New endpoint POST /v2/orgs/{spaceCatId}/brands/{brandId}/activate. For an existing (e.g. pending) brand whose primary URL is already onboarded:

1. Resolve the onboarded primary Site → set the brand active with baseSiteId in the same write (400 if no onboarded site; 409 on brands_base_site_unique).
2. If generatePrompts: submit a direct prompt_generation_base_url DRS job with source: 'brand-activation' (never Brandalf, never the llmo-customer-analysis cascade). Idempotent via an in-flight listJobs check.
3. Ensure the recurring brand-presence schedule only when prompts exist / are generated, via the shared createBrandPresenceSchedule helper (POST + tolerate 409).
4. Returns 200 quickly ({ brandId, status:'active', baseSiteId, promptGenerationJobId?, scheduleId? }); prompts generate async.

• Auth: membership (hasAccess) + explicit PAID entitlement (TierClient), mirroring Piece 1 — no admin requirement (decision: don't 403 paying non-admin members).
• OpenAPI specs (api.yaml / brands-v2-api.yaml / schemas.yaml) + generated docs updated; bumps @adobe/spacecat-shared-drs-client → 1.13.0.

4. Required information

• Jira / issue: LLMO-5605 — https://jira.corp.adobe.com/browse/LLMO-5605
• Spec: Piece 2 design spec — https://github.com/adobe/project-elmo-ui/issues/2095
• Other: Piece 1 spec — https://github.com/adobe/project-elmo-ui/issues/2092

5. Affected / used mysticat-workspace projects

• spacecat-shared (drs-client) — consumed: uses listJobs (dedup) + createBrandPresenceSchedule from 1.13.0 — feat(drs-client): add listJobs + createBrandPresenceSchedule | LLMO-5605 spacecat-shared#1721.
• llmo-data-retrieval-service (DRS) — depends-on (runtime): the (site, provider_id, source) dedup needs the source filter from https://github.com/adobe-rnd/llmo-data-retrieval-service/pull/2370 deployed.
• spacecat-audit-worker — contract / parallel: shares the createBrandPresenceSchedule helper with the llmo-customer-analysis cascade (fix(llmo-customer-analysis): create brand-presence schedule via shared drs-client helper | LLMO-5605 spacecat-audit-worker#2737); both must route through the same method to preserve DRS provider-set dedup.

7. Test plan

(a) Local — unit coverage for: same-write activate (200); generatePrompts: true → one prompt job + one schedule; false / no-prompts → neither; double-click idempotency; the 400 / 403 / 404 / 409 paths; and DRS-not-configured. Integration tests (test/it/) for the endpoint are still outstanding — CLAUDE.md requires IT for new endpoints; this is a pre-merge item.

(b) Per-env (dev / stage): activate a pending brand whose primary URL is onboarded → confirm status:'active' with baseSiteId set in one write; with generatePrompts:true confirm a single source:'brand-activation' prompt job and one brand-presence schedule (re-activate is idempotent — listJobs dedup + schedule 409 tolerated); with generatePrompts:false confirm neither is created; confirm a non-PAID or non-member caller is rejected.

8. Deployment & merge order

Final consumer in the LLMO-5605 Piece 2 chain.

• drs-client 1.13.0 (spacecat-shared) — released — feat(drs-client): add listJobs + createBrandPresenceSchedule | LLMO-5605 spacecat-shared#1721.
• llmo-data-retrieval-service source filter — depends-on (deploy): deploy to DRS before this endpoint's dedup discriminates by source — https://github.com/adobe-rnd/llmo-data-retrieval-service/pull/2370.
• spacecat-audit-worker anti-drift migration — related (parallel): keep both on the shared schedule helper — fix(llmo-customer-analysis): create brand-presence schedule via shared drs-client helper | LLMO-5605 spacecat-audit-worker#2737.
• This PR — coordinate: brands.js / routes/index.js overlap the open in-repo /status (feat(brands): add explicit brand status-transition endpoint (LLMO-5587) #2621) and demotion-guard (feat(brands): guard against active->pending demotion in updateBrand/upsertBrand (LLMO-5587) #2637) work; land after those merge to avoid conflicts. Remaining pre-merge item: the integration tests above.

Ordered sequence: drs-client 1.13.0 (done) + DRS source filter deployed → land after the in-repo /status + demotion-guard PRs → merge this endpoint; the audit-worker migration lands in parallel.

🤖 Generated with Claude Code

[MysticatBot]

Mysticat review failed: Claude CLI crashed (exit 1): stderr= stdout={"type":"result","subtype":"error_max_budget_usd","duration_ms":5,"duration_api_ms":1694089,"is_error":true,"num_turns":1,"stop_reason":null,"session_id":"6122fae3-68a9-48bb-90ae-a503adffa0c8","total_cost_usd":12.047866350000003,"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_i

[MysticatBot]

Mysticat review failed: Claude CLI crashed (exit 1): stderr= stdout={"type":"result","subtype":"error_max_budget_usd","duration_ms":3,"duration_api_ms":1799198,"is_error":true,"num_turns":1,"stop_reason":null,"session_id":"637454f6-7c99-43b2-8e09-a0d743e3fdce","total_cost_usd":11.398289300000004,"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_i

[github-actions]

This PR will trigger a minor release when merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!