feat(serenity): expose semrush provisioning status on brand reads (LLMO-7352/LLMO-7418)

[IrisAlexandrescu]

Summary

Fifth and last in the stack (base: #3249). Small, focused prerequisite for the frontend UI-states work (LLMO-7419, adobe/project-elmo-ui#3128): surfaces brands.semrush_provisioning_status / semrush_provisioning_error as read-only semrushProvisioningStatus / semrushProvisioningError on the V2 Brand DTO.

Why this PR exists: those two columns previously existed only for the async provisioning worker's own internal CAS bookkeeping (getBrandProvisioningState's narrow PROVISIONING_SELECT) — no GET response exposed them. Without this the frontend cannot show a persistent "Setting up / Ready / Setup failed" indicator on the brand list or detail view; it would have to rely on the one-shot jobId an async: true response carries, which is useless on any later page load.

Changes

• mapDbBrandToV2 (src/support/brands-storage.js) — the single mapping point for all 3 GET paths (listBrandsForOrg / getBrandForOrg / getBrandForOrgSite) and the create/update write-response paths (all route through withSerenityState) — now copies the two columns onto the DTO. No SELECT changes needed: PostgREST's '*' already returns every brands column.
• V2Brand in docs/openapi/schemas.yaml — both fields added as readOnly, nullable, not in required.

Test plan

• npm run lint, npm run type-check, npm run docs:lint — clean
• 1827 passing across serenity, brands, brands-storage and the handlers
• Unit test asserting both the failed-with-error case and the null/never-provisioned case
• Rebased onto current main

Related Issues

• LLMO-7352 / LLMO-7418
• Consumer: adobe/project-elmo-ui#3128 (LLMO-7419)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[IrisAlexandrescu]

Rebased onto Phase 4's (#3249) fix commit — no changes needed in this PR itself, the fixed activate-brand-workspace-job.js behavior now carries through automatically.

[github-actions]

This PR will trigger a minor release when merged.

[luis6156]

Clean, minimal, correct. The single mapping point (mapDbBrandToV2) covers all three GET paths simultaneously, no SELECT changes needed since PostgREST's '*' already returns every column, and the "Null unless semrushProvisioningStatus is failed" comment is a DB-level guarantee (confirmed: beginProvisioningAttempt explicitly writes semrush_provisioning_error: null in its UPDATE, so a successful retry atomically clears any prior error). Two small items:

---

Finding 1 — Test coverage missing pending and ready states

The test exercises failed-with-error and null (never provisioned), but the two states the frontend UI actually renders differently are pending (show "Setting up..." spinner) and ready (silent success). Adding cases for both would ensure a future rename of an enum value or a mapping typo doesn't go undetected:

it('maps semrush_provisioning_status: pending and ready', async () => {
  for (const status of ['pending', 'ready']) {
    const row = makeBrandRow({ semrush_provisioning_status: status });
    const query = createChainableQuery({ data: row, error: null });
    const result = await getBrandById(ORG_ID, BRAND_ID, { from: sinon.stub().returns(query) });
    expect(result.semrushProvisioningStatus).to.equal(status);
    expect(result.semrushProvisioningError).to.equal(null); // error only set on failed
  }
});

---

Finding 2 — OpenAPI description doesn't explain the null / ready distinction for clients

The semrushProvisioningStatus description says "show a persistent Setting-up/Ready/Setup-failed indicator without relying on … jobId" but doesn't tell a reader what each value means from the client side. The null vs ready split is particularly subtle: both mean "workspace is usable", but null indicates a brand that went through the sync path (or predates async provisioning) while ready indicates an async-provisioned brand. A frontend developer implementing LLMO-7419 should not need to read the provisioning worker source to know this.

Suggested description:

semrushProvisioningStatus:
  description: >-
    Read-only: the brand's async Semrush provisioning state.
    `pending` — a provisioning attempt is in flight; the client should
    show a "Setting up" indicator and may poll the job status via `jobId`.
    `ready` — async provisioning completed successfully.
    `failed` — the last attempt failed; see `semrushProvisioningError` for detail.
    `null` — the brand was created via the sync path or before async
    provisioning was introduced; no active provisioning issue.
    For display purposes, treat both `null` and `ready` as "workspace available".

The four-state breakdown also confirms the OpenAPI enum [pending, ready, failed, null] is complete.

[luis6156]

Review — feat(serenity): expose semrush provisioning status on brand reads

Clean and focused. The single-mapping-point strategy (mapDbBrandToV2 covers all three GET paths and the write-response path via withSerenityState) is correct, and no SELECT/query changes are needed since PostgREST's '*' already returns every column.

---

null vs ready semantics

The OpenAPI description correctly documents the distinction: null = synchronous create or predates async provisioning; ready = async-provisioned workspace confirmed created. Worth confirming with the frontend that they treat both as "workspace available" — the description now states this plainly ("clients should treat null and ready as equivalent for display"), but the UI rendering code is the authoritative check.

---

Non-Semrush / flat-mode brands

semrushProvisioningStatus will always be null for flat-mode organizations since the provisioning columns are never written for them. The OpenAPI schema marks the field nullable and not required, which is correct. One thing worth noting for frontend consumers: null can mean either "synchronous Semrush brand" or "non-Semrush brand" — a flat-mode client should treat null as "not applicable" rather than "provisioning status unknown." The current description says null and ready are equivalent for display, which is accurate for the Semrush case but could mislead a flat-mode consumer into polling for a status that will never change. A clarifying note ("for non-Semrush organizations this field is always null") in the schema description would close that ambiguity.

Non-blocking. Approving.