@dainamite/billing 0.20.0 → 0.22.0

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

@@ -1,12 +1,12 @@
 "use client"
 import * as React from 'react'
 import Link from 'next/link'
-import { useParams } from 'next/navigation'
+import { useParams, useRouter } from 'next/navigation'
 import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { Page, PageBody, PageHeader } from '@open-mercato/ui/backend/Page'
 import { FormHeader } from '@open-mercato/ui/backend/forms'
-import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import { BillingDataTable as DataTable } from '../../../../components/BillingDataTable'
 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'
@@ -17,6 +17,9 @@ import {
 } from '@open-mercato/ui/backend/utils/apiCall'
 import { normalizeCrudServerError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { billRunName } from '../../../../lib/billRunLabel'
+import { RunCyclesSection, type RunCycle } from '../../../../components/RunCyclesSection'
+import { TestRunActions, billRunMode } from '../../../../components/TestRunActions'
+import { PostRunDraftsButton } from '../../../../components/PostRunDraftsButton'
 import {
   DetailCard,
   DetailField,
@@ -42,7 +45,6 @@ type BillRun = {
   parent_run_id: string | null
   dry_run: boolean
   test_mode: boolean
-  catch_up: boolean
   as_of_date: string
   started_at: string | null
   finished_at: string | null
@@ -50,6 +52,7 @@ type BillRun = {
   summary: {
     accounts_processed?: number
     drafts_created?: number
+    cycles_processed?: number
     drafts_skipped_existing?: number
     accounts_failed?: number
     accounts_with_warnings?: number
@@ -71,6 +74,7 @@ type BillRunOutcome = {
   warnings: Record<string, unknown> | null
   draft_invoice_id: string | null
   invoice_number: string | null
+  cycles: RunCycle[] | null
   created_at: string
 }
 
@@ -180,6 +184,7 @@ export default function BillRunDetailPage(props: { params?: { id?: string } }) {
     void loadOutcomes()
   }, [loadOutcomes])
 
+  const router = useRouter()
   const failedCount = run?.summary?.accounts_failed ?? 0
 
   const handleRetryFailed = React.useCallback(async () => {
@@ -259,10 +264,10 @@ export default function BillRunDetailPage(props: { params?: { id?: string } }) {
         accessorKey: 'warnings',
         header: t('billing.runs.outcomes.columns.warnings', 'Warnings'),
         cell: ({ row }) => {
-          if (!row.original.warnings) return '—'
-          return (
-            <span className="font-mono text-xs">{JSON.stringify(row.original.warnings)}</span>
-          )
+          // Skipped items get their own table below; show the rest inline.
+          const { skipped_items: _skipped, ...rest } = row.original.warnings ?? {}
+          if (Object.keys(rest).length === 0) return '—'
+          return <span className="font-mono text-xs">{JSON.stringify(rest)}</span>
         },
       },
     ],
@@ -302,14 +307,37 @@ export default function BillRunDetailPage(props: { params?: { id?: string } }) {
           <Tag variant={runStatusVariant(run.status)}>{run.status}</Tag>
         }
         actionsContent={
-          failedCount > 0 ? (
-            <Button disabled={retrying} onClick={handleRetryFailed}>
-              {retrying
-                ? t('billing.runs.retry.in_progress', 'Retrying…')
-                : t('billing.runs.retry.action', 'Retry failed accounts')}
-              {` (${failedCount})`}
-            </Button>
-          ) : null
+          <>
+            {failedCount > 0 ? (
+              <Button disabled={retrying} onClick={handleRetryFailed}>
+                {retrying
+                  ? t('billing.runs.retry.in_progress', 'Retrying…')
+                  : t('billing.runs.retry.action', 'Retry failed accounts')}
+                {` (${failedCount})`}
+              </Button>
+            ) : null}
+            {run.status !== 'running' && billRunMode(run) === 'real' ? (
+              <PostRunDraftsButton
+                runId={run.id}
+                onPosted={() => {
+                  void loadRun()
+                  void loadOutcomes()
+                }}
+              />
+            ) : null}
+            {run.status !== 'running' ? (
+              <TestRunActions
+                runId={run.id}
+                mode={billRunMode(run)}
+                draftsCount={run.summary?.drafts_created}
+                onWiped={() => {
+                  void loadRun()
+                  void loadOutcomes()
+                }}
+                onDeleted={() => router.push('/backend/billing/runs')}
+              />
+            ) : null}
+          </>
         }
       />
       <PageBody>
@@ -330,9 +358,6 @@ export default function BillRunDetailPage(props: { params?: { id?: string } }) {
                 ) : (
                   <Tag variant="default">{t('billing.runs.mode.real', 'Real')}</Tag>
                 )}
-                {run.catch_up ? (
-                  <Tag variant="default">{t('billing.runs.mode.catch_up', 'Catch-up')}</Tag>
-                ) : null}
               </div>
             </DetailField>
             <DetailField label={t('billing.runs.detail.field.as_of_date', 'As-of date')}>
@@ -361,6 +386,10 @@ export default function BillRunDetailPage(props: { params?: { id?: string } }) {
                 label={t('billing.runs.summary.drafts', 'Drafts')}
                 value={run.summary.drafts_created ?? 0}
               />
+              <Stat
+                label={t('billing.runs.summary.cycles', 'Cycles')}
+                value={run.summary.cycles_processed ?? 0}
+              />
               <Stat
                 label={t('billing.runs.summary.skipped', 'Skipped')}
                 value={run.summary.drafts_skipped_existing ?? 0}
@@ -397,6 +426,8 @@ export default function BillRunDetailPage(props: { params?: { id?: string } }) {
               }}
             />
           </div>
+
+          <RunCyclesSection outcomes={outcomes} />
         </div>
       </PageBody>
     </Page>

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

@@ -6,7 +6,10 @@ import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 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 { BillingDataTable as DataTable } from '../../../components/BillingDataTable'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import { BillingSettingsLink } from '../../../components/BillingSettingsLink'
+import { billRunMode, useTestRunCleanup } from '../../../components/TestRunActions'
 import { Tag } from '@open-mercato/ui/primitives/tag'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Input } from '@open-mercato/ui/primitives/input'
@@ -54,7 +57,6 @@ type BillRunRow = {
   parent_run_id: string | null
   dry_run: boolean
   test_mode: boolean
-  catch_up: boolean
   as_of_date: string
   started_at: string | null
   finished_at: string | null
@@ -122,6 +124,7 @@ export default function BillRunsListPage() {
   const [totalPages, setTotalPages] = React.useState(1)
   const [loading, setLoading] = React.useState(true)
   const [search, setSearch] = React.useState('')
+  const cleanup = useTestRunCleanup()
 
   // Trigger dialog — controls the New-run modal and its submit state.
   const [triggerOpen, setTriggerOpen] = React.useState(false)
@@ -145,6 +148,16 @@ export default function BillRunsListPage() {
           { value: 'failed', label: t('billing.runs.status.failed', 'Failed') },
         ],
       },
+      {
+        id: 'mode',
+        label: t('billing.runs.filters.mode', 'Mode'),
+        type: 'select',
+        options: [
+          { value: 'real', label: t('billing.runs.mode.real', 'Real') },
+          { value: 'test', label: t('billing.runs.mode.test', 'Test') },
+          { value: 'dry', label: t('billing.runs.mode.dry_run', 'Dry-run') },
+        ],
+      },
       {
         id: 'triggeredBy',
         label: t('billing.runs.filters.triggered_by', 'Trigger'),
@@ -174,6 +187,9 @@ export default function BillRunsListPage() {
       if (typeof filters.triggeredBy === 'string' && filters.triggeredBy) {
         params.set('triggeredBy', filters.triggeredBy)
       }
+      if (typeof filters.mode === 'string' && filters.mode) {
+        params.set('mode', filters.mode)
+      }
       const result = await readApiResultOrThrow<ListResponse>(
         `/api/billing/runs?${params.toString()}`,
       )
@@ -183,7 +199,7 @@ export default function BillRunsListPage() {
     } finally {
       setLoading(false)
     }
-  }, [filters.status, filters.triggeredBy, page, pageSize, search])
+  }, [filters.mode, filters.status, filters.triggeredBy, page, pageSize, search])
 
   React.useEffect(() => {
     void loadRows()
@@ -310,10 +326,13 @@ export default function BillRunsListPage() {
         <DataTable
           title={t('billing.runs.title', 'Bill Runs')}
           actions={
-            <Button onClick={() => setTriggerOpen(true)}>
-              <Play size={16} />
-              {t('billing.runs.trigger.action', 'New run')}
-            </Button>
+            <div className="flex items-center gap-2">
+              <BillingSettingsLink />
+              <Button onClick={() => setTriggerOpen(true)}>
+                <Play size={16} />
+                {t('billing.runs.trigger.action', 'New run')}
+              </Button>
+            </div>
           }
           refreshButton={{
             label: t('billing.common.refresh', 'Refresh'),
@@ -325,6 +344,37 @@ export default function BillRunsListPage() {
           columns={columns}
           data={rows}
           onRowClick={(row) => router.push(`/backend/billing/runs/${row.id}`)}
+          rowActions={(row) => {
+            const mode = billRunMode(row)
+            return (
+              <RowActions
+                items={[
+                  {
+                    id: 'open',
+                    label: t('billing.runs.actions.open', 'Open'),
+                    href: `/backend/billing/runs/${row.id}`,
+                  },
+                  ...(mode !== 'real' && row.status !== 'running'
+                    ? [
+                        {
+                          id: 'delete',
+                          label: t('billing.runs.delete.action', 'Delete run'),
+                          destructive: true,
+                          onSelect: async () => {
+                            const removed = await cleanup.remove({
+                              runId: row.id,
+                              mode,
+                              draftsCount: row.summary?.drafts_created,
+                            })
+                            if (removed !== null) void loadRows()
+                          },
+                        },
+                      ]
+                    : []),
+                ]}
+              />
+            )
+          }}
           isLoading={loading}
           pagination={{
             page,
@@ -391,7 +441,7 @@ export default function BillRunsListPage() {
                 <span className="text-xs text-muted-foreground">
                   {t(
                     'billing.runs.trigger.dialog.as_of_date.help',
-                    'Accounts whose next bill date is on or before this date will be billed.',
+                    'Bills every due cycle up to this date — one draft per bill date. Test and dry-run simulate them without changing accounts.',
                   )}
                 </span>
               </label>
@@ -420,6 +470,7 @@ export default function BillRunsListPage() {
             </DialogFooter>
           </DialogContent>
         </Dialog>
+        {cleanup.ConfirmDialogElement}
       </PageBody>
     </Page>
   )

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

@@ -8,7 +8,7 @@ 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 { BillingDataTable as DataTable } from '../../../../components/BillingDataTable'
 import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { DetailCard, DetailField } from '../../../../components/DetailFields'
@@ -19,9 +19,19 @@ type BreakdownEntry = {
   billing_type: string
   uom_code?: string
   quantity: string
+  /** What left the balance. */
   amount: string
+  // Spec F — older statements do not carry these.
+  description?: string
+  net?: string
+  tax?: string
+  tax_rate?: string
+  service_period_start?: string | null
+  service_period_end?: string | null
 }
 
+type VatSummaryEntry = { rate: string; net: string; tax: string; gross: string }
+
 type StatementRow = {
   id: string
   bill_account_id: string
@@ -36,6 +46,7 @@ type StatementRow = {
   total_adjustments: string
   closing_balance: string
   debit_breakdown: { items?: BreakdownEntry[] } | null
+  vat_summary?: VatSummaryEntry[] | null
   status: string
 }
 
@@ -80,6 +91,9 @@ export default function BillingStatementDetailPage(props: { params?: { id?: stri
   }, [statementId, t])
 
   const breakdown = row?.debit_breakdown?.items ?? []
+  const vatSummary = row?.vat_summary ?? []
+  // Spec F: VAT columns only when VAT was charged at consumption.
+  const showVat = vatSummary.length > 0
   const columns = React.useMemo<ColumnDef<BreakdownEntry>[]>(
     () => [
       {
@@ -90,19 +104,75 @@ export default function BillingStatementDetailPage(props: { params?: { id?: stri
       {
         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>,
+        cell: ({ row }) => (
+          <Link href={`/backend/billing/items/${row.original.billing_item_id}`} className="text-sm text-primary hover:underline">
+            {row.original.description ?? row.original.billing_item_id}
+          </Link>
+        ),
+      },
+      {
+        accessorKey: 'service_period_start',
+        header: t('billing.statements.breakdown.service_period', 'Service period'),
+        cell: ({ row }) =>
+          row.original.service_period_start
+            ? `${row.original.service_period_start} – ${row.original.service_period_end ?? '…'}`
+            : '—',
       },
       {
         accessorKey: 'quantity',
         header: t('billing.statements.breakdown.quantity', 'Qty'),
         cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.quantity}</span>,
       },
+      ...(showVat
+        ? [
+            {
+              accessorKey: 'net',
+              header: t('billing.statements.breakdown.net', 'Net'),
+              cell: ({ row }: { row: { original: BreakdownEntry } }) => (
+                <span className="font-mono tabular-nums">{row.original.net ?? '—'}</span>
+              ),
+            } satisfies ColumnDef<BreakdownEntry>,
+            {
+              accessorKey: 'tax',
+              header: t('billing.statements.breakdown.vat', 'VAT'),
+              cell: ({ row }: { row: { original: BreakdownEntry } }) =>
+                row.original.tax !== undefined ? (
+                  <span className="font-mono tabular-nums">
+                    {row.original.tax} ({row.original.tax_rate ?? '0'} %)
+                  </span>
+                ) : (
+                  '—'
+                ),
+            } satisfies ColumnDef<BreakdownEntry>,
+          ]
+        : []),
       {
         accessorKey: 'amount',
-        header: t('billing.statements.breakdown.amount', 'Amount'),
+        header: t('billing.statements.breakdown.charged', 'Charged to balance'),
         cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.amount}</span>,
       },
     ],
+    [showVat, t],
+  )
+  const vatColumns = React.useMemo<ColumnDef<VatSummaryEntry>[]>(
+    () => [
+      { accessorKey: 'rate', header: t('billing.statements.vat.rate', 'VAT rate'), cell: ({ row }) => `${row.original.rate} %` },
+      {
+        accessorKey: 'net',
+        header: t('billing.statements.breakdown.net', 'Net'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.net}</span>,
+      },
+      {
+        accessorKey: 'tax',
+        header: t('billing.statements.breakdown.vat', 'VAT'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.tax}</span>,
+      },
+      {
+        accessorKey: 'gross',
+        header: t('billing.statements.vat.gross', 'Gross'),
+        cell: ({ row }) => <span className="font-mono tabular-nums">{row.original.gross}</span>,
+      },
+    ],
     [t],
   )
 
@@ -156,7 +226,7 @@ export default function BillingStatementDetailPage(props: { params?: { id?: stri
           <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')}>
+          <DetailField label={t('billing.statements.columns.charges', 'Charges')}>
             <span className="font-mono tabular-nums">{row.total_recurring}</span>
           </DetailField>
           <DetailField label={t('billing.statements.columns.adjustments', 'Adjustments')}>
@@ -185,13 +255,24 @@ export default function BillingStatementDetailPage(props: { params?: { id?: stri
             title={t('billing.statements.detail.breakdown', 'Period-close charges')}
             columns={columns}
             data={breakdown}
+            pagination={{ page: 1, pageSize: 100, total: breakdown.length, totalPages: 1, onPageChange: () => undefined }}
             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.')}
+                {t('billing.statements.detail.no_charges', 'No charges at this bill date.')}
               </div>
             }
           />
         </div>
+        {showVat ? (
+          <div className="mt-6">
+            <DataTable
+              title={t('billing.statements.detail.vat_summary', 'VAT summary')}
+              columns={vatColumns}
+              data={vatSummary}
+              pagination={{ page: 1, pageSize: 100, total: vatSummary.length, totalPages: 1, onPageChange: () => undefined }}
+            />
+          </div>
+        ) : null}
       </PageBody>
     </Page>
   )

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

@@ -5,7 +5,7 @@ import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 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 { BillingDataTable as DataTable } from '../../../components/BillingDataTable'
 import { Tag } from '@open-mercato/ui/primitives/tag'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { fetchAccountNames } from '../../../components/accountNames'

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

@@ -5,7 +5,7 @@ import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 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 { BillingDataTable as DataTable } from '../../../components/BillingDataTable'
 import { Tag } from '@open-mercato/ui/primitives/tag'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { fetchAccountNames } from '../../../components/accountNames'

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

@@ -5,7 +5,7 @@ import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 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 { BillingDataTable as DataTable } from '../../../components/BillingDataTable'
 import { Tag } from '@open-mercato/ui/primitives/tag'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { fetchAccountNames } from '../../../components/accountNames'

package/src/modules/billing/backend/billing/usage/create/page.tsx

@@ -15,6 +15,7 @@ import {
   type UsageAccountOption,
   type AssembledUsagePayload,
 } from '../../../../components/UsageForm'
+import { accountHref } from '../../../../lib/navigation'
 
 /**
  * `/backend/billing/usage/create` — manually record a usage entry.
@@ -75,7 +76,7 @@ export default function CreateBillingUsagePage() {
         } else {
           flash(t('billing.usage.create.success', 'Usage record created'), 'success')
         }
-        router.push(`/backend/billing/accounts/${payload.billAccountId}`)
+        router.push(accountHref(payload.billAccountId, 'usage'))
       } catch (err) {
         const { message } = normalizeCrudServerError(err)
         flash(
@@ -91,7 +92,7 @@ export default function CreateBillingUsagePage() {
 
   const handleCancel = React.useCallback(() => {
     if (preselectedAccountId) {
-      router.push(`/backend/billing/accounts/${preselectedAccountId}`)
+      router.push(accountHref(preselectedAccountId, 'usage'))
     } else {
       router.push('/backend/billing/accounts')
     }

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

@@ -0,0 +1,21 @@
+import React from 'react'
+import { Receipt } from 'lucide-react'
+
+const billingSettingsIcon = React.createElement(Receipt, { size: 16 })
+
+// Spec 0 — billing settings (prepaid defaults + document number masks).
+// Lives in the settings area next to other module configs. No `navHidden`:
+// the nav builder drops navHidden routes from the Settings sidebar too
+// (Spec F, F6).
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['billing.settings.view'],
+  pageTitle: 'Billing',
+  pageTitleKey: 'billing.settings.title',
+  pageGroup: 'Module Configs',
+  pageGroupKey: 'settings.sections.moduleConfigs',
+  pageOrder: 20,
+  icon: billingSettingsIcon,
+  pageContext: 'settings' as const,
+  breadcrumb: [{ label: 'Billing', labelKey: 'billing.settings.title' }],
+} as const