@dainamite/billing 0.20.0 → 0.21.0

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.')}
+    />
+  )
+}

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

@@ -0,0 +1,153 @@
+"use client"
+import * as React from 'react'
+import Link from 'next/link'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { Stat, StatCard } from '../DetailFields'
+import { formatMoney } from '../InvoicesTable'
+
+/**
+ * Billing Account workspace header (Spec E §4 / Spec F, F8): what the
+ * operator needs at a glance, from ONE call to
+ * `GET /api/billing/accounts/{id}/summary`. Postpaid shows receivables;
+ * prepaid shows the balance. Informational — a failed load hides the cards.
+ */
+
+export type AccountWorkspaceSummary = {
+  currency_code: string
+  open_amount: string
+  overdue_amount: string
+  overdue_count: number
+  credit_amount: string
+  billing_mode: 'postpaid' | 'prepaid'
+  bill_cycle: string
+  next_bill_date: string | null
+  last_invoice: { id: string; number: string; issue_date: string | null; total_gross: string } | null
+  prepaid: {
+    balance: string
+    balance_status: 'ok' | 'low' | 'exhausted'
+    credit_limit: string
+    last_statement: { id: string; period_start: string; period_end: string; closing_balance: string } | null
+  } | null
+}
+
+function balanceVariant(status: 'ok' | 'low' | 'exhausted'): 'success' | 'warning' | 'error' {
+  if (status === 'exhausted') return 'error'
+  if (status === 'low') return 'warning'
+  return 'success'
+}
+
+export function AccountSummaryCards({ accountId, refreshKey = 0 }: { accountId: string; refreshKey?: number }) {
+  const t = useT()
+  const [summary, setSummary] = React.useState<AccountWorkspaceSummary | null>(null)
+
+  React.useEffect(() => {
+    let cancelled = false
+    readApiResultOrThrow<AccountWorkspaceSummary>(`/api/billing/accounts/${encodeURIComponent(accountId)}/summary`)
+      .then((result) => {
+        if (!cancelled) setSummary(result)
+      })
+      .catch(() => {
+        if (!cancelled) setSummary(null)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [accountId, refreshKey])
+
+  if (!summary) return null
+  const currency = summary.currency_code
+  const statusLabel = (status: 'ok' | 'low' | 'exhausted') =>
+    status === 'exhausted'
+      ? t('billing.prepaid.status.exhausted', 'Exhausted')
+      : status === 'low'
+        ? t('billing.prepaid.status.low', 'Low')
+        : t('billing.prepaid.status.ok', 'OK')
+
+  return (
+    <StatCard>
+      {summary.prepaid ? (
+        <>
+          <Stat
+            label={t('billing.accounts.summary.balance', 'Balance')}
+            value={
+              <span className="inline-flex items-center gap-2">
+                {formatMoney(summary.prepaid.balance, currency)}
+                <Tag variant={balanceVariant(summary.prepaid.balance_status)}>
+                  {statusLabel(summary.prepaid.balance_status)}
+                </Tag>
+              </span>
+            }
+          />
+          <Stat
+            label={t('billing.accounts.columns.credit_limit', 'Credit limit')}
+            value={formatMoney(summary.prepaid.credit_limit, currency)}
+          />
+        </>
+      ) : (
+        <>
+          <Stat
+            label={t('billing.accounts.summary.balance_due', 'Balance due')}
+            value={formatMoney(summary.open_amount, currency)}
+          />
+          <Stat
+            label={t('billing.accounts.summary.overdue', 'Overdue')}
+            value={
+              <span className={Number(summary.overdue_amount) > 0 ? 'text-status-error-text' : undefined}>
+                {formatMoney(summary.overdue_amount, currency)} ({summary.overdue_count})
+              </span>
+            }
+          />
+          <Stat
+            label={t('billing.accounts.summary.credit', 'Unapplied credit')}
+            value={formatMoney(summary.credit_amount, currency)}
+          />
+        </>
+      )}
+      <Stat
+        label={t('billing.accounts.columns.next_bill', 'Next bill')}
+        value={
+          summary.next_bill_date ? (
+            <span>
+              {summary.next_bill_date}
+              <span className="ml-1 text-xs font-normal text-muted-foreground">· {summary.bill_cycle}</span>
+            </span>
+          ) : (
+            '—'
+          )
+        }
+      />
+      {summary.prepaid ? (
+        <Stat
+          label={t('billing.accounts.summary.last_statement', 'Last statement')}
+          value={
+            summary.prepaid.last_statement ? (
+              <Link
+                href={`/backend/billing/statements/${summary.prepaid.last_statement.id}`}
+                className="text-primary hover:underline"
+              >
+                {summary.prepaid.last_statement.period_start} – {summary.prepaid.last_statement.period_end}
+              </Link>
+            ) : (
+              '—'
+            )
+          }
+        />
+      ) : (
+        <Stat
+          label={t('billing.accounts.summary.last_invoice', 'Last invoice')}
+          value={
+            summary.last_invoice ? (
+              <Link href={`/backend/billing/invoices/${summary.last_invoice.id}`} className="text-primary hover:underline">
+                {summary.last_invoice.number} · {formatMoney(summary.last_invoice.total_gross, currency)}
+              </Link>
+            ) : (
+              '—'
+            )
+          }
+        />
+      )}
+    </StatCard>
+  )
+}