@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/components/account/AccountItemsTab.tsx

@@ -0,0 +1,192 @@
+"use client"
+import * as React from 'react'
+import { useRouter } from 'next/navigation'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { BillingDataTable as DataTable } from '../BillingDataTable'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { itemBillingState, type ItemBillingState } from '../../lib/itemBillingState'
+import { formatDate } from './accountRow'
+
+// Snake_case projection of `GET /api/billing/items` (see its `fields`).
+type AccountItemRow = {
+  id: string
+  description: string
+  type: 'one_time' | 'recurring' | 'usage'
+  bill_start_date: string
+  bill_end_date: string | null
+  billed_to_date: string | null
+  rate_json: Record<string, unknown> | null
+  charge_timing: 'in_advance' | 'in_arrears'
+  price_basis?: 'net' | 'gross'
+  uom_code: string | null
+  is_active: boolean
+}
+
+function localToday(): string {
+  const now = new Date()
+  const month = String(now.getMonth() + 1).padStart(2, '0')
+  const date = String(now.getDate()).padStart(2, '0')
+  return `${now.getFullYear()}-${month}-${date}`
+}
+
+function stateVariant(state: ItemBillingState): 'success' | 'warning' | 'neutral' | 'info' {
+  switch (state.status) {
+    case 'billed':
+    case 'current':
+    case 'fully_billed':
+      return 'success'
+    case 'awaiting_run':
+    case 'due':
+      return 'warning'
+    case 'metered':
+      return 'info'
+    default:
+      return 'neutral'
+  }
+}
+
+/**
+ * The account's billing items (workspace Items tab): what each item costs,
+ * its term, how far it has been billed and — against today — whether a Bill
+ * Run still has to charge it.
+ */
+export function AccountItemsTab({ accountId, currencyCode }: { accountId: string; currencyCode?: string }) {
+  const t = useT()
+  const router = useRouter()
+  const [rows, setRows] = React.useState<AccountItemRow[]>([])
+  const [page, setPage] = React.useState(1)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [loading, setLoading] = React.useState(true)
+  const pageSize = 25
+  const today = React.useMemo(() => localToday(), [])
+
+  const load = React.useCallback(async () => {
+    setLoading(true)
+    try {
+      const result = await readApiResultOrThrow<{ items: AccountItemRow[]; total: number; totalPages: number }>(
+        `/api/billing/items?billAccountId=${accountId}&page=${page}` + `&pageSize=${pageSize}&sortField=createdAt&sortDir=desc`,
+      )
+      setRows(result.items ?? [])
+      setTotal(result.total ?? 0)
+      setTotalPages(result.totalPages ?? 1)
+    } finally {
+      setLoading(false)
+    }
+  }, [accountId, page])
+
+  React.useEffect(() => {
+    void load()
+  }, [load])
+
+  const typeLabel = React.useCallback(
+    (row: AccountItemRow) => {
+      if (row.type === 'one_time') return t('billing.items.form.type.one_time', 'One-time charge')
+      if (row.type === 'usage') return t('billing.items.form.type.usage', 'Usage (metered)')
+      return row.charge_timing === 'in_arrears'
+        ? t('billing.accounts.items.recurring_arrears', 'Recurring · in arrears')
+        : t('billing.accounts.items.recurring_advance', 'Recurring · in advance')
+    },
+    [t],
+  )
+
+  const rateLabel = React.useCallback(
+    (row: AccountItemRow) => {
+      const rate = row.rate_json ?? {}
+      const amount = typeof rate.amount === 'number' ? rate.amount : typeof rate.unit_price === 'number' ? rate.unit_price : null
+      if (amount === null) {
+        return 'model' in rate ? `${t('billing.accounts.items.tiered', 'Tiered')} (${String(rate.model)})` : '—'
+      }
+      const perUnit = row.type === 'usage' && row.uom_code ? ` / ${row.uom_code}` : ''
+      const basis = row.price_basis === 'gross' ? t('billing.items.price_basis.gross', 'Gross') : t('billing.items.price_basis.net', 'Net')
+      return `${amount}${currencyCode ? ` ${currencyCode}` : ''}${perUnit} · ${basis}`
+    },
+    [currencyCode, t],
+  )
+
+  const stateLabel = React.useCallback(
+    (state: ItemBillingState) => {
+      const date = state.date ? formatDate(state.date) : ''
+      switch (state.status) {
+        case 'inactive':
+          return t('billing.common.inactive', 'Inactive')
+        case 'metered':
+          return t('billing.accounts.items.state.metered', 'Billed from usage')
+        case 'scheduled':
+          return `${t('billing.accounts.items.state.scheduled', 'Starts')} ${date}`
+        case 'awaiting_run':
+          return t('billing.accounts.items.state.awaiting_run', 'Not billed yet')
+        case 'billed':
+          return t('billing.accounts.items.state.billed', 'Billed')
+        case 'current':
+          return `${t('billing.accounts.items.state.current', 'Billed through')} ${date}`
+        case 'due':
+          return `${t('billing.accounts.items.state.due', 'Due since')} ${date}`
+        case 'fully_billed':
+          return t('billing.accounts.items.state.fully_billed', 'Fully billed')
+      }
+    },
+    [t],
+  )
+
+  const columns = React.useMemo<ColumnDef<AccountItemRow>[]>(
+    () => [
+      {
+        accessorKey: 'description',
+        header: t('billing.items.columns.description', 'Description'),
+        cell: ({ row }) => <span className="text-sm font-medium text-primary">{row.original.description}</span>,
+      },
+      {
+        accessorKey: 'type',
+        header: t('billing.items.columns.type', 'Type'),
+        cell: ({ row }) => <span className="text-sm">{typeLabel(row.original)}</span>,
+      },
+      {
+        accessorKey: 'rate_json',
+        header: t('billing.items.form.rate.title', 'Rate'),
+        cell: ({ row }) => <span className="text-sm tabular-nums">{rateLabel(row.original)}</span>,
+      },
+      {
+        accessorKey: 'bill_start_date',
+        header: t('billing.accounts.items.term', 'Term'),
+        cell: ({ row }) =>
+          `${formatDate(row.original.bill_start_date)} – ${
+            row.original.bill_end_date ? formatDate(row.original.bill_end_date) : t('billing.accounts.items.open_ended', 'open-ended')
+          }`,
+      },
+      {
+        accessorKey: 'billed_to_date',
+        header: t('billing.accounts.items.billed_through', 'Billed through'),
+        cell: ({ row }) =>
+          row.original.type === 'recurring' && row.original.billed_to_date ? formatDate(row.original.billed_to_date) : '—',
+      },
+      {
+        id: 'billing_state',
+        header: t('billing.accounts.items.state', 'Billing'),
+        cell: ({ row }) => {
+          const state = itemBillingState(row.original, today)
+          return <Tag variant={stateVariant(state)}>{stateLabel(state)}</Tag>
+        },
+      },
+    ],
+    [rateLabel, stateLabel, t, today, typeLabel],
+  )
+
+  return (
+    <DataTable
+      title={t('billing.accounts.detail.items.title', 'Items')}
+      columns={columns}
+      data={rows}
+      isLoading={loading}
+      onRowClick={(row) => router.push(`/backend/billing/items/${row.id}`)}
+      pagination={{ page, pageSize, total, totalPages, onPageChange: setPage }}
+      emptyState={
+        <div className="rounded-lg border bg-card p-6 text-center text-sm text-muted-foreground">
+          {t('billing.accounts.detail.items.empty', 'No items for this account yet.')}
+        </div>
+      }
+    />
+  )
+}

package/src/modules/billing/components/account/AccountRunBillingDialog.tsx

@@ -0,0 +1,147 @@
+"use client"
+import * as React from 'react'
+import { Play } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Kbd, KbdShortcut } from '@open-mercato/ui/primitives/kbd'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@open-mercato/ui/primitives/dialog'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { normalizeCrudServerError } from '@open-mercato/ui/backend/utils/serverErrors'
+import type { BillRunMode } from '../TestRunActions'
+
+/**
+ * "Run billing" for one account (Spec E, E2-D3 / Spec F, F8): mode (Test by
+ * default) + as-of date → `POST /api/billing/runs` with
+ * `scopedAccountIds: [id]`. On success the dialog closes with a one-line
+ * summary; the workspace switches to its Bill runs tab, where the run (with
+ * its mode, documents and cleanup actions) is listed.
+ */
+
+type OutcomeRow = { status: string; error_message: string | null; cycles: Array<{ status: string }> | null }
+
+function todayIso(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+export type AccountRunBillingDialogProps = {
+  accountId: string
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Called after a run finished — the workspace closes the dialog and refreshes. */
+  onCompleted: (billRunId: string) => void
+}
+
+export function AccountRunBillingDialog({ accountId, open, onOpenChange, onCompleted }: AccountRunBillingDialogProps) {
+  const t = useT()
+  const [mode, setMode] = React.useState<BillRunMode>('test')
+  const [asOfDate, setAsOfDate] = React.useState<string>(todayIso())
+  const [running, setRunning] = React.useState(false)
+
+  React.useEffect(() => {
+    if (open) {
+      setMode('test')
+      setAsOfDate(todayIso())
+    }
+  }, [open])
+
+  const handleRun = React.useCallback(async () => {
+    setRunning(true)
+    try {
+      const call = await apiCallOrThrow<{ billRunId: string | null }>('/api/billing/runs', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ mode, asOfDate, scopedAccountIds: [accountId] }),
+      })
+      const billRunId = call.result?.billRunId
+      if (!billRunId) throw new Error(t('billing.runs.trigger.error', 'Failed to trigger run'))
+      const outcomes = await readApiResultOrThrow<{ items: OutcomeRow[] }>(
+        `/api/billing/run-outcomes?billRunId=${encodeURIComponent(billRunId)}&pageSize=1`,
+      )
+      const outcome = outcomes.items?.[0]
+      if (!outcome) {
+        flash(t('billing.accounts.run.nothing_due', 'Nothing is due up to this date — the next bill date is later.'), 'info')
+      } else if (outcome.status === 'failed') {
+        flash(`${t('billing.accounts.run.failed', 'Bill run failed')}: ${outcome.error_message ?? ''}`, 'error')
+      } else {
+        const cycles = (outcome.cycles ?? []).filter((cycle) => cycle.status !== 'empty').length
+        flash(`${t('billing.accounts.run.done', 'Bill run completed — bill dates with charges:')} ${cycles}`, 'success')
+      }
+      onCompleted(billRunId)
+    } catch (err) {
+      const { message } = normalizeCrudServerError(err)
+      flash(message || t('billing.runs.trigger.error', 'Failed to trigger run'), 'error')
+    } finally {
+      setRunning(false)
+    }
+  }, [accountId, asOfDate, mode, onCompleted, t])
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+        event.preventDefault()
+        if (!running) void handleRun()
+      }
+    },
+    [handleRun, running],
+  )
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => (!running ? onOpenChange(next) : undefined)}>
+      <DialogContent onKeyDown={handleKeyDown}>
+        <DialogHeader>
+          <DialogTitle>{t('billing.accounts.run.title', 'Run billing for this account')}</DialogTitle>
+          <DialogDescription>
+            {t(
+              'billing.accounts.run.description',
+              'Bills every due cycle of this account up to the as-of date. Test and dry runs change nothing on the account.',
+            )}
+          </DialogDescription>
+        </DialogHeader>
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+          <label className="flex flex-col gap-1 text-sm">
+            <span className="text-muted-foreground">{t('billing.runs.trigger.dialog.mode', 'Mode')}</span>
+            <Select value={mode} onValueChange={(next) => setMode(next === 'real' || next === 'dry' ? next : 'test')}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="test">{t('billing.runs.trigger.dialog.mode.test', 'Test — drafts tagged for cleanup')}</SelectItem>
+                <SelectItem value="dry">{t('billing.runs.trigger.dialog.mode.dry', 'Dry-run — no rows written')}</SelectItem>
+                <SelectItem value="real">{t('billing.runs.trigger.dialog.mode.real', 'Real — create draft invoices')}</SelectItem>
+              </SelectContent>
+            </Select>
+          </label>
+          <label className="flex flex-col gap-1 text-sm">
+            <span className="text-muted-foreground">{t('billing.runs.trigger.dialog.as_of_date', 'As-of date')}</span>
+            <Input type="date" value={asOfDate} onChange={(event) => setAsOfDate(event.currentTarget.value)} />
+          </label>
+        </div>
+        <DialogFooter className="flex items-center justify-between gap-3 sm:justify-between">
+          <span className="text-xs text-muted-foreground">
+            <KbdShortcut keys={['Ctrl/⌘', 'Enter']} /> {t('billing.accounts.run.submit_hint', 'to run,')} <Kbd>Esc</Kbd>{' '}
+            {t('billing.accounts.run.close_hint', 'to close')}
+          </span>
+          <div className="flex items-center gap-2">
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)} disabled={running}>
+              {t('billing.common.cancel', 'Cancel')}
+            </Button>
+            <Button type="button" onClick={() => void handleRun()} disabled={running}>
+              <Play size={16} />
+              {running ? t('billing.accounts.run.running', 'Running…') : t('billing.accounts.run.action', 'Run billing')}
+            </Button>
+          </div>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/modules/billing/components/account/AccountRunsTab.tsx

@@ -0,0 +1,201 @@
+"use client"
+import * as React from 'react'
+import Link from 'next/link'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { BillingDataTable as DataTable } from '../BillingDataTable'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import { useTestRunCleanup, type BillRunMode } from '../TestRunActions'
+
+/**
+ * Bill Runs tab of the account workspace (Spec E §4 / Spec F, F8): this
+ * account's run outcomes, newest first, from
+ * `GET /api/billing/run-outcomes?billAccountId=` (server-paginated).
+ */
+
+type OutcomeCycle = {
+  bill_date: string
+  status: string
+  invoice_id: string | null
+  invoice_number?: string | null
+  statement_id?: string | null
+}
+
+type OutcomeRow = {
+  id: string
+  bill_run_id: string
+  run_mode: BillRunMode | null
+  run_as_of_date: string | null
+  status: string
+  error_message: string | null
+  draft_invoice_id: string | null
+  invoice_number: string | null
+  cycles: OutcomeCycle[] | null
+  created_at: string
+}
+
+type ListResponse = { items: OutcomeRow[]; total: number; totalPages: number }
+
+const PAGE_SIZE = 20
+
+function statusVariant(status: string): 'success' | 'warning' | 'error' | 'neutral' {
+  if (status === 'success') return 'success'
+  if (status === 'failed') return 'error'
+  if (status === 'success_with_warnings' || status.startsWith('skipped')) return 'warning'
+  return 'neutral'
+}
+
+export function AccountRunsTab({ accountId, refreshKey = 0 }: { accountId: string; refreshKey?: number }) {
+  const t = useT()
+  const [rows, setRows] = React.useState<OutcomeRow[]>([])
+  const [page, setPage] = React.useState(1)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+  const cleanup = useTestRunCleanup()
+
+  const load = React.useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const params = new URLSearchParams({
+        billAccountId: accountId,
+        page: String(page),
+        pageSize: String(PAGE_SIZE),
+        sortField: 'createdAt',
+        sortDir: 'desc',
+      })
+      const result = await readApiResultOrThrow<ListResponse>(`/api/billing/run-outcomes?${params.toString()}`)
+      setRows(result.items ?? [])
+      setTotal(result.total ?? 0)
+      setTotalPages(result.totalPages ?? 1)
+    } catch {
+      setError(t('billing.accounts.runs.error', 'Failed to load bill runs'))
+    } finally {
+      setLoading(false)
+    }
+  }, [accountId, page, t])
+
+  React.useEffect(() => {
+    void load()
+  }, [load, refreshKey])
+
+  const columns = React.useMemo<ColumnDef<OutcomeRow>[]>(
+    () => [
+      {
+        accessorKey: 'created_at',
+        header: t('billing.accounts.runs.columns.when', 'Run at'),
+        cell: ({ row }) => (
+          <Link href={`/backend/billing/runs/${row.original.bill_run_id}`} className="text-primary hover:underline">
+            {new Date(row.original.created_at).toLocaleString()}
+          </Link>
+        ),
+      },
+      {
+        accessorKey: 'run_mode',
+        header: t('billing.runs.detail.field.mode', 'Mode'),
+        cell: ({ row }) =>
+          row.original.run_mode === 'dry' ? (
+            <Tag variant="warning">{t('billing.runs.mode.dry_run', 'Dry-run')}</Tag>
+          ) : row.original.run_mode === 'test' ? (
+            <Tag variant="warning">{t('billing.runs.mode.test', 'Test')}</Tag>
+          ) : (
+            <Tag variant="default">{t('billing.runs.mode.real', 'Real')}</Tag>
+          ),
+      },
+      {
+        accessorKey: 'run_as_of_date',
+        header: t('billing.runs.columns.as_of_date', 'As-of date'),
+        cell: ({ row }) => row.original.run_as_of_date ?? '—',
+      },
+      {
+        accessorKey: 'status',
+        header: t('billing.runs.outcomes.columns.status', 'Status'),
+        cell: ({ row }) => <Tag variant={statusVariant(row.original.status)}>{row.original.status}</Tag>,
+      },
+      {
+        id: 'cycles',
+        header: t('billing.accounts.runs.columns.cycles', 'Bill dates'),
+        cell: ({ row }) => {
+          const cycles = row.original.cycles ?? []
+          if (cycles.length === 0) return '—'
+          return cycles.map((cycle) => cycle.bill_date).join(', ')
+        },
+      },
+      {
+        id: 'documents',
+        header: t('billing.accounts.runs.columns.documents', 'Documents'),
+        cell: ({ row }) => {
+          const cycles = row.original.cycles ?? []
+          const links = cycles.flatMap((cycle) =>
+            cycle.invoice_id
+              ? [
+                  <Link key={cycle.invoice_id} href={`/backend/billing/invoices/${cycle.invoice_id}`} className="text-primary hover:underline">
+                    {cycle.invoice_number ?? cycle.invoice_id.slice(0, 8)}
+                  </Link>,
+                ]
+              : cycle.statement_id
+                ? [
+                    <Link key={cycle.statement_id} href={`/backend/billing/statements/${cycle.statement_id}`} className="text-primary hover:underline">
+                      {t('billing.runs.cycles.statement', 'Statement')} {cycle.bill_date}
+                    </Link>,
+                  ]
+                : [],
+          )
+          if (links.length === 0) return row.original.error_message ?? '—'
+          return <span className="flex flex-wrap gap-x-3 gap-y-1">{links}</span>
+        },
+      },
+    ],
+    [t],
+  )
+
+  return (
+    <>
+    <DataTable
+      title={t('billing.accounts.tabs.runs', 'Bill runs')}
+      columns={columns}
+      data={rows}
+      isLoading={loading}
+      error={error}
+      pagination={{ page, pageSize: PAGE_SIZE, total, totalPages, onPageChange: setPage }}
+      emptyState={t('billing.accounts.runs.empty', 'No bill runs for this account yet.')}
+      rowActions={(row) => (
+        <RowActions
+          items={[
+            { id: 'open', label: t('billing.runs.actions.open', 'Open'), href: `/backend/billing/runs/${row.bill_run_id}` },
+            ...(row.run_mode === 'test'
+              ? [
+                  {
+                    id: 'wipe',
+                    label: t('billing.runs.wipe.action', 'Wipe test invoices'),
+                    onSelect: async () => {
+                      if ((await cleanup.wipe(row.bill_run_id)) !== null) void load()
+                    },
+                  },
+                ]
+              : []),
+            ...(row.run_mode === 'test' || row.run_mode === 'dry'
+              ? [
+                  {
+                    id: 'delete',
+                    label: t('billing.runs.delete.action', 'Delete run'),
+                    destructive: true,
+                    onSelect: async () => {
+                      const removed = await cleanup.remove({ runId: row.bill_run_id, mode: row.run_mode ?? 'test' })
+                      if (removed !== null) void load()
+                    },
+                  },
+                ]
+              : []),
+          ]}
+        />
+      )}
+    />
+    {cleanup.ConfirmDialogElement}
+    </>
+  )
+}

package/src/modules/billing/components/account/AccountStatementsTab.tsx

@@ -0,0 +1,120 @@
+"use client"
+import * as React from 'react'
+import { useRouter } from 'next/navigation'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { BillingDataTable as DataTable } from '../BillingDataTable'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { formatMoney } from '../InvoicesTable'
+
+/**
+ * Statements tab of a prepaid account workspace (Spec E §4 / Spec F, F8):
+ * the account's consumption statements, newest period first
+ * (`GET /api/billing/statements?billAccountId=`, server-paginated).
+ */
+
+type StatementRow = {
+  id: string
+  period_start: string
+  period_end: string
+  currency_code: string
+  opening_balance: string
+  total_topups: string
+  total_usage: string
+  total_recurring: string
+  closing_balance: string
+}
+
+type ListResponse = { items: StatementRow[]; total: number; totalPages: number }
+
+const PAGE_SIZE = 20
+
+function day(value: string): string {
+  return value ? value.slice(0, 10) : '—'
+}
+
+export function AccountStatementsTab({ accountId, refreshKey = 0 }: { accountId: string; refreshKey?: number }) {
+  const t = useT()
+  const router = useRouter()
+  const [rows, setRows] = React.useState<StatementRow[]>([])
+  const [page, setPage] = React.useState(1)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+
+  const load = React.useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const params = new URLSearchParams({
+        billAccountId: accountId,
+        page: String(page),
+        pageSize: String(PAGE_SIZE),
+        sortField: 'periodEnd',
+        sortDir: 'desc',
+      })
+      const result = await readApiResultOrThrow<ListResponse>(`/api/billing/statements?${params.toString()}`)
+      setRows(result.items ?? [])
+      setTotal(result.total ?? 0)
+      setTotalPages(result.totalPages ?? 1)
+    } catch {
+      setError(t('billing.accounts.statements.error', 'Failed to load statements'))
+    } finally {
+      setLoading(false)
+    }
+  }, [accountId, page, t])
+
+  React.useEffect(() => {
+    void load()
+  }, [load, refreshKey])
+
+  const columns = React.useMemo<ColumnDef<StatementRow>[]>(
+    () => [
+      {
+        accessorKey: 'period_start',
+        header: t('billing.statements.columns.period', 'Period'),
+        cell: ({ row }) => `${day(row.original.period_start)} – ${day(row.original.period_end)}`,
+      },
+      {
+        accessorKey: 'opening_balance',
+        header: t('billing.statements.columns.opening', 'Opening'),
+        cell: ({ row }) => formatMoney(row.original.opening_balance, row.original.currency_code),
+      },
+      {
+        accessorKey: 'total_topups',
+        header: t('billing.statements.columns.topups', 'Top-ups'),
+        cell: ({ row }) => formatMoney(row.original.total_topups, row.original.currency_code),
+      },
+      {
+        accessorKey: 'total_usage',
+        header: t('billing.statements.columns.usage', 'Usage'),
+        cell: ({ row }) => formatMoney(row.original.total_usage, row.original.currency_code),
+      },
+      {
+        accessorKey: 'total_recurring',
+        header: t('billing.statements.columns.charges', 'Charges'),
+        cell: ({ row }) => formatMoney(row.original.total_recurring, row.original.currency_code),
+      },
+      {
+        accessorKey: 'closing_balance',
+        header: t('billing.statements.columns.closing', 'Closing'),
+        cell: ({ row }) => formatMoney(row.original.closing_balance, row.original.currency_code),
+      },
+    ],
+    [t],
+  )
+
+  return (
+    <DataTable
+      title={t('billing.accounts.tabs.statements', 'Statements')}
+      columns={columns}
+      data={rows}
+      isLoading={loading}
+      error={error}
+      onRowClick={(row) => router.push(`/backend/billing/statements/${row.id}`)}
+      pagination={{ page, pageSize: PAGE_SIZE, total, totalPages, onPageChange: setPage }}
+      emptyState={t('billing.accounts.statements.empty', 'No statements yet — they are written when a period closes.')}
+    />
+  )
+}