@dainamite/cpq 0.2.2

package/src/modules/cpq/__integration__/TC-CPQ-ARC-006.spec.ts

@@ -0,0 +1,79 @@
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import {
+  seedActiveSubscription,
+  seedCustomer,
+  deleteSubscription,
+  deleteCustomer,
+  hideFloatingOverlays,
+} from './_helpers/cpqArcFixtures'
+
+/**
+ * TC-CPQ-ARC-006 — Concurrent ARC quote rejection + redirect-on-confirm (UI) (XD-250)
+ *
+ * Operator opens Amend on subscription S → quote Q1 created. While Q1 is
+ * still in non-terminal status, the operator returns to S and clicks "Amend"
+ * again. The second attempt is rejected server-side (409); the UI surfaces
+ * the conflict via a window.confirm() carrying the 409 message and offers
+ * to navigate to the existing quote. Spec § UI Integration "Existing-quote
+ * redirect": clicking OK navigates to the conflicting Q1.
+ */
+test.describe('TC-CPQ-ARC-006 — Concurrent ARC rejection + redirect (UI)', () => {
+  test('second Amend on a subscription already on a non-terminal ARC quote prompts and redirects to it', async ({
+    page,
+    request,
+  }) => {
+    const token = await getAuthToken(request, 'admin')
+    const customerId = await seedCustomer(request, token)
+    const sub = await seedActiveSubscription(request, token, { customerId, name: 'Conflict Sub' })
+
+    try {
+      await login(page, 'admin')
+
+      // 1st Amend — succeeds. Capture the resulting quote URL so we can
+      // assert the redirect lands on the same one. We must wait for the URL
+      // to actually change to /backend/cpq/quotes/<...> before snapshotting
+      // it — body-text assertions can pass on the source subscription page
+      // (which also contains sub.code) before router.push() completes.
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+      await page.getByRole('button', { name: /^Amend$/ }).click()
+      await page.waitForURL(/\/backend\/cpq\/quotes\/[0-9a-f-]+$/, { timeout: 15_000 })
+      await expect(page.locator('body')).toContainText(sub.code, { timeout: 10_000 })
+      const firstQuoteUrl = new URL(page.url())
+      const firstQuoteId = firstQuoteUrl.pathname.split('/').pop()
+      expect(firstQuoteId).toBeTruthy()
+
+      // 2nd Amend on the same sub — should trigger window.confirm() with
+      // the conflict message + an offer to open the existing quote.
+      // Accept the dialog → page should navigate back to the first quote.
+      let confirmMessage: string | null = null
+      page.once('dialog', async (dialog) => {
+        confirmMessage = dialog.message()
+        // Click OK → component should router.push(/backend/cpq/quotes/<existingId>).
+        await dialog.accept()
+      })
+
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+      await page.getByRole('button', { name: /^Amend$/ }).click()
+
+      // Wait for the confirm to have surfaced.
+      await expect.poll(() => confirmMessage, { timeout: 10_000 }).not.toBeNull()
+      expect(confirmMessage).toMatch(/in progress|already|existing/i)
+      // And the message should include an "Open the existing quote" prompt.
+      expect(confirmMessage).toMatch(/Open the existing quote/i)
+
+      // After accepting the confirm, the page should land on the first quote.
+      await expect.poll(() => page.url(), { timeout: 10_000 }).toContain(firstQuoteId!)
+    } finally {
+      await deleteSubscription(request, token, sub.id).catch(() => undefined)
+      await deleteCustomer(request, token, customerId).catch(() => undefined)
+    }
+  })
+})

package/src/modules/cpq/__integration__/TC-CPQ-ARC-007.spec.ts

@@ -0,0 +1,63 @@
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import {
+  seedActiveSubscription,
+  seedCustomer,
+  daysFromNow,
+  deleteSubscription,
+  deleteCustomer,
+  hideFloatingOverlays,
+} from './_helpers/cpqArcFixtures'
+
+/**
+ * TC-CPQ-ARC-007 — Renew from subscription detail (UI) (XD-250 scenario 3)
+ *
+ * The standalone /expiring page was retired (commit fa5b899) — the Renew
+ * action moved onto the subscription detail page header. This test now
+ * navigates straight to the expiring subscription's detail and clicks
+ * Renew there. The "expiring" angle is preserved by seeding with
+ * currentTermEnd inside the 30d window so the sub would have appeared on
+ * the deprecated view; the renewal flow is identical regardless.
+ */
+test.describe('TC-CPQ-ARC-007 — Renew from subscription detail (UI)', () => {
+  test('Renew on an expiring sub creates a RENEW quote with the source as the only target', async ({
+    page,
+    request,
+  }) => {
+    const token = await getAuthToken(request, 'admin')
+    const customerId = await seedCustomer(request, token)
+    const sub = await seedActiveSubscription(request, token, {
+      customerId,
+      name: 'Expiring Soon — for renew',
+      currentTermEnd: daysFromNow(20),
+    })
+
+    try {
+      await login(page, 'admin')
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+
+      // Subscription detail loads — its name is visible in the header.
+      await expect(page.locator('body')).toContainText(sub.name, { timeout: 15_000 })
+
+      // Click the Renew button in the FormHeader actions row.
+      await page.getByRole('button', { name: /^Renew$/ }).first().click()
+
+      // After click, startArcQuote('renew') POSTs from-subscription then
+      // router.push()es to the new quote. Wait for URL transition.
+      await page.waitForURL(/\/backend\/cpq\/quotes\/[0-9a-f-]+$/, { timeout: 15_000 })
+      await expect(page.locator('body')).toContainText(sub.code, { timeout: 10_000 })
+      // ARC banner shows "RENEW • 1 target: <code>" — DOM stores lowercase
+      // 'renew' under a CSS uppercase rule, so `getByText` regex must use the
+      // case-insensitive flag.
+      await expect(page.getByText(/1 target/i).first()).toBeVisible({ timeout: 5_000 })
+      await expect(page.getByText(/renew/i).first()).toBeVisible({ timeout: 5_000 })
+    } finally {
+      await deleteSubscription(request, token, sub.id).catch(() => undefined)
+      await deleteCustomer(request, token, customerId).catch(() => undefined)
+    }
+  })
+})

package/src/modules/cpq/__integration__/TC-CPQ-ARC-008.spec.ts

@@ -0,0 +1,62 @@
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import {
+  seedSubscriptionInStatus,
+  seedCustomer,
+  deleteSubscription,
+  deleteCustomer,
+  hideFloatingOverlays,
+} from './_helpers/cpqArcFixtures'
+
+/**
+ * TC-CPQ-ARC-008 — ARC on suspended subscription (UI) (XD-250 scenario 6, DD-ARC)
+ *
+ * Spec § DD-ARC: amend / standalone-renew / cancel work on suspended subs
+ * without first reactivating. The action row in the subscription detail
+ * header MUST render for status ∈ {active, suspended} — only terminal
+ * statuses hide it. This test seeds a suspended sub, asserts the buttons
+ * are rendered, opens Amend, and verifies the resulting quote attaches the
+ * suspended sub as a target.
+ */
+test.describe('TC-CPQ-ARC-008 — ARC on suspended subscription (UI)', () => {
+  test('suspended sub still shows ARC buttons; Amend works and quote attaches it', async ({
+    page,
+    request,
+  }) => {
+    const token = await getAuthToken(request, 'admin')
+    const customerId = await seedCustomer(request, token)
+    const sub = await seedSubscriptionInStatus(
+      request,
+      token,
+      { customerId, name: 'Suspended sub for ARC' },
+      'suspended',
+    )
+
+    try {
+      await login(page, 'admin')
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+
+      // Status badge confirms suspended; all three ARC buttons must render.
+      await expect(page.locator('body')).toContainText(/suspended/i, { timeout: 15_000 })
+      const amendBtn = page.getByRole('button', { name: /^Amend$/ })
+      const renewBtn = page.getByRole('button', { name: /^Renew$/ })
+      const cancelBtn = page.getByRole('button', { name: /^Cancel$/ })
+      await expect(amendBtn).toBeVisible()
+      await expect(renewBtn).toBeVisible()
+      await expect(cancelBtn).toBeVisible()
+
+      // Click Amend → fresh quote with the suspended sub as target.
+      await amendBtn.click()
+      await page.waitForURL(/\/backend\/cpq\/quotes\/[0-9a-f-]+$/, { timeout: 15_000 })
+      await expect(page.locator('body')).toContainText(sub.code, { timeout: 10_000 })
+      await expect(page.getByText(/1 target/i).first()).toBeVisible({ timeout: 5_000 })
+    } finally {
+      await deleteSubscription(request, token, sub.id).catch(() => undefined)
+      await deleteCustomer(request, token, customerId).catch(() => undefined)
+    }
+  })
+})

package/src/modules/cpq/__integration__/TC-CPQ-ARC-009.spec.ts

@@ -0,0 +1,62 @@
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import {
+  seedSubscriptionInStatus,
+  seedCustomer,
+  deleteSubscription,
+  deleteCustomer,
+  hideFloatingOverlays,
+} from './_helpers/cpqArcFixtures'
+
+/**
+ * TC-CPQ-ARC-009 — Terminal-status subscriptions hide ARC buttons (UI) (XD-250 scenario 7)
+ *
+ * Spec § UI Integration: the action row only renders when status ∈
+ * {active, suspended}. Terminal statuses (`expired`, `terminated`,
+ * `superseded`) MUST NOT show Amend / Renew / Cancel buttons. This test
+ * verifies the gate for both `terminated` and `expired`.
+ */
+test.describe('TC-CPQ-ARC-009 — Terminal-status subs hide ARC buttons (UI)', () => {
+  for (const status of ['terminated', 'expired'] as const) {
+    test(`${status} sub renders status badge but no ARC action buttons`, async ({
+      page,
+      request,
+    }) => {
+      const token = await getAuthToken(request, 'admin')
+      const customerId = await seedCustomer(request, token)
+      const sub = await seedSubscriptionInStatus(
+        request,
+        token,
+        { customerId, name: `${status} sub for ARC gate` },
+        status,
+      )
+
+      try {
+        await login(page, 'admin')
+        await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+          waitUntil: 'domcontentloaded',
+        })
+        await hideFloatingOverlays(page)
+
+        await expect(page.locator('body')).toContainText(new RegExp(status, 'i'), {
+          timeout: 15_000,
+        })
+
+        // ARC buttons must not be present.
+        await expect(page.getByRole('button', { name: /^Amend$/ })).toHaveCount(0)
+        await expect(page.getByRole('button', { name: /^Renew$/ })).toHaveCount(0)
+        // Note: there is a "Cancel" item-detail button elsewhere, but the
+        // header-level Cancel ARC button is what we're guarding against.
+        // Anchor by parent role — the action row sits inside the page
+        // header, while item-row Cancels live inside item cards.
+        const headerCancelButtons = page.locator('header, [role="banner"]')
+          .getByRole('button', { name: /^Cancel$/ })
+        await expect(headerCancelButtons).toHaveCount(0)
+      } finally {
+        await deleteSubscription(request, token, sub.id).catch(() => undefined)
+        await deleteCustomer(request, token, customerId).catch(() => undefined)
+      }
+    })
+  }
+})

package/src/modules/cpq/__integration__/TC-CPQ-ARC-010.spec.ts

@@ -0,0 +1,59 @@
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import {
+  seedActiveSubscription,
+  seedCustomer,
+  deleteSubscription,
+  deleteCustomer,
+  hideFloatingOverlays,
+} from './_helpers/cpqArcFixtures'
+
+/**
+ * TC-CPQ-ARC-010 — Change History "Created" seed entry (UI) (XD-250 scenario 10)
+ *
+ * Commit fa5b899 made `createSubscription` write a `created` row into
+ * `CpqSubscriptionChangeLog` so the history panel is never empty —
+ * operators always see where the subscription came from before any
+ * ARC operation. This test verifies:
+ *   - Change History renders with one row (the "Created" seed)
+ *   - the row is tagged "Created" rather than "Amended" / "Renewed" / etc.
+ */
+test.describe('TC-CPQ-ARC-010 — Change History seeded with Created (UI)', () => {
+  test('fresh subscription renders Change History (1) with a "Created" entry', async ({
+    page,
+    request,
+  }) => {
+    const token = await getAuthToken(request, 'admin')
+    const customerId = await seedCustomer(request, token)
+    const sub = await seedActiveSubscription(request, token, {
+      customerId,
+      name: 'Fresh sub — seeded Created entry',
+    })
+
+    try {
+      await login(page, 'admin')
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+
+      const heading = page.getByRole('heading', { name: /Change History/i })
+      await expect(heading).toBeVisible({ timeout: 15_000 })
+      // Subscription was just created → exactly one log row.
+      await expect(heading).toContainText('(1)')
+      // Scope the "Created" lookup to the Change History container so
+      // the assertion can't accidentally match the "Created" Field
+      // label on the Pricing & References meta card above.
+      const historySection = page
+        .locator('div', { has: heading })
+        .first()
+      await expect(historySection.getByText(/^Created$/).first()).toBeVisible({
+        timeout: 5_000,
+      })
+    } finally {
+      await deleteSubscription(request, token, sub.id).catch(() => undefined)
+      await deleteCustomer(request, token, customerId).catch(() => undefined)
+    }
+  })
+})

package/src/modules/cpq/__integration__/TC-CPQ-ARC-011.spec.ts

@@ -0,0 +1,128 @@
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import {
+  seedActiveSubscription,
+  seedCustomer,
+  deleteSubscription,
+  deleteCustomer,
+  hideFloatingOverlays,
+} from './_helpers/cpqArcFixtures'
+
+/**
+ * TC-CPQ-ARC-011 — Full ARC lifecycle: amend → approval → convert → activate (UI + API hybrid)
+ * (XD-250 scenario 11)
+ *
+ * The longest manual scenario: an amend quote is driven through the full
+ * approval ladder, converted to an order, and activated. Activation runs
+ * `cpqInventoryService.applyAmendment()` which writes a `CpqSubscriptionChangeLog`
+ * row + emits `cpq.subscription.amended`. We assert UI at the entry points
+ * (Amend button on the sub, Activate button on the order — renamed in
+ * commit 720db2b) and at the exit (Change History (2) on the source sub:
+ * one seeded `Created` row + one `Amended` row from the activation) and
+ * drive the approval lifecycle / convert via API to keep the test stable.
+ */
+test.describe('TC-CPQ-ARC-011 — Full ARC lifecycle (UI + API hybrid)', () => {
+  test('amend → drive through statuses → convert → activate → Change History (Created + Amended)', async ({
+    page,
+    request,
+  }) => {
+    const token = await getAuthToken(request, 'admin')
+    const customerId = await seedCustomer(request, token)
+    const sub = await seedActiveSubscription(request, token, {
+      customerId,
+      name: 'Lifecycle target',
+      items: [{ name: 'Premium Tier', mrcAmount: 250 }],
+    })
+
+    try {
+      await login(page, 'admin')
+
+      // 1. UI — click Amend on the source sub. Captures the new quote id.
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+      await page.getByRole('button', { name: /^Amend$/ }).click()
+      await page.waitForURL(/\/backend\/cpq\/quotes\/[0-9a-f-]+$/, { timeout: 15_000 })
+      const quoteId = page.url().split('/').pop()!
+      expect(quoteId).toMatch(/^[0-9a-f-]+$/)
+
+      // 2. API — drive quote through approval ladder. The API path was
+      // exercised manually for each transition; we just need an `accepted`
+      // quote so Convert to Order unlocks.
+      const transitions = [
+        'ready',
+        'in_approval',
+        'approved',
+        'with_customer',
+        'accepted',
+      ]
+      for (const target of transitions) {
+        const res = await apiRequest(
+          request,
+          'POST',
+          `/api/cpq/quotes/${quoteId}/status`,
+          { token, data: { targetStatus: target } },
+        )
+        expect(
+          res.ok(),
+          `transition to ${target} returned ${res.status()}: ${await res.text()}`,
+        ).toBeTruthy()
+      }
+
+      // 3. API — convert quote to order. POST /api/cpq/orders with quoteId.
+      const convertRes = await apiRequest(request, 'POST', '/api/cpq/orders', {
+        token,
+        data: { quoteId },
+      })
+      expect(
+        convertRes.ok(),
+        `convert returned ${convertRes.status()}: ${await convertRes.text()}`,
+      ).toBeTruthy()
+      const order = (await convertRes.json()) as { id: string }
+      expect(order.id).toBeTruthy()
+
+      // 4. UI — open the order detail and click Activate Order. This is the
+      // critical mutation point: the API endpoint creates ChangeLog rows /
+      // updates the subscription, but the manual instructs operators to
+      // press the green button so we cover the same path here.
+      await page.goto(`/backend/cpq/orders/${order.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+      // Button renamed to "Activate" in commit 720db2b (entity context is
+      // already in the FormHeader eyebrow, so the verb stands alone).
+      const activateBtn = page.getByRole('button', { name: /^Activate$/ })
+      await expect(activateBtn).toBeVisible({ timeout: 15_000 })
+      await activateBtn.click()
+
+      // Wait for activation to complete — order status flips to 'active' and
+      // the green success banner appears.
+      await expect(page.locator('body')).toContainText(/active/i, { timeout: 30_000 })
+
+      // 5. UI — return to the source sub. Expect Change History (2):
+      //    - the seeded `Created` row (commit fa5b899)
+      //    - the `Amended` row written by activation
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, {
+        waitUntil: 'domcontentloaded',
+      })
+      await hideFloatingOverlays(page)
+      const heading = page.getByRole('heading', { name: /Change History/i })
+      await expect(heading).toBeVisible({ timeout: 15_000 })
+      // Poll the count text — the change-log fetch is async and can race
+      // with the heading's first paint.
+      await expect.poll(async () => (await heading.textContent()) ?? '', {
+        timeout: 15_000,
+      }).toMatch(/\(2\)/)
+      // Scope tag lookups to the Change History container so the
+      // "Created" tag isn't confused with the meta-card "Created" label.
+      const historySection = page.locator('div', { has: heading }).first()
+      await expect(historySection.getByText(/^Amended$/).first()).toBeVisible({ timeout: 5_000 })
+      await expect(historySection.getByText(/^Created$/).first()).toBeVisible({ timeout: 5_000 })
+    } finally {
+      await deleteSubscription(request, token, sub.id).catch(() => undefined)
+      await deleteCustomer(request, token, customerId).catch(() => undefined)
+    }
+  })
+})

package/src/modules/cpq/__integration__/_helpers/cpqArcFixtures.ts

@@ -0,0 +1,208 @@
+import { expect, type APIRequestContext, type Page } from '@playwright/test'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { createCompanyFixture } from '@open-mercato/core/helpers/integration/crmFixtures'
+
+/**
+ * XD-250 ARC integration test fixtures.
+ *
+ * Test setup helpers (subscription / customer creation) go through the
+ * CPQ inventory + customers REST APIs because building a real subscription
+ * end-to-end via the new-sale UI flow per test would be enormous. The
+ * actual ARC behaviour under test still drives the UI (drawer, status
+ * transitions, change history) — only the *prerequisite state* is API.
+ */
+
+export const uniq = (): string =>
+  Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+export interface SeededSubscription {
+  id: string
+  customerId: string
+  code: string
+  name: string
+  currencyCode: string
+  billingCycle: string
+  mrcAmount: string
+  currentTermEnd: string | null
+}
+
+export interface SeedSubscriptionInput {
+  customerId: string
+  name?: string
+  code?: string
+  billingCycle?: 'monthly' | 'quarterly' | 'annually'
+  currencyCode?: string
+  mrcAmount?: number
+  /** ISO date — sets currentTermEnd via PUT after creation. */
+  currentTermEnd?: string
+  termMonths?: number
+  /** Pre-seed at least one item; subscription schema requires items.min(1). */
+  items?: Array<{
+    name: string
+    mrcAmount?: number
+    nrcAmount?: number
+  }>
+}
+
+/**
+ * Creates a customer (company) and returns its id.
+ */
+export async function seedCustomer(
+  request: APIRequestContext,
+  token: string,
+  displayName?: string,
+): Promise<string> {
+  return createCompanyFixture(request, token, displayName ?? `ARC-Test-Co-${uniq()}`)
+}
+
+/**
+ * Creates a subscription, transitions it to active, optionally sets the
+ * current term end (used by Expiring view test). Returns enough metadata
+ * for the test to navigate by id and assert by code.
+ */
+export async function seedActiveSubscription(
+  request: APIRequestContext,
+  token: string,
+  input: SeedSubscriptionInput,
+): Promise<SeededSubscription> {
+  const code = input.code ?? `SUB-${uniq().toUpperCase()}`
+  const name = input.name ?? `ARC Test Subscription ${uniq()}`
+  const items = input.items ?? [{ name: 'Default Item', mrcAmount: input.mrcAmount ?? 100 }]
+
+  const createRes = await apiRequest(request, 'POST', '/api/cpq/inventory/subscriptions', {
+    token,
+    data: {
+      customerId: input.customerId,
+      code,
+      name,
+      billingCycle: input.billingCycle ?? 'monthly',
+      currencyCode: input.currencyCode ?? 'USD',
+      termMonths: input.termMonths ?? 12,
+      items,
+    },
+  })
+  expect(
+    createRes.ok(),
+    `subscription POST returned ${createRes.status()}: ${await createRes.text()}`,
+  ).toBeTruthy()
+  const created = (await createRes.json()) as { id: string; code: string; name: string; currencyCode: string; billingCycle: string; mrcAmount: string }
+
+  // Pending → active.
+  const transitionRes = await apiRequest(
+    request,
+    'POST',
+    '/api/cpq/inventory/subscriptions/status',
+    {
+      token,
+      data: { id: created.id, targetStatus: 'active' },
+    },
+  )
+  expect(
+    transitionRes.ok(),
+    `status transition returned ${transitionRes.status()}: ${await transitionRes.text()}`,
+  ).toBeTruthy()
+
+  // Optional: stamp currentTermEnd via PUT for the Expiring view test.
+  if (input.currentTermEnd) {
+    const updateRes = await apiRequest(request, 'PUT', '/api/cpq/inventory/subscriptions', {
+      token,
+      data: { id: created.id, currentTermEnd: input.currentTermEnd },
+    })
+    expect(
+      updateRes.ok(),
+      `subscription PUT returned ${updateRes.status()}: ${await updateRes.text()}`,
+    ).toBeTruthy()
+  }
+
+  return {
+    id: created.id,
+    customerId: input.customerId,
+    code: created.code,
+    name: created.name,
+    currencyCode: created.currencyCode,
+    billingCycle: created.billingCycle,
+    mrcAmount: created.mrcAmount,
+    currentTermEnd: input.currentTermEnd ?? null,
+  }
+}
+
+/**
+ * Creates a subscription, takes it to `active`, then transitions to the
+ * given non-active status (`suspended` / `terminated` / `expired`). Used by
+ * the ARC suspended-target test (scenario 6) and the terminal-status
+ * negative test (scenario 7) where ARC buttons must not render.
+ */
+export async function seedSubscriptionInStatus(
+  request: APIRequestContext,
+  token: string,
+  input: SeedSubscriptionInput,
+  status: 'suspended' | 'terminated' | 'expired',
+): Promise<SeededSubscription> {
+  const sub = await seedActiveSubscription(request, token, input)
+  const res = await apiRequest(
+    request,
+    'POST',
+    '/api/cpq/inventory/subscriptions/status',
+    { token, data: { id: sub.id, targetStatus: status } },
+  )
+  expect(
+    res.ok(),
+    `transition to ${status} returned ${res.status()}: ${await res.text()}`,
+  ).toBeTruthy()
+  return sub
+}
+
+/**
+ * Cleanup: soft-delete created subscriptions, swallow errors so teardown
+ * never aborts subsequent cleanup.
+ */
+export async function deleteSubscription(
+  request: APIRequestContext,
+  token: string,
+  id: string,
+): Promise<void> {
+  await apiRequest(request, 'DELETE', '/api/cpq/inventory/subscriptions', {
+    token,
+    data: { id },
+  }).catch(() => undefined)
+}
+
+export async function deleteCustomer(
+  request: APIRequestContext,
+  token: string,
+  id: string,
+): Promise<void> {
+  await apiRequest(request, 'DELETE', '/api/customers/companies', {
+    token,
+    data: { id },
+  }).catch(() => undefined)
+}
+
+/**
+ * Compute an ISO date (YYYY-MM-DD) `daysFromNow` days into the future. Used
+ * by the Expiring view test to build subscriptions with predictable
+ * term-end dates. Always returns the UTC calendar date — runner timezone
+ * doesn't affect the ±1 day boundary that the 30/90-day window asserts on.
+ * Negative values are accepted (returns a past date).
+ */
+export function daysFromNow(days: number): string {
+  return new Date(Date.now() + days * 24 * 60 * 60 * 1000).toISOString().split('T')[0]
+}
+
+/**
+ * Hide globally floating widgets (Feedback FAB, Next.js dev toolbar) so they
+ * don't intercept clicks on drawer / page buttons. Safe to call multiple times.
+ */
+export async function hideFloatingOverlays(page: Page): Promise<void> {
+  await page
+    .addStyleTag({
+      content: `
+        button[aria-label="Open feedback form"],
+        nextjs-portal,
+        [data-nextjs-toast-wrapper] {
+          display: none !important;
+        }
+      `,
+    })
+    .catch(() => undefined)
+}