@dainamite/billing 0.17.0 → 0.18.0

package/src/modules/billing/backend/billing/statements/[id]/page.meta.ts

@@ -0,0 +1,19 @@
+import React from 'react'
+import { FileText } from 'lucide-react'
+
+const statementIcon = React.createElement(FileText, { size: 16 })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['billing.statement.view'],
+  pageTitle: 'Statement',
+  pageTitleKey: 'billing.statements.detail.title',
+  pageGroup: 'Billing',
+  pageGroupKey: 'billing.nav.group',
+  navHidden: true,
+  icon: statementIcon,
+  breadcrumb: [
+    { label: 'Statements', labelKey: 'billing.statements.title', href: '/backend/billing/statements' },
+    { label: 'Statement', labelKey: 'billing.statements.detail.title' },
+  ],
+} as const

package/src/modules/billing/backend/billing/statements/[id]/page.tsx

@@ -0,0 +1,198 @@
+"use client"
+import * as React from 'react'
+import Link from 'next/link'
+import { useParams } from 'next/navigation'
+import type { ColumnDef } from '@tanstack/react-table'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { FormHeader } from '@open-mercato/ui/backend/forms'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { DetailCard, DetailField } from '../../../../components/DetailFields'
+import { statementStatusVariant } from '../page'
+
+type BreakdownEntry = {
+  billing_item_id: string
+  billing_type: string
+  uom_code?: string
+  quantity: string
+  amount: string
+}
+
+type StatementRow = {
+  id: string
+  bill_account_id: string
+  bill_run_id: string | null
+  period_start: string
+  period_end: string
+  currency_code: string
+  opening_balance: string
+  total_topups: string
+  total_usage: string
+  total_recurring: string
+  total_adjustments: string
+  closing_balance: string
+  debit_breakdown: { items?: BreakdownEntry[] } | null
+  status: string
+}
+
+function formatDate(value: string | null | undefined): string {
+  if (!value) return '—'
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? value : d.toLocaleDateString()
+}
+
+export default function BillingStatementDetailPage(props: { params?: { id?: string } }) {
+  const t = useT()
+  const urlParams = useParams<{ id: string }>()
+  const statementId = (props.params?.id ?? urlParams?.id ?? '') as string
+
+  const [row, setRow] = React.useState<StatementRow | null>(null)
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    let cancelled = false
+    if (!statementId) return
+    setLoading(true)
+    readApiResultOrThrow<{ items: StatementRow[] }>(
+      `/api/billing/statements?id=${statementId}&pageSize=1`,
+    )
+      .then((res) => {
+        if (cancelled) return
+        const found = res.items?.[0]
+        if (!found) setError(t('billing.statements.detail.not_found', 'Statement not found'))
+        else setRow(found)
+      })
+      .catch(() => {
+        if (!cancelled)
+          setError(t('billing.statements.detail.load_error', 'Failed to load statement'))
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [statementId, t])
+
+  const breakdown = row?.debit_breakdown?.items ?? []
+  const columns = React.useMemo<ColumnDef<BreakdownEntry>[]>(
+    () => [
+      {
+        accessorKey: 'billing_type',
+        header: t('billing.statements.breakdown.type', 'Type'),
+        cell: ({ row }) => <Tag variant="info">{row.original.billing_type}</Tag>,
+      },
+      {
+        accessorKey: 'billing_item_id',
+        header: t('billing.statements.breakdown.item', 'Item'),
+        cell: ({ row }) => <span className="font-mono text-xs">{row.original.billing_item_id}</span>,
+      },
+      {
+        accessorKey: 'quantity',
+        header: t('billing.statements.breakdown.quantity', 'Qty'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.quantity}</span>,
+      },
+      {
+        accessorKey: 'amount',
+        header: t('billing.statements.breakdown.amount', 'Amount'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.amount}</span>,
+      },
+    ],
+    [t],
+  )
+
+  if (error) {
+    return (
+      <Page>
+        <PageBody>
+          <ErrorMessage label={error} />
+        </PageBody>
+      </Page>
+    )
+  }
+  if (loading || !row) {
+    return (
+      <Page>
+        <PageBody>
+          <LoadingMessage label={t('billing.statements.detail.loading', 'Loading statement…')} />
+        </PageBody>
+      </Page>
+    )
+  }
+
+  return (
+    <Page>
+      <FormHeader
+        mode="detail"
+        backHref="/backend/billing/statements"
+        entityTypeLabel={t('billing.statements.detail.title', 'Statement')}
+        title={`${formatDate(row.period_start)} – ${formatDate(row.period_end)}`}
+        statusBadge={
+          <Tag variant={statementStatusVariant(row.status)}>
+            {t(`billing.statements.status.${row.status}`, row.status)}
+          </Tag>
+        }
+        actionsContent={
+          <Button asChild variant="outline">
+            <Link href={`/backend/billing/accounts/${row.bill_account_id}`}>
+              {t('billing.statements.detail.view_account', 'View account')}
+            </Link>
+          </Button>
+        }
+      />
+      <PageBody>
+        <DetailCard>
+          <DetailField label={t('billing.statements.columns.opening', 'Opening')}>
+            <span className="font-mono tabular-nums">{row.opening_balance}</span>
+          </DetailField>
+          <DetailField label={t('billing.statements.columns.topups', 'Top-ups')}>
+            <span className="font-mono tabular-nums">{row.total_topups}</span>
+          </DetailField>
+          <DetailField label={t('billing.statements.columns.usage', 'Usage')}>
+            <span className="font-mono tabular-nums">{row.total_usage}</span>
+          </DetailField>
+          <DetailField label={t('billing.statements.columns.recurring', 'Recurring')}>
+            <span className="font-mono tabular-nums">{row.total_recurring}</span>
+          </DetailField>
+          <DetailField label={t('billing.statements.columns.adjustments', 'Adjustments')}>
+            <span className="font-mono tabular-nums">{row.total_adjustments}</span>
+          </DetailField>
+          <DetailField label={t('billing.statements.columns.closing', 'Closing')}>
+            <span className="font-mono tabular-nums">
+              {row.closing_balance} {row.currency_code}
+            </span>
+          </DetailField>
+          <DetailField label={t('billing.statements.detail.bill_run', 'Bill Run')}>
+            {row.bill_run_id ? (
+              <Link
+                href={`/backend/billing/runs/${row.bill_run_id}`}
+                className="font-mono text-xs hover:underline"
+              >
+                {row.bill_run_id}
+              </Link>
+            ) : (
+              '—'
+            )}
+          </DetailField>
+        </DetailCard>
+        <div className="mt-6">
+          <DataTable
+            title={t('billing.statements.detail.breakdown', 'Period-close charges')}
+            columns={columns}
+            data={breakdown}
+            emptyState={
+              <div className="rounded-lg border bg-card p-6 text-center text-sm text-muted-foreground">
+                {t('billing.statements.detail.no_charges', 'No recurring charges this period.')}
+              </div>
+            }
+          />
+        </div>
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/billing/backend/billing/statements/page.meta.ts

@@ -0,0 +1,16 @@
+import React from 'react'
+import { FileText } from 'lucide-react'
+
+const statementsIcon = React.createElement(FileText, { size: 16 })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['billing.statement.view'],
+  pageTitle: 'Statements',
+  pageTitleKey: 'billing.statements.title',
+  pageGroup: 'Billing',
+  pageGroupKey: 'billing.nav.group',
+  pageOrder: 60,
+  icon: statementsIcon,
+  breadcrumb: [{ label: 'Statements', labelKey: 'billing.statements.title' }],
+} as const

package/src/modules/billing/backend/billing/statements/page.tsx

@@ -0,0 +1,190 @@
+"use client"
+import * as React from 'react'
+import { useRouter } from 'next/navigation'
+import type { ColumnDef } from '@tanstack/react-table'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { fetchAccountNames } from '../../../components/accountNames'
+
+/**
+ * Consumption statements admin list (SPEC-002 P3). Non-fiscal period summaries
+ * for prepaid accounts — opening / top-ups / usage / recurring / closing.
+ */
+
+type StatementRow = {
+  id: string
+  bill_account_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
+  status: string
+}
+
+type ListResponse = { items: StatementRow[]; total: number; totalPages: number }
+
+function formatDate(value: string | null | undefined): string {
+  if (!value) return '—'
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? value : d.toLocaleDateString()
+}
+
+export function statementStatusVariant(status: string): 'success' | 'info' {
+  return status === 'sent' ? 'success' : 'info'
+}
+
+export default function BillingStatementsListPage() {
+  const t = useT()
+  const router = useRouter()
+  const [rows, setRows] = React.useState<StatementRow[]>([])
+  const [page, setPage] = React.useState(1)
+  const [pageSize] = React.useState(25)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [loading, setLoading] = React.useState(true)
+  const [filters, setFilters] = React.useState<FilterValues>({})
+  const [accountNames, setAccountNames] = React.useState<Record<string, string>>({})
+
+  const filterDefs = React.useMemo<FilterDef[]>(
+    () => [
+      {
+        id: 'status',
+        label: t('billing.statements.filters.status', 'Status'),
+        type: 'select',
+        options: [
+          { value: 'generated', label: t('billing.statements.status.generated', 'Generated') },
+          { value: 'sent', label: t('billing.statements.status.sent', 'Sent') },
+        ],
+      },
+    ],
+    [t],
+  )
+
+  const loadRows = React.useCallback(async () => {
+    setLoading(true)
+    try {
+      const params = new URLSearchParams({
+        page: String(page),
+        pageSize: String(pageSize),
+        sortField: 'periodEnd',
+        sortDir: 'desc',
+      })
+      if (typeof filters.status === 'string' && filters.status) params.set('status', filters.status)
+      const result = await readApiResultOrThrow<ListResponse>(
+        `/api/billing/statements?${params.toString()}`,
+      )
+      const items = result.items ?? []
+      setRows(items)
+      setTotal(result.total ?? 0)
+      setTotalPages(result.totalPages ?? 1)
+      try {
+        const names = await fetchAccountNames(items.map((r) => r.bill_account_id))
+        setAccountNames((prev) => ({ ...prev, ...names }))
+      } catch {
+        // Name resolution is best-effort — fall back to the id in the cell.
+      }
+    } finally {
+      setLoading(false)
+    }
+  }, [filters.status, page, pageSize])
+
+  React.useEffect(() => {
+    void loadRows()
+  }, [loadRows])
+
+  const columns = React.useMemo<ColumnDef<StatementRow>[]>(
+    () => [
+      {
+        accessorKey: 'period_end',
+        header: t('billing.statements.columns.period', 'Period'),
+        cell: ({ row }) =>
+          `${formatDate(row.original.period_start)} – ${formatDate(row.original.period_end)}`,
+      },
+      {
+        accessorKey: 'bill_account_id',
+        header: t('billing.statements.columns.account', 'Account'),
+        cell: ({ row }) => {
+          const name = accountNames[row.original.bill_account_id]
+          return name ? (
+            <span className="text-sm">{name}</span>
+          ) : (
+            <span className="font-mono text-xs">{row.original.bill_account_id}</span>
+          )
+        },
+      },
+      {
+        accessorKey: 'opening_balance',
+        header: t('billing.statements.columns.opening', 'Opening'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.opening_balance}</span>,
+      },
+      {
+        accessorKey: 'total_topups',
+        header: t('billing.statements.columns.topups', 'Top-ups'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.total_topups}</span>,
+      },
+      {
+        accessorKey: 'total_usage',
+        header: t('billing.statements.columns.usage', 'Usage'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.total_usage}</span>,
+      },
+      {
+        accessorKey: 'total_recurring',
+        header: t('billing.statements.columns.recurring', 'Recurring'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.total_recurring}</span>,
+      },
+      {
+        accessorKey: 'closing_balance',
+        header: t('billing.statements.columns.closing', 'Closing'),
+        cell: ({ row }) => (
+          <span className="font-mono tabular-nums">
+            {row.original.closing_balance} {row.original.currency_code}
+          </span>
+        ),
+      },
+      {
+        accessorKey: 'status',
+        header: t('billing.statements.columns.status', 'Status'),
+        cell: ({ row }) => (
+          <Tag variant={statementStatusVariant(row.original.status)}>
+            {t(`billing.statements.status.${row.original.status}`, row.original.status)}
+          </Tag>
+        ),
+      },
+    ],
+    [t, accountNames],
+  )
+
+  return (
+    <Page>
+      <PageBody>
+        <DataTable
+          title={t('billing.statements.title', 'Statements')}
+          refreshButton={{
+            label: t('billing.common.refresh', 'Refresh'),
+            onRefresh: loadRows,
+            isRefreshing: loading,
+          }}
+          columnChooser={{ auto: true }}
+          perspective={{ tableId: 'billing-statements' }}
+          columns={columns}
+          data={rows}
+          onRowClick={(row) => router.push(`/backend/billing/statements/${row.id}`)}
+          isLoading={loading}
+          pagination={{ page, pageSize, total, totalPages, onPageChange: setPage }}
+          filters={filterDefs}
+          filterValues={filters}
+          onFiltersApply={setFilters}
+          onFiltersClear={() => setFilters({})}
+        />
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/billing/backend/billing/topups/[id]/page.meta.ts

@@ -0,0 +1,19 @@
+import React from 'react'
+import { Wallet } from 'lucide-react'
+
+const topupIcon = React.createElement(Wallet, { size: 16 })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['billing.topup.view'],
+  pageTitle: 'Top-up',
+  pageTitleKey: 'billing.topups.detail.title',
+  pageGroup: 'Billing',
+  pageGroupKey: 'billing.nav.group',
+  navHidden: true,
+  icon: topupIcon,
+  breadcrumb: [
+    { label: 'Top-ups', labelKey: 'billing.topups.title', href: '/backend/billing/topups' },
+    { label: 'Top-up', labelKey: 'billing.topups.detail.title' },
+  ],
+} as const

package/src/modules/billing/backend/billing/topups/[id]/page.tsx

@@ -0,0 +1,151 @@
+"use client"
+import * as React from 'react'
+import Link from 'next/link'
+import { useParams } from 'next/navigation'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { FormHeader } from '@open-mercato/ui/backend/forms'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { DetailCard, DetailField } from '../../../../components/DetailFields'
+import { statusVariant } from '../page'
+
+type TopupRow = {
+  id: string
+  bill_account_id: string
+  status: string
+  amount: string
+  currency_code: string
+  provider_key: string
+  payment_id: string
+  gateway_transaction_id: string | null
+  transaction_id: string | null
+  receipt_invoice_id: string | null
+  source_ref: string | null
+  created_at: string
+  updated_at: string
+}
+
+function formatDate(value: string | null | undefined): string {
+  if (!value) return '—'
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? value : d.toLocaleString()
+}
+
+export default function BillingTopupDetailPage(props: { params?: { id?: string } }) {
+  const t = useT()
+  const urlParams = useParams<{ id: string }>()
+  const topupId = (props.params?.id ?? urlParams?.id ?? '') as string
+
+  const [row, setRow] = React.useState<TopupRow | null>(null)
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    let cancelled = false
+    if (!topupId) return
+    setLoading(true)
+    readApiResultOrThrow<{ items: TopupRow[] }>(`/api/billing/topups?id=${topupId}&pageSize=1`)
+      .then((res) => {
+        if (cancelled) return
+        const found = res.items?.[0]
+        if (!found) setError(t('billing.topups.detail.not_found', 'Top-up not found'))
+        else setRow(found)
+      })
+      .catch(() => {
+        if (!cancelled) setError(t('billing.topups.detail.load_error', 'Failed to load top-up'))
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [topupId, t])
+
+  if (error) {
+    return (
+      <Page>
+        <PageBody>
+          <ErrorMessage label={error} />
+        </PageBody>
+      </Page>
+    )
+  }
+  if (loading || !row) {
+    return (
+      <Page>
+        <PageBody>
+          <LoadingMessage label={t('billing.topups.detail.loading', 'Loading top-up…')} />
+        </PageBody>
+      </Page>
+    )
+  }
+
+  return (
+    <Page>
+      <FormHeader
+        mode="detail"
+        backHref="/backend/billing/topups"
+        entityTypeLabel={t('billing.topups.detail.title', 'Top-up')}
+        title={`${row.amount} ${row.currency_code}`}
+        statusBadge={
+          <Tag variant={statusVariant(row.status)}>
+            {t(`billing.topups.status.${row.status}`, row.status)}
+          </Tag>
+        }
+        actionsContent={
+          <Button asChild variant="outline">
+            <Link href={`/backend/billing/accounts/${row.bill_account_id}`}>
+              {t('billing.topups.detail.view_account', 'View account')}
+            </Link>
+          </Button>
+        }
+      />
+      <PageBody>
+        <DetailCard>
+          <DetailField label={t('billing.topups.columns.amount', 'Amount')}>
+            <span className="font-mono tabular-nums">
+              {row.amount} {row.currency_code}
+            </span>
+          </DetailField>
+          <DetailField label={t('billing.topups.columns.provider', 'Provider')}>
+            {row.provider_key}
+          </DetailField>
+          <DetailField label={t('billing.topups.columns.created', 'Created')}>
+            {formatDate(row.created_at)}
+          </DetailField>
+          <DetailField label={t('billing.topups.detail.updated', 'Updated')}>
+            {formatDate(row.updated_at)}
+          </DetailField>
+          <DetailField label={t('billing.topups.detail.payment_id', 'Payment ID')}>
+            <span className="font-mono text-xs">{row.payment_id}</span>
+          </DetailField>
+          <DetailField label={t('billing.topups.detail.gateway_txn', 'Gateway transaction')}>
+            <span className="font-mono text-xs">{row.gateway_transaction_id || '—'}</span>
+          </DetailField>
+          <DetailField label={t('billing.topups.detail.balance_txn', 'Balance transaction')}>
+            <span className="font-mono text-xs">{row.transaction_id || '—'}</span>
+          </DetailField>
+          <DetailField label={t('billing.topups.detail.receipt', 'VAT receipt')}>
+            {row.receipt_invoice_id ? (
+              <Link
+                href={`/backend/billing/invoices/${row.receipt_invoice_id}`}
+                className="font-mono text-xs hover:underline"
+              >
+                {row.receipt_invoice_id}
+              </Link>
+            ) : (
+              '—'
+            )}
+          </DetailField>
+          <DetailField label={t('billing.common.id', 'ID')}>
+            <span className="font-mono text-xs">{row.id}</span>
+          </DetailField>
+        </DetailCard>
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/billing/backend/billing/topups/page.meta.ts

@@ -0,0 +1,16 @@
+import React from 'react'
+import { Wallet } from 'lucide-react'
+
+const topupsIcon = React.createElement(Wallet, { size: 16 })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['billing.topup.view'],
+  pageTitle: 'Top-ups',
+  pageTitleKey: 'billing.topups.title',
+  pageGroup: 'Billing',
+  pageGroupKey: 'billing.nav.group',
+  pageOrder: 50,
+  icon: topupsIcon,
+  breadcrumb: [{ label: 'Top-ups', labelKey: 'billing.topups.title' }],
+} as const