feat(usage): Show usage against the plan limit for the current billing period

frontend/common/types/requests.ts

@@ -74,7 +74,10 @@ export enum PermissionRoleType {
   GRANTED_FOR_TAGS = 'GRANTED_FOR_TAGS',
   NONE = 'NONE',
 }
-export const billingPeriods = [
+export type BillingPeriod = Req['getOrganisationUsage']['billing_period']
+export type PeriodOption = { label: string; value: BillingPeriod }
+
+export const periodOptions: PeriodOption[] = [
   {
     label: 'Current billing period',
     value: 'current_billing_period',
@@ -86,7 +89,7 @@ export const billingPeriods = [
   { label: 'Last 90 days', value: '90_day_period' },
   { label: 'Last 30 days', value: undefined },
 ]
-export const freePeriods = [
+export const rollingPeriodOptions: PeriodOption[] = [
   { label: 'Last 90 days', value: '90_day_period' },
   { label: 'Last 30 days', value: undefined },
 ]

frontend/common/types/responses.ts

@@ -514,6 +514,7 @@ export type Subscription = {
   customer_id: string
   payment_method: string
   notes: string | null
+  has_active_billing_periods: boolean
 }
 
 export type OnboardingVariant = 'control' | 'single_page'

frontend/common/utils/__tests__/format.test.ts

@@ -12,6 +12,12 @@ describe('Format', () => {
       ${1234}          | ${'1.2K'}
       ${12345}         | ${'12.3K'}
       ${123456}        | ${'123.5K'}
+      ${0}             | ${'0'}
+      ${undefined}     | ${'0'}
+      ${null}          | ${'0'}
+      ${NaN}           | ${'0'}
+      ${Infinity}      | ${'0'}
+      ${-Infinity}     | ${'0'}
     `('shortenNumber($input) returns $expected', ({ expected, input }) => {
       expect(Format.shortenNumber(input)).toBe(expected)
     })

frontend/common/utils/format.ts

@@ -4,6 +4,8 @@ type Person = {
   email?: string
 }
 
+type NullableNumber = number | null | undefined
+
 const Format = {
   camelCase(val: string): string {
     // hello world > Hello world
@@ -39,9 +41,14 @@ const Format = {
 
   newLineDelimiter: '↵',
 
-  shortenNumber(number: number): string {
+  shortenNumber(number: NullableNumber): string {
     // Converts a float number into a short literal with suffix for the magnitude:
     // 1523125 > 1.5M
+    // Guarded because the maths below takes log10 of the value, so zero and
+    // anything missing come back as NaN.
+    if (!number || !Number.isFinite(number)) {
+      return '0'
+    }
     const suffixes = ['', 'K', 'M', 'B', 'T']
     const numDigits = Math.floor(Math.log10(number)) + 1
     const suffixIndex = Math.floor((numDigits - 1) / 3)

frontend/documentation/components/UsageBar.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from 'storybook'
+import UsageBar from 'components/shared/UsageBar'
+
+const meta: Meta<typeof UsageBar> = {
+  component: UsageBar,
+  parameters: { layout: 'padded' },
+  title: 'Components/Data Display/UsageBar',
+}
+export default meta
+
+type Story = StoryObj<typeof UsageBar>
+
+export const WithLabel: Story = {
+  args: { label: 'Segment overrides', limit: 100, usage: 42 },
+}
+
+export const Warning: Story = {
+  args: { label: 'Segment overrides', limit: 100, usage: 91 },
+}
+
+export const OverTheLimit: Story = {
+  args: { label: 'Segment overrides', limit: 100, usage: 118 },
+}
+
+// Thresholds are marked on the bar, for usage that is notified at set points.
+export const WithThresholds: Story = {
+  args: {
+    ariaLabel: 'Plan usage this period',
+    limit: 2000000,
+    thresholds: [75, 100],
+    usage: 1240000,
+    warnAt: 75,
+  },
+}
+
+export const WithThresholdsOverTheLimit: Story = {
+  args: {
+    ariaLabel: 'Plan usage this period',
+    limit: 50000,
+    thresholds: [75, 100],
+    usage: 68400,
+    warnAt: 75,
+  },
+}
+
+export const NoUsageYet: Story = {
+  args: { label: 'Segment overrides', limit: 100, usage: 0 },
+}

frontend/documentation/components/UsageDashboard.stories.tsx

@@ -0,0 +1,140 @@
+import type { Meta, StoryObj } from 'storybook'
+import { UsageDashboard } from 'components/pages/usage'
+import { Res } from 'common/types/responses'
+
+const meta: Meta<typeof UsageDashboard> = {
+  component: UsageDashboard,
+  parameters: { layout: 'fullscreen' },
+  title: 'Pages/Usage Dashboard/Page',
+}
+export default meta
+
+type Story = StoryObj<typeof UsageDashboard>
+
+const DAY_WEIGHTS = [1.08, 1.12, 1.05, 1.1, 0.98, 0.62, 0.58]
+
+const usage = (days: number, perDay: number): Res['organisationUsage'] => {
+  const events = Array.from({ length: days }).map((_, index) => {
+    const weight = DAY_WEIGHTS[index % DAY_WEIGHTS.length]
+    return {
+      day: `2026-08-${`${index + 1}`.padStart(2, '0')}`,
+      environment_document: Math.round(perDay * weight * 0.04),
+      flags: Math.round(perDay * weight * 0.63),
+      identities: Math.round(perDay * weight * 0.24),
+      labels: { user_agent: null },
+      traits: Math.round(perDay * weight * 0.09),
+    }
+  })
+  const sum = (
+    key: 'flags' | 'identities' | 'traits' | 'environment_document',
+  ) => events.reduce((acc, event) => acc + event[key], 0)
+
+  return {
+    events_list: events,
+    totals: {
+      environmentDocument: sum('environment_document'),
+      flags: sum('flags'),
+      identities: sum('identities'),
+      total:
+        sum('flags') +
+        sum('identities') +
+        sum('traits') +
+        sum('environment_document'),
+      traits: sum('traits'),
+    },
+  }
+}
+
+const paid = usage(18, 70000)
+const free = usage(30, 1800)
+const paidApproaching = usage(26, 75000)
+const paidOver = usage(28, 92000)
+
+// A plan with a billing term: usage climbs towards a reset, so it is drawn
+// cumulatively against the ceiling.
+export const PaidWithABillingPeriod: Story = {
+  args: {
+    data: paid,
+    hasBillingPeriod: true,
+    limit: 2000000,
+    total: paid.totals.total,
+  },
+}
+
+export const PaidApproachingTheLimit: Story = {
+  args: {
+    data: paidApproaching,
+    hasBillingPeriod: true,
+    limit: 2000000,
+    total: paidApproaching.totals.total,
+  },
+}
+
+export const PaidOverTheLimit: Story = {
+  args: {
+    data: paidOver,
+    hasBillingPeriod: true,
+    limit: 2000000,
+    total: paidOver.totals.total,
+  },
+}
+
+// No billing term, so no reset to accumulate towards: daily volume instead.
+export const FreeOnARollingWindow: Story = {
+  args: {
+    data: free,
+    hasBillingPeriod: false,
+    limit: 50000,
+    total: free.totals.total,
+  },
+}
+
+// Enterprise agreements are not billed through Chargebee, so they have a real
+// limit and no period. The meter still works; the chart falls back to volume.
+export const EnterpriseWithoutABillingPeriod: Story = {
+  args: {
+    data: paid,
+    hasBillingPeriod: false,
+    limit: 50000000,
+    total: paid.totals.total,
+  },
+}
+
+// Self-hosted has no subscription data at all, so there is nothing to be a
+// percentage of.
+export const WithoutAPlanLimit: Story = {
+  args: {
+    data: paid,
+    hasBillingPeriod: false,
+    limit: null,
+    total: paid.totals.total,
+  },
+}
+
+export const NoUsageYet: Story = {
+  args: {
+    data: usage(0, 0),
+    hasBillingPeriod: true,
+    limit: 2000000,
+    total: 0,
+  },
+}
+
+export const Loading: Story = {
+  args: {
+    hasBillingPeriod: true,
+    isLoading: true,
+    limit: 2000000,
+    total: 0,
+  },
+}
+
+/** Distinct from NoUsageYet, which would otherwise look identical. */
+export const FailedToLoad: Story = {
+  args: {
+    hasBillingPeriod: true,
+    isError: true,
+    limit: 2000000,
+    total: 0,
+  },
+}

frontend/documentation/components/UsageMeter.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from 'storybook'
+import UsageMeter from 'components/pages/usage/components/UsageMeter'
+
+const meta: Meta<typeof UsageMeter> = {
+  component: UsageMeter,
+  parameters: { layout: 'padded' },
+  title: 'Pages/Usage Dashboard/Components/UsageMeter',
+}
+export default meta
+
+type Story = StoryObj<typeof UsageMeter>
+
+export const UnderTheLimit: Story = {
+  args: { limit: 2000000, total: 1240000 },
+}
+
+export const ApproachingTheLimit: Story = {
+  args: { limit: 2000000, total: 1760000 },
+}
+
+export const AtTheLimit: Story = {
+  args: { limit: 2000000, total: 2000000 },
+}
+
+export const OverTheLimit: Story = {
+  args: { limit: 50000, total: 68400 },
+}
+
+// Nothing to be a percentage of, so the total stands on its own.
+export const WithoutAPlanLimit: Story = {
+  args: { limit: null, total: 340000 },
+}
+
+export const NoUsageYet: Story = {
+  args: { limit: 50000, total: 0 },
+}
+
+export const WithANote: Story = {
+  args: {
+    limit: 2000000,
+    note: (
+      <p className='mt-3 mb-0 text-muted fs-small'>
+        On track to use ~1.9M calls by the end of the period.
+      </p>
+    ),
+    total: 1240000,
+  },
+}

frontend/documentation/components/UsageOverTime.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from 'storybook'
+import UsageOverTime from 'components/pages/usage/components/UsageOverTime'
+import { Res } from 'common/types/responses'
+
+const meta: Meta<typeof UsageOverTime> = {
+  component: UsageOverTime,
+  parameters: { layout: 'padded' },
+  title: 'Pages/Usage Dashboard/Components/UsageOverTime',
+}
+export default meta
+
+type Story = StoryObj<typeof UsageOverTime>
+
+// Weekends lighter, so the shape reads like real traffic rather than a ramp.
+const DAY_WEIGHTS = [1.08, 1.12, 1.05, 1.1, 0.98, 0.62, 0.58]
+
+const usage = (days: number, perDay: number): Res['organisationUsage'] => {
+  const events = Array.from({ length: days }).map((_, index) => {
+    const weight = DAY_WEIGHTS[index % DAY_WEIGHTS.length]
+    return {
+      day: `2026-08-${`${index + 1}`.padStart(2, '0')}`,
+      environment_document: Math.round(perDay * weight * 0.04),
+      flags: Math.round(perDay * weight * 0.63),
+      identities: Math.round(perDay * weight * 0.24),
+      labels: { user_agent: null },
+      traits: Math.round(perDay * weight * 0.09),
+    }
+  })
+  const sum = (key: keyof (typeof events)[number]) =>
+    events.reduce((acc, event) => acc + Number(event[key] ?? 0), 0)
+
+  return {
+    events_list: events,
+    totals: {
+      environmentDocument: sum('environment_document'),
+      flags: sum('flags'),
+      identities: sum('identities'),
+      total:
+        sum('flags') +
+        sum('identities') +
+        sum('traits') +
+        sum('environment_document'),
+      traits: sum('traits'),
+    },
+  }
+}
+
+export const CumulativeUnderTheCeiling: Story = {
+  args: {
+    data: usage(18, 70000),
+    isBillingPeriod: true,
+    limit: 2000000,
+  },
+}
+
+export const CumulativeCrossingTheCeiling: Story = {
+  args: {
+    data: usage(24, 110000),
+    isBillingPeriod: true,
+    limit: 2000000,
+  },
+}
+
+// A rolling window's total falls as old days drop out, so it gets daily volume
+// rather than a line that only ever climbs.
+export const DailyVolumeOnARollingWindow: Story = {
+  args: {
+    data: usage(30, 2000),
+    isBillingPeriod: false,
+    limit: 50000,
+  },
+}
+
+export const NoLimitToDrawAgainst: Story = {
+  args: {
+    data: usage(18, 70000),
+    isBillingPeriod: true,
+    limit: null,
+  },
+}
+
+export const NoUsageRecorded: Story = {
+  args: {
+    data: usage(0, 0),
+    isBillingPeriod: true,
+    limit: 2000000,
+  },
+}