@dainamite/billing 0.20.0 → 0.22.0

package/src/modules/billing/components/CreateMemoDialog.tsx

@@ -0,0 +1,232 @@
+"use client"
+import * as React from 'react'
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Textarea } from '@open-mercato/ui/primitives/textarea'
+import { Checkbox } from '@open-mercato/ui/primitives/checkbox'
+import { Kbd, KbdShortcut } from '@open-mercato/ui/primitives/kbd'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { normalizeCrudServerError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { formatMoney } from './InvoicesTable'
+
+/**
+ * Create a credit or debit memo for a posted invoice (Spec D, D-D9).
+ *
+ *   - credit memo: the original lines with a checkbox and editable quantity /
+ *     unit net (VAT rate stays the original's), a "Full credit" shortcut,
+ *     the required reason and the projected totals;
+ *   - debit memo: the reason only — lines are added on the draft.
+ *
+ * Creates a DRAFT memo and hands its id back (the page navigates to it).
+ * Cmd/Ctrl+Enter submits, Escape cancels.
+ */
+
+export type MemoSourceLine = {
+  id: string
+  description: string | null
+  quantity: string
+  unit_price_net: string
+  tax_rate: string | number | null
+}
+
+type LineState = { selected: boolean; quantity: string; unitPriceNet: string }
+
+function round2(value: number): number {
+  return Math.round((value + Number.EPSILON) * 100) / 100
+}
+
+export function CreateMemoDialog({
+  open,
+  type,
+  invoiceId,
+  invoiceNumber,
+  currencyCode,
+  lines,
+  onClose,
+  onCreated,
+}: {
+  open: boolean
+  type: 'credit_memo' | 'debit_memo'
+  invoiceId: string
+  invoiceNumber: string
+  currencyCode: string
+  lines: MemoSourceLine[]
+  onClose: () => void
+  onCreated: (memoId: string) => void
+}) {
+  const t = useT()
+  const [reason, setReason] = React.useState('')
+  const [state, setState] = React.useState<Record<string, LineState>>({})
+  const [saving, setSaving] = React.useState(false)
+
+  const fullCredit = React.useCallback(() => {
+    setState(
+      Object.fromEntries(
+        lines.map((line) => [
+          line.id,
+          { selected: true, quantity: String(Number(line.quantity)), unitPriceNet: String(Math.abs(Number(line.unit_price_net))) },
+        ]),
+      ),
+    )
+  }, [lines])
+
+  React.useEffect(() => {
+    if (!open) return
+    setReason('')
+    if (type === 'credit_memo') fullCredit()
+    else setState({})
+  }, [fullCredit, open, type])
+
+  const selected = lines.filter((line) => state[line.id]?.selected)
+  const projected = selected.reduce(
+    (acc, line) => {
+      const s = state[line.id]
+      const net = round2((Number.parseFloat(s.quantity) || 0) * (Number.parseFloat(s.unitPriceNet) || 0))
+      const tax = round2(net * ((Number(line.tax_rate) || 0) / 100))
+      return { net: acc.net + net, tax: acc.tax + tax }
+    },
+    { net: 0, tax: 0 },
+  )
+
+  const update = (id: string, patch: Partial<LineState>) =>
+    setState((prev) => ({ ...prev, [id]: { ...prev[id], ...patch } }))
+
+  const submit = React.useCallback(async () => {
+    if (saving) return
+    if (!reason.trim()) {
+      flash(t('billing.memo.error.reason_required', 'A reason is required'), 'error')
+      return
+    }
+    if (type === 'credit_memo' && selected.length === 0) {
+      flash(t('billing.memo.error.no_lines', 'Select at least one line to credit'), 'error')
+      return
+    }
+    setSaving(true)
+    try {
+      const body =
+        type === 'credit_memo'
+          ? {
+              type,
+              reason: reason.trim(),
+              lines: selected.map((line) => ({
+                correctsLineId: line.id,
+                description: line.description ?? '',
+                quantity: Number.parseFloat(state[line.id].quantity),
+                unitPriceNet: Number.parseFloat(state[line.id].unitPriceNet),
+              })),
+            }
+          : { type, reason: reason.trim() }
+      const call = await apiCallOrThrow<{ memoId: string }>(`/api/billing/invoices/${encodeURIComponent(invoiceId)}/memos`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+      flash(t('billing.memo.created', 'Draft memo created'), 'success')
+      onClose()
+      if (call.result?.memoId) onCreated(call.result.memoId)
+    } catch (err) {
+      const code = (err as { body?: { code?: string } } | null)?.body?.code
+      flash(
+        code === 'billing.memo.exceeds_invoice'
+          ? t('billing.memo.error.exceeds', 'The credit is more than what is left to credit on this invoice')
+          : normalizeCrudServerError(err).message || t('billing.memo.error.create', 'Could not create the memo'),
+        'error',
+      )
+    } finally {
+      setSaving(false)
+    }
+  }, [invoiceId, onClose, onCreated, reason, saving, selected, state, t, type])
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => (!next ? onClose() : undefined)}>
+      <DialogContent
+        className="max-w-3xl"
+        onKeyDown={(event) => {
+          if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+            event.preventDefault()
+            void submit()
+          }
+        }}
+      >
+        <DialogHeader>
+          <DialogTitle>
+            {type === 'credit_memo'
+              ? t('billing.memo.create_credit.title', 'Create credit memo')
+              : t('billing.memo.create_debit.title', 'Create debit memo')}
+          </DialogTitle>
+          <DialogDescription>
+            {t('billing.memo.corrects', 'Corrects')} {invoiceNumber} ·{' '}
+            {t('billing.memo.hint', 'Corrects this document only. Update the billing item to change future invoices.')}
+          </DialogDescription>
+        </DialogHeader>
+        <div className="flex flex-col gap-3 py-2 text-sm">
+          {type === 'credit_memo' ? (
+            <>
+              <div className="flex items-center justify-between">
+                <span className="font-medium">{t('billing.memo.lines', 'Lines to credit')}</span>
+                <Button type="button" variant="outline" size="sm" onClick={fullCredit}>
+                  {t('billing.memo.full_credit', 'Full credit')}
+                </Button>
+              </div>
+              <div className="max-h-72 overflow-auto rounded-md border">
+                {lines.map((line) => {
+                  const s = state[line.id] ?? { selected: false, quantity: '', unitPriceNet: '' }
+                  return (
+                    <div key={line.id} className="grid grid-cols-[24px_1fr_90px_110px_60px] items-center gap-2 border-b px-2 py-1 last:border-b-0">
+                      <Checkbox checked={s.selected} onCheckedChange={(next) => update(line.id, { selected: next === true })} />
+                      <span className="truncate">{line.description}</span>
+                      <Input
+                        type="number"
+                        min="0"
+                        step="0.0001"
+                        value={s.quantity}
+                        disabled={!s.selected}
+                        onChange={(e) => update(line.id, { quantity: e.currentTarget.value })}
+                      />
+                      <Input
+                        type="number"
+                        min="0"
+                        step="0.01"
+                        value={s.unitPriceNet}
+                        disabled={!s.selected}
+                        onChange={(e) => update(line.id, { unitPriceNet: e.currentTarget.value })}
+                      />
+                      <span className="text-right text-xs text-muted-foreground">{Number(line.tax_rate ?? 0)} %</span>
+                    </div>
+                  )
+                })}
+              </div>
+              <div className="text-right text-muted-foreground">
+                {t('billing.memo.projected', 'Credit')}: {formatMoney(String(projected.net), currencyCode)} +{' '}
+                {t('billing.invoices.lines.columns.tax_amount', 'VAT')} {formatMoney(String(projected.tax), currencyCode)} ={' '}
+                <span className="font-medium text-foreground">{formatMoney(String(projected.net + projected.tax), currencyCode)}</span>
+              </div>
+            </>
+          ) : null}
+          <label className="flex flex-col gap-1">
+            <span className="text-muted-foreground">{t('billing.memo.reason', 'Reason (printed on the document)')} *</span>
+            <Textarea rows={2} maxLength={1000} value={reason} onChange={(e) => setReason(e.currentTarget.value)} />
+          </label>
+        </div>
+        <DialogFooter>
+          <div className="flex w-full items-center justify-between gap-3">
+            <span className="text-xs text-muted-foreground">
+              <KbdShortcut keys={['Ctrl/⌘', 'Enter']} /> · <Kbd>Esc</Kbd>
+            </span>
+            <div className="flex items-center gap-2">
+              <Button type="button" variant="outline" onClick={onClose}>
+                {t('billing.common.cancel', 'Cancel')}
+              </Button>
+              <Button type="button" onClick={() => void submit()} disabled={saving}>
+                {t('billing.memo.create', 'Create draft')}
+              </Button>
+            </div>
+          </div>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/modules/billing/components/CustomerLabel.tsx

@@ -0,0 +1,53 @@
+"use client"
+import * as React from 'react'
+import Link from 'next/link'
+import { Building2, User } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import type { CustomerKind } from '../data/validators'
+import { customerDetailHref } from '../lib/customerLookup'
+
+/**
+ * Customer reference for billing views (Spec E): kind icon + resolved
+ * display name, falling back to the raw id when the customers lookup is
+ * unavailable. `linkToCustomer` turns the name into a link to the customer
+ * record in the customers module.
+ */
+export function CustomerLabel({
+  customerId,
+  customerKind,
+  name,
+  linkToCustomer = false,
+}: {
+  customerId: string
+  customerKind: CustomerKind
+  name?: string | null
+  linkToCustomer?: boolean
+}) {
+  const t = useT()
+  const kindLabel =
+    customerKind === 'person'
+      ? t('billing.accounts.kind.person', 'Person')
+      : t('billing.accounts.kind.company', 'Company')
+  const Icon = customerKind === 'person' ? User : Building2
+  const text = name ? (
+    <span>{name}</span>
+  ) : (
+    <span className="font-mono text-xs">{customerId}</span>
+  )
+  return (
+    <span className="inline-flex items-center gap-1.5" title={kindLabel}>
+      <Icon size={14} aria-label={kindLabel} className="shrink-0 text-muted-foreground" />
+      {linkToCustomer ? (
+        <Link
+          href={customerDetailHref(customerKind, customerId)}
+          className="underline-offset-2 hover:underline"
+          onClick={(event) => event.stopPropagation()}
+        >
+          {text}
+        </Link>
+      ) : (
+        text
+      )}
+    </span>
+  )
+}

package/src/modules/billing/components/InvoicesTable.tsx

@@ -0,0 +1,344 @@
+"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 type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { BillingDataTable as DataTable } from './BillingDataTable'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { invoiceDetailHref, invoicePdfHref } from '../lib/navigation'
+import { displaySign } from '../lib/documentTypes'
+
+/**
+ * Billing documents table (Spec B) — shared by the global Invoices list and
+ * the Invoices section of a billing account (and, later, Spec E's tab).
+ *
+ *   - `billAccountId` pins the list to one account (no account column; rows
+ *     open the invoice with a return link to the account).
+ *   - Filters: status, overdue (computed server-side, B-D6), document type,
+ *     test runs. Columns include due date, outstanding and days overdue.
+ *   - Row action: download the PDF (frozen when posted, preview for drafts).
+ *
+ * Server-paginated via `GET /api/billing/invoices` (pageSize ≤ 100).
+ */
+
+export type BillingInvoiceRow = {
+  id: string
+  number: string
+  document_type: 'invoice' | 'credit_memo' | 'debit_memo' | 'receipt'
+  status: 'draft' | 'posted' | 'partially_paid' | 'paid' | 'credited'
+  test_run: boolean
+  bill_account_id: string
+  bill_account_name: string | null
+  bill_run_id: string | null
+  bill_date: string | null
+  period_start: string | null
+  period_end: string | null
+  currency_code: string
+  issue_date: string | null
+  due_date: string | null
+  subtotal_net: string
+  total_gross: string
+  paid_total: string
+  outstanding: string
+  days_overdue: number
+  created_at: string
+  updated_at: string
+}
+
+type ListResponse = {
+  items: BillingInvoiceRow[]
+  total: number
+  totalPages: number
+}
+
+export type InvoicesTableProps = {
+  title: string
+  /** Pin the table to one account (account Invoices section). */
+  billAccountId?: string
+  /** Stable perspective / extension id. */
+  tableId: string
+  pageSize?: number
+  /** Extra header actions (e.g. the billing settings shortcut). */
+  actions?: React.ReactNode
+}
+
+function formatDate(value: string | null | undefined): string {
+  if (!value) return '—'
+  const parsed = new Date(value)
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleDateString()
+}
+
+export function formatMoney(value: string, currency: string): string {
+  const n = Number.parseFloat(value)
+  if (!Number.isFinite(n)) return value
+  try {
+    return new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(n)
+  } catch {
+    return `${value} ${currency}`
+  }
+}
+
+export function invoiceStatusVariant(status: BillingInvoiceRow['status']): 'default' | 'success' | 'warning' | 'error' {
+  switch (status) {
+    case 'paid':
+    case 'credited':
+      return 'success'
+    case 'posted':
+    case 'partially_paid':
+      return 'warning'
+    case 'draft':
+    default:
+      return 'default'
+  }
+}
+
+export function InvoicesTable({ title, billAccountId, tableId, pageSize = 25, actions }: InvoicesTableProps) {
+  const t = useT()
+  const router = useRouter()
+  const [rows, setRows] = React.useState<BillingInvoiceRow[]>([])
+  const [page, setPage] = React.useState(1)
+  const [filters, setFilters] = React.useState<FilterValues>({})
+  const [search, setSearch] = React.useState('')
+  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 statusLabel = React.useCallback(
+    (status: BillingInvoiceRow['status']) =>
+      ({
+        draft: t('billing.invoices.status.draft', 'Draft'),
+        posted: t('billing.invoices.status.posted', 'Posted'),
+        partially_paid: t('billing.invoices.status.partially_paid', 'Partially paid'),
+        paid: t('billing.invoices.status.paid', 'Paid'),
+        credited: t('billing.invoices.status.credited', 'Credited'),
+      })[status] ?? status,
+    [t],
+  )
+
+  const filterDefs = React.useMemo<FilterDef[]>(
+    () => [
+      {
+        id: 'status',
+        label: t('billing.invoices.filters.status', 'Status'),
+        type: 'select',
+        options: (['draft', 'posted', 'partially_paid', 'paid', 'credited'] as const).map((value) => ({
+          value,
+          label: statusLabel(value),
+        })),
+      },
+      {
+        id: 'overdue',
+        label: t('billing.invoices.filters.overdue', 'Overdue'),
+        type: 'select',
+        options: [
+          { value: 'true', label: t('billing.invoices.filters.overdue.only', 'Only overdue') },
+          { value: 'false', label: t('billing.invoices.filters.overdue.exclude', 'Not overdue') },
+        ],
+      },
+      {
+        id: 'documentType',
+        label: t('billing.invoices.filters.document_type', 'Document type'),
+        type: 'select',
+        options: [
+          { value: 'invoice', label: t('billing.invoices.document_type.invoice', 'Invoice') },
+          { value: 'credit_memo', label: t('billing.invoices.document_type.credit_memo', 'Credit memo') },
+          { value: 'debit_memo', label: t('billing.invoices.document_type.debit_memo', 'Debit memo') },
+          { value: 'receipt', label: t('billing.invoices.document_type.receipt', 'Top-up receipt') },
+        ],
+      },
+      {
+        id: 'testRun',
+        label: t('billing.invoices.filters.test_run', 'Test runs'),
+        type: 'select',
+        options: [
+          { value: 'true', label: t('billing.invoices.filters.test_run.only', 'Only test') },
+          { value: 'false', label: t('billing.invoices.filters.test_run.exclude', 'Exclude test') },
+        ],
+      },
+    ],
+    [statusLabel, t],
+  )
+
+  const loadRows = React.useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const params = new URLSearchParams({ page: String(page), pageSize: String(Math.min(pageSize, 100)) })
+      if (billAccountId) params.set('billAccountId', billAccountId)
+      if (search.trim()) params.set('search', search.trim())
+      for (const key of ['status', 'documentType'] as const) {
+        const value = filters[key]
+        if (typeof value === 'string' && value) params.set(key, value)
+      }
+      for (const key of ['testRun', 'overdue'] as const) {
+        const value = filters[key]
+        if (value === 'true' || value === 'false') params.set(key, value)
+      }
+      const result = await readApiResultOrThrow<ListResponse>(`/api/billing/invoices?${params.toString()}`)
+      setRows(result.items ?? [])
+      setTotal(result.total ?? 0)
+      setTotalPages(result.totalPages ?? 1)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : t('billing.invoices.error.load', 'Could not load invoices'))
+    } finally {
+      setLoading(false)
+    }
+  }, [billAccountId, filters, page, pageSize, search, t])
+
+  React.useEffect(() => {
+    void loadRows()
+  }, [loadRows])
+
+  const columns = React.useMemo<ColumnDef<BillingInvoiceRow>[]>(() => {
+    const cols: ColumnDef<BillingInvoiceRow>[] = [
+      {
+        accessorKey: 'number',
+        header: t('billing.invoices.columns.number', 'Number'),
+        cell: ({ row }) => (
+          <div className="flex items-center gap-2">
+            <span className="text-sm font-medium text-primary">{row.original.number}</span>
+            {row.original.test_run ? <Tag variant="warning">TEST</Tag> : null}
+          </div>
+        ),
+      },
+      {
+        accessorKey: 'document_type',
+        header: t('billing.invoices.columns.type', 'Type'),
+        cell: ({ row }) =>
+          ({
+            invoice: t('billing.invoices.document_type.invoice', 'Invoice'),
+            credit_memo: t('billing.invoices.document_type.credit_memo', 'Credit memo'),
+            debit_memo: t('billing.invoices.document_type.debit_memo', 'Debit memo'),
+            receipt: t('billing.invoices.document_type.receipt', 'Top-up receipt'),
+          })[row.original.document_type] ?? row.original.document_type,
+      },
+      {
+        accessorKey: 'status',
+        header: t('billing.invoices.columns.status', 'Status'),
+        cell: ({ row }) => (
+          <div className="flex items-center gap-1">
+            <Tag variant={invoiceStatusVariant(row.original.status)}>{statusLabel(row.original.status)}</Tag>
+            {row.original.days_overdue > 0 ? (
+              <Tag variant="error">{t('billing.invoices.overdue', 'Overdue')}</Tag>
+            ) : null}
+          </div>
+        ),
+      },
+    ]
+    if (!billAccountId) {
+      cols.push({
+        accessorKey: 'bill_account_name',
+        header: t('billing.invoices.columns.account', 'Account'),
+        cell: ({ row }) => row.original.bill_account_name ?? '—',
+        meta: { truncate: true, maxWidth: '220px' },
+      })
+    }
+    cols.push(
+      {
+        id: 'period',
+        header: t('billing.invoices.columns.period', 'Period'),
+        cell: ({ row }) => {
+          const start = row.original.period_start?.slice(0, 10)
+          const end = row.original.period_end?.slice(0, 10)
+          if (!start || !end) return '—'
+          return (
+            <span className="text-xs">
+              {start} → {end}
+            </span>
+          )
+        },
+      },
+      {
+        id: 'total',
+        header: t('billing.invoices.columns.total', 'Total'),
+        // Credit memos are stored positive (D-D5) and shown negative.
+        cell: ({ row }) =>
+          formatMoney(
+            String(displaySign(row.original.document_type) * Number.parseFloat(row.original.total_gross)),
+            row.original.currency_code,
+          ),
+      },
+      {
+        accessorKey: 'outstanding',
+        header: t('billing.invoices.columns.outstanding', 'Outstanding'),
+        cell: ({ row }) => formatMoney(row.original.outstanding, row.original.currency_code),
+      },
+      {
+        accessorKey: 'issue_date',
+        header: t('billing.invoices.columns.issued', 'Issued'),
+        cell: ({ row }) => formatDate(row.original.issue_date),
+      },
+      {
+        accessorKey: 'due_date',
+        header: t('billing.invoices.columns.due', 'Due'),
+        cell: ({ row }) => formatDate(row.original.due_date),
+      },
+      {
+        accessorKey: 'days_overdue',
+        header: t('billing.invoices.columns.days_overdue', 'Days overdue'),
+        cell: ({ row }) =>
+          row.original.days_overdue > 0 ? (
+            <span className="font-medium text-status-error-text tabular-nums">{row.original.days_overdue}</span>
+          ) : (
+            <span className="text-muted-foreground">—</span>
+          ),
+      },
+    )
+    return cols
+  }, [billAccountId, statusLabel, t])
+
+  return (
+    <DataTable
+      title={title}
+      actions={actions}
+      refreshButton={{ label: t('billing.common.refresh', 'Refresh'), onRefresh: loadRows, isRefreshing: loading }}
+      columnChooser={{ auto: true }}
+      perspective={{ tableId }}
+      columns={columns}
+      data={rows}
+      error={error}
+      emptyState={t('billing.invoices.empty', 'No invoices yet.')}
+      onRowClick={(row) => router.push(invoiceDetailHref(row.id, { fromAccountId: billAccountId }))}
+      rowActions={(row) => (
+        <RowActions
+          items={[
+            {
+              id: 'open',
+              label: t('billing.invoices.actions.open', 'Open'),
+              href: invoiceDetailHref(row.id, { fromAccountId: billAccountId }),
+            },
+            {
+              id: 'pdf',
+              label:
+                row.status === 'draft'
+                  ? t('billing.invoices.actions.pdf_preview', 'Preview PDF')
+                  : t('billing.invoices.actions.pdf', 'Download PDF'),
+              href: invoicePdfHref(row.id),
+            },
+          ]}
+        />
+      )}
+      isLoading={loading}
+      pagination={{ page, pageSize, total, totalPages, onPageChange: setPage }}
+      filters={filterDefs}
+      filterValues={filters}
+      onFiltersApply={(next) => {
+        setPage(1)
+        setFilters(next)
+      }}
+      onFiltersClear={() => {
+        setPage(1)
+        setFilters({})
+      }}
+      searchValue={search}
+      onSearchChange={(next) => {
+        setPage(1)
+        setSearch(next)
+      }}
+    />
+  )
+}