@dainamite/billing 0.20.0 → 0.21.0

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

@@ -1,243 +1,24 @@
 "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 { 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 { InvoicesTable } from '../../../components/InvoicesTable'
+import { BillingSettingsLink } from '../../../components/BillingSettingsLink'
 
 /**
- * Billing Invoices list — what the operator actually opens every
- * morning to "review and post drafts".
+ * Billing Invoices list — what the operator opens every morning to review
+ * and post drafts, and (Spec B) to chase overdue invoices.
  *
- * Scope: only invoices the billing engine emitted (`metadata.bill_run_id`
- * set). Plain `core/sales` invoices (created by sales orders, etc.)
- * are NOT shown here — billing has its own surface so the operator's
- * review queue is small and focused.
+ * Billing documents only (`billing_invoices`); core Sales invoices are a
+ * separate surface. The table itself is shared with the account page.
  */
-
-type BillingInvoiceRow = {
-  id: string
-  invoice_number: string
-  status: 'draft' | 'posted' | 'paid' | 'void' | null
-  currency_code: string
-  issue_date: string | null
-  due_date: string | null
-  subtotal_net_amount: string
-  grand_total_net_amount: string
-  grand_total_gross_amount: string
-  paid_total_amount: string
-  outstanding_amount: string
-  metadata: {
-    bill_run_id?: string
-    bill_account_id?: string
-    bill_period_start?: string
-    bill_period_end?: string
-    test_run?: boolean
-  } | null
-  created_at: string
-  updated_at: string
-}
-
-type ListResponse = {
-  items: BillingInvoiceRow[]
-  total: number
-  totalPages: number
-}
-
-function formatDate(value: string | null | undefined): string {
-  if (!value) return '—'
-  const parsed = new Date(value)
-  return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleDateString()
-}
-
-function statusVariant(
-  status: BillingInvoiceRow['status'],
-): 'default' | 'success' | 'warning' | 'error' {
-  switch (status) {
-    case 'paid':
-      return 'success'
-    case 'posted':
-      return 'warning'
-    case 'void':
-      return 'error'
-    case 'draft':
-    default:
-      return 'default'
-  }
-}
-
-function formatMoney(value: string, currency: string): string {
-  const n = Number.parseFloat(value)
-  if (!Number.isFinite(n)) return value
-  try {
-    return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(n)
-  } catch {
-    return `${value} ${currency}`
-  }
-}
-
 export default function BillingInvoicesListPage() {
   const t = useT()
-  const router = useRouter()
-  const [rows, setRows] = React.useState<BillingInvoiceRow[]>([])
-  const [page, setPage] = React.useState(1)
-  const [pageSize] = React.useState(25)
-  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 filterDefs = React.useMemo<FilterDef[]>(
-    () => [
-      {
-        id: 'status',
-        label: t('billing.invoices.filters.status', 'Status'),
-        type: 'select',
-        options: [
-          { value: 'draft', label: t('billing.invoices.status.draft', 'Draft') },
-          { value: 'posted', label: t('billing.invoices.status.posted', 'Posted') },
-          { value: 'paid', label: t('billing.invoices.status.paid', 'Paid') },
-          { value: 'void', label: t('billing.invoices.status.void', 'Void') },
-        ],
-      },
-      {
-        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'),
-          },
-        ],
-      },
-    ],
-    [t],
-  )
-
-  const loadRows = React.useCallback(async () => {
-    setLoading(true)
-    try {
-      const params = new URLSearchParams({
-        page: String(page),
-        pageSize: String(pageSize),
-      })
-      if (search.trim()) params.set('search', search.trim())
-      if (typeof filters.status === 'string' && filters.status) {
-        params.set('status', filters.status)
-      }
-      if (filters.testRun === 'true' || filters.testRun === 'false') {
-        params.set('testRun', String(filters.testRun))
-      }
-      const result = await readApiResultOrThrow<ListResponse>(
-        `/api/billing/invoices?${params.toString()}`,
-      )
-      setRows(result.items ?? [])
-      setTotal(result.total ?? 0)
-      setTotalPages(result.totalPages ?? 1)
-    } finally {
-      setLoading(false)
-    }
-  }, [filters.status, filters.testRun, page, pageSize, search])
-
-  React.useEffect(() => {
-    void loadRows()
-  }, [loadRows])
-
-  const columns = React.useMemo<ColumnDef<BillingInvoiceRow>[]>(
-    () => [
-      {
-        accessorKey: 'invoice_number',
-        header: t('billing.invoices.columns.number', 'Number'),
-        cell: ({ row }) => {
-          const isTest = row.original.metadata?.test_run === true
-          return (
-            <div className="flex items-center gap-2">
-              <span className="text-sm font-medium text-primary">
-                {row.original.invoice_number}
-              </span>
-              {isTest ? <Tag variant="warning">TEST</Tag> : null}
-            </div>
-          )
-        },
-      },
-      {
-        accessorKey: 'status',
-        header: t('billing.invoices.columns.status', 'Status'),
-        cell: ({ row }) => (
-          <Tag variant={statusVariant(row.original.status)}>{row.original.status ?? '—'}</Tag>
-        ),
-      },
-      {
-        id: 'period',
-        header: t('billing.invoices.columns.period', 'Period'),
-        cell: ({ row }) => {
-          const start = row.original.metadata?.bill_period_start
-          const end = row.original.metadata?.bill_period_end
-          if (!start || !end) return '—'
-          return (
-            <span className="text-xs">
-              {start} → {end}
-            </span>
-          )
-        },
-      },
-      {
-        id: 'total',
-        header: t('billing.invoices.columns.total', 'Total'),
-        cell: ({ row }) =>
-          formatMoney(row.original.grand_total_gross_amount, row.original.currency_code),
-      },
-      {
-        accessorKey: 'outstanding_amount',
-        header: t('billing.invoices.columns.outstanding', 'Outstanding'),
-        cell: ({ row }) =>
-          formatMoney(row.original.outstanding_amount, row.original.currency_code),
-      },
-      {
-        accessorKey: 'issue_date',
-        header: t('billing.invoices.columns.issued', 'Issued'),
-        cell: ({ row }) => formatDate(row.original.issue_date),
-      },
-    ],
-    [t],
-  )
-
   return (
     <Page>
       <PageBody>
-        <DataTable
-          title={t('billing.invoices.title', 'Billing Invoices')}
-          refreshButton={{
-            label: t('billing.common.refresh', 'Refresh'),
-            onRefresh: loadRows,
-            isRefreshing: loading,
-          }}
-          columnChooser={{ auto: true }}
-          perspective={{ tableId: 'billing-invoices' }}
-          columns={columns}
-          data={rows}
-          onRowClick={(row) => router.push(`/backend/billing/invoices/${row.id}`)}
-          isLoading={loading}
-          pagination={{
-            page,
-            pageSize,
-            total,
-            totalPages,
-            onPageChange: setPage,
-          }}
-          filters={filterDefs}
-          filterValues={filters}
-          onFiltersApply={setFilters}
-          onFiltersClear={() => setFilters({})}
-          searchValue={search}
-          onSearchChange={setSearch}
+        <InvoicesTable title={t('billing.invoices.title', 'Billing Invoices')} tableId="billing-invoices"
+          actions={<BillingSettingsLink />}
         />
       </PageBody>
     </Page>

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

@@ -1,8 +1,8 @@
 "use client"
 import * as React from 'react'
 import Link from 'next/link'
-import { Pencil } from 'lucide-react'
-import { useParams, useRouter } from 'next/navigation'
+import { Pencil, Repeat } from 'lucide-react'
+import { useParams, useRouter, useSearchParams } from 'next/navigation'
 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'
@@ -22,6 +22,8 @@ import {
   type ItemFormValues,
 } from '../../../../components/ItemForm'
 import { DetailCard, DetailField } from '../../../../components/DetailFields'
+import { resolveItemReturnTarget } from '../../../../lib/navigation'
+import { ChangeItemPriceDialog } from '../../../../components/ChangeItemPriceDialog'
 
 /**
  * `/backend/billing/items/[id]` — Billing Item detail.
@@ -42,6 +44,8 @@ type BillingItemRow = {
   id: string
   bill_account_id: string
   bill_account_name: string | null
+  bill_account_currency?: string | null
+  bill_account_mode?: 'postpaid' | 'prepaid' | null
   type: 'one_time' | 'recurring' | 'usage'
   bill_start_date: string
   bill_end_date: string | null
@@ -53,6 +57,10 @@ type BillingItemRow = {
   source_ref: string | null
   currency_mismatch: boolean
   billed_to_date: string | null
+  charge_timing: 'in_advance' | 'in_arrears'
+  prorate: boolean
+  tax_rate: string | number | null
+  price_basis?: 'net' | 'gross'
   is_active: boolean
   created_at: string
   updated_at: string
@@ -97,6 +105,10 @@ function toFormValues(row: BillingItemRow): Partial<ItemFormValues> {
     subscriptionId: row.subscription_id ?? '',
     subscriptionItemId: row.subscription_item_id ?? '',
     isActive: row.is_active,
+    chargeTiming: row.charge_timing ?? 'in_advance',
+    prorate: row.prorate ?? true,
+    taxRate: row.tax_rate != null ? String(Number(row.tax_rate)) : '',
+    priceBasis: row.price_basis === 'gross' ? 'gross' : 'net',
   }
   if (row.type === 'one_time' && typeof rate.amount === 'number') {
     out.oneTimeAmount = String(rate.amount)
@@ -138,7 +150,17 @@ function ItemView({ row }: { row: BillingItemRow }) {
         {formatDate(row.bill_end_date)}
       </DetailField>
       <DetailField label={t('billing.items.form.rate.title', 'Rate')}>
-        {formatRate(row)}
+        <span className="inline-flex items-center gap-2">
+          <span className="tabular-nums">
+            {formatRate(row)}
+            {row.bill_account_currency && formatRate(row) !== '—' ? ` ${row.bill_account_currency}` : ''}
+          </span>
+          <Tag variant="neutral">
+            {row.price_basis === 'gross'
+              ? t('billing.items.price_basis.gross', 'Gross')
+              : t('billing.items.price_basis.net', 'Net')}
+          </Tag>
+        </span>
       </DetailField>
       <DetailField label={t('billing.items.columns.uom', 'UoM')}>
         {row.uom_code || '—'}
@@ -158,6 +180,23 @@ function ItemView({ row }: { row: BillingItemRow }) {
           '—'
         )}
       </DetailField>
+      <DetailField label={t('billing.items.form.tax_rate', 'VAT rate (%)')}>
+        {row.tax_rate != null ? `${Number(row.tax_rate)} %` : '—'}
+      </DetailField>
+      {row.type === 'recurring' ? (
+        <>
+          <DetailField label={t('billing.items.form.charge_timing', 'Charge timing')}>
+            <Tag variant="neutral">
+              {row.charge_timing === 'in_arrears'
+                ? t('billing.items.charge_timing.in_arrears', 'In arrears')
+                : t('billing.items.charge_timing.in_advance', 'In advance')}
+            </Tag>
+          </DetailField>
+          <DetailField label={t('billing.items.form.prorate', 'Prorate partial periods')}>
+            {row.prorate === false ? t('billing.common.no', 'No') : t('billing.common.yes', 'Yes')}
+          </DetailField>
+        </>
+      ) : null}
       <DetailField label={t('billing.items.detail.field.billed_to', 'Billed through')}>
         {row.billed_to_date ? formatDate(row.billed_to_date) : '—'}
       </DetailField>
@@ -185,10 +224,15 @@ function ItemView({ row }: { row: BillingItemRow }) {
 export default function BillingItemDetailPage(props: { params?: { id?: string } }) {
   const t = useT()
   const router = useRouter()
+  const [changePriceOpen, setChangePriceOpen] = React.useState(false)
   // OM serves backend pages through a catch-all route — the dynamic
   // `[id]` segment arrives as a page prop; `useParams()` is the fallback.
   const urlParams = useParams<{ id: string }>()
   const itemId = (props.params?.id ?? urlParams?.id ?? '') as string
+  // Spec E (D23): back / after-delete return to the owning account, unless
+  // the item was opened from the global Items list (`?from=items`).
+  const searchParams = useSearchParams()
+  const from = searchParams?.get('from') ?? null
 
   const [row, setRow] = React.useState<BillingItemRow | null>(null)
   const [loading, setLoading] = React.useState(true)
@@ -244,6 +288,10 @@ export default function BillingItemDetailPage(props: { params?: { id?: string }
         payload.uomCode = assembled.uomCode ?? null
         payload.subscriptionId = assembled.subscriptionId ?? null
         payload.subscriptionItemId = assembled.subscriptionItemId ?? null
+        if (assembled.chargeTiming !== undefined) payload.chargeTiming = assembled.chargeTiming
+        if (assembled.prorate !== undefined) payload.prorate = assembled.prorate
+        if (assembled.taxRate !== undefined) payload.taxRate = assembled.taxRate
+        if (assembled.priceBasis !== undefined) payload.priceBasis = assembled.priceBasis
 
         await apiCallOrThrow('/api/billing/items', {
           method: 'PUT',
@@ -283,13 +331,13 @@ export default function BillingItemDetailPage(props: { params?: { id?: string }
         body: JSON.stringify({ id: row.id }),
       })
       flash(t('billing.items.detail.delete.success', 'Item deleted'), 'success')
-      router.push('/backend/billing/items')
+      router.push(resolveItemReturnTarget({ from, billAccountId: row.bill_account_id }))
     } catch (err) {
       const { message } = normalizeCrudServerError(err)
       flash(message || t('billing.items.detail.delete.error', 'Delete failed'), 'error')
       setDeleting(false)
     }
-  }, [confirm, router, row, t])
+  }, [confirm, from, router, row, t])
 
   if (error) {
     return (
@@ -316,7 +364,7 @@ export default function BillingItemDetailPage(props: { params?: { id?: string }
     <Page>
       <FormHeader
         mode="detail"
-        backHref="/backend/billing/items"
+        backHref={resolveItemReturnTarget({ from, billAccountId: row.bill_account_id })}
         entityTypeLabel={t('billing.items.detail.title', 'Billing Item')}
         title={row.description}
         statusBadge={
@@ -328,6 +376,12 @@ export default function BillingItemDetailPage(props: { params?: { id?: string }
         }
         actionsContent={
           <>
+            {!editing && row.type === 'recurring' && row.is_active ? (
+              <Button type="button" variant="outline" onClick={() => setChangePriceOpen(true)}>
+                <Repeat size={16} />
+                {t('billing.items.change_price.action', 'Change price')}
+              </Button>
+            ) : null}
             {!editing ? (
               <Button type="button" onClick={() => setEditing(true)}>
                 <Pencil size={16} />
@@ -352,6 +406,8 @@ export default function BillingItemDetailPage(props: { params?: { id?: string }
           <ItemForm
             mode="edit"
             initial={toFormValues(row)}
+            accountCurrency={row.bill_account_currency ?? undefined}
+            accountBillingMode={row.bill_account_mode ?? undefined}
             submitting={saving}
             onSubmit={handleSubmit}
             onCancel={() => setEditing(false)}
@@ -359,6 +415,19 @@ export default function BillingItemDetailPage(props: { params?: { id?: string }
         ) : (
           <ItemView row={row} />
         )}
+        {row.type === 'recurring' ? (
+          <ChangeItemPriceDialog
+            open={changePriceOpen}
+            onOpenChange={setChangePriceOpen}
+            itemId={row.id}
+            currentPrice={typeof row.rate_json?.unit_price === 'number' ? row.rate_json.unit_price : null}
+            currencyCode={row.bill_account_currency}
+            priceBasis={row.price_basis === 'gross' ? 'gross' : 'net'}
+            billStartDate={row.bill_start_date}
+            billEndDate={row.bill_end_date}
+            onChanged={(newItemId) => router.push(`/backend/billing/items/${encodeURIComponent(newItemId)}`)}
+          />
+        ) : null}
         {ConfirmDialogElement}
       </PageBody>
     </Page>

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

@@ -11,6 +11,7 @@ import {
 } from '@open-mercato/ui/backend/utils/apiCall'
 import { normalizeCrudServerError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { ItemForm, type AccountOption, type AssembledItemPayload } from '../../../../components/ItemForm'
+import { ITEMS_LIST_HREF, accountHref, itemDetailHref } from '../../../../lib/navigation'
 
 /**
  * `/backend/billing/items/create` — create a Billing Item.
@@ -19,8 +20,10 @@ import { ItemForm, type AccountOption, type AssembledItemPayload } from '../../.
  * Supports `?billAccountId=<id>` deep-link so the parent account
  * page (when we add an "Add item" CTA there) can pre-select.
  *
- * POSTs `/api/billing/items`. On success, navigates to the item's
- * detail page so the operator can edit further if needed.
+ * POSTs `/api/billing/items`. Navigation (Spec E, D23): opened from an
+ * account (`?billAccountId=`) → save and cancel both return to that
+ * account; opened standalone → save goes to the new item, cancel to the
+ * Items list.
  */
 export default function CreateBillingItemPage() {
   const t = useT()
@@ -62,10 +65,12 @@ export default function CreateBillingItemPage() {
         )
         const id = call.result?.id
         flash(t('billing.items.create.success', 'Billing item created'), 'success')
-        if (id) {
-          router.push(`/backend/billing/items/${id}`)
+        if (preselectedAccountId) {
+          router.push(accountHref(preselectedAccountId, 'items'))
+        } else if (id) {
+          router.push(itemDetailHref(id, { fromItemsList: true }))
         } else {
-          router.push('/backend/billing/items')
+          router.push(ITEMS_LIST_HREF)
         }
       } catch (err) {
         const { message } = normalizeCrudServerError(err)
@@ -77,12 +82,12 @@ export default function CreateBillingItemPage() {
         setSubmitting(false)
       }
     },
-    [router, t],
+    [preselectedAccountId, router, t],
   )
 
   const handleCancel = React.useCallback(() => {
-    router.push('/backend/billing/items')
-  }, [router])
+    router.push(preselectedAccountId ? accountHref(preselectedAccountId, 'items') : ITEMS_LIST_HREF)
+  }, [preselectedAccountId, router])
 
   return (
     <Page>

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

@@ -7,10 +7,11 @@ 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 { Button } from '@open-mercato/ui/primitives/button'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { itemDetailHref } from '../../../lib/navigation'
 
 /**
  * Billing Items admin list.
@@ -34,6 +35,7 @@ type BillingItemRow = {
   uom_code: string | null
   subscription_id: string | null
   source_ref: string | null
+  charge_timing: 'in_advance' | 'in_arrears'
   is_active: boolean
   created_at: string
 }
@@ -186,6 +188,20 @@ export default function BillingItemsListPage() {
           <Tag variant={typeVariant(row.original.type)}>{row.original.type}</Tag>
         ),
       },
+      {
+        accessorKey: 'charge_timing',
+        header: t('billing.items.columns.timing', 'Timing'),
+        cell: ({ row }) =>
+          row.original.type === 'recurring' ? (
+            <span className="text-sm">
+              {row.original.charge_timing === 'in_arrears'
+                ? t('billing.items.charge_timing.in_arrears', 'In arrears')
+                : t('billing.items.charge_timing.in_advance', 'In advance')}
+            </span>
+          ) : (
+            <span className="text-muted-foreground">—</span>
+          ),
+      },
       {
         accessorKey: 'bill_account_id',
         header: t('billing.items.columns.account', 'Account'),
@@ -250,7 +266,7 @@ export default function BillingItemsListPage() {
           perspective={{ tableId: 'billing-items' }}
           columns={columns}
           data={rows}
-          onRowClick={(row) => router.push(`/backend/billing/items/${row.id}`)}
+          onRowClick={(row) => router.push(itemDetailHref(row.id, { fromItemsList: true }))}
           isLoading={loading}
           pagination={{
             page,

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

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