@dainamite/billing 0.20.0 → 0.21.0

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

@@ -0,0 +1,122 @@
+"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 { formatDate } from './accountRow'
+
+// Minimal usage shape for the embedded "Usage" table. Mirrors the
+// snake_case `fields` projection in `api/usage/route.ts`. Usage is
+// append-only — `rated_in_bill_run_id` is null until a Bill Run rates it.
+type AccountUsageRow = {
+  id: string
+  uom_code: string
+  quantity: string
+  period_start: string
+  period_end: string
+  line_description: string | null
+  rated_in_bill_run_id: string | null
+}
+
+/** The account's usage records (workspace Usage tab). */
+export function AccountUsageTab({ accountId }: { accountId: string }) {
+  const t = useT()
+  const [rows, setRows] = React.useState<AccountUsageRow[]>([])
+  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 pageSize = 25
+
+  const load = React.useCallback(async () => {
+    setLoading(true)
+    try {
+      const result = await readApiResultOrThrow<{
+        items: AccountUsageRow[]
+        total: number
+        totalPages: number
+      }>(
+        `/api/billing/usage?billAccountId=${accountId}&page=${page}` +
+          `&pageSize=${pageSize}&sortField=periodStart&sortDir=desc`,
+      )
+      setRows(result.items ?? [])
+      setTotal(result.total ?? 0)
+      setTotalPages(result.totalPages ?? 1)
+    } finally {
+      setLoading(false)
+    }
+  }, [accountId, page])
+
+  React.useEffect(() => {
+    void load()
+  }, [load])
+
+  const columns = React.useMemo<ColumnDef<AccountUsageRow>[]>(
+    () => [
+      {
+        accessorKey: 'uom_code',
+        header: t('billing.usage.columns.uom', 'Unit'),
+        cell: ({ row }) => (
+          <span className="font-mono text-xs">{row.original.uom_code}</span>
+        ),
+      },
+      {
+        accessorKey: 'quantity',
+        header: t('billing.usage.columns.quantity', 'Quantity'),
+        cell: ({ row }) => (
+          <span className="font-mono tabular-nums">{row.original.quantity}</span>
+        ),
+      },
+      {
+        accessorKey: 'period_start',
+        header: t('billing.usage.columns.period', 'Period'),
+        cell: ({ row }) =>
+          `${formatDate(row.original.period_start)} – ${formatDate(row.original.period_end)}`,
+      },
+      {
+        accessorKey: 'line_description',
+        header: t('billing.usage.columns.description', 'Description'),
+        cell: ({ row }) => row.original.line_description || '—',
+      },
+      {
+        accessorKey: 'rated_in_bill_run_id',
+        header: t('billing.usage.columns.rated', 'Rated'),
+        cell: ({ row }) =>
+          row.original.rated_in_bill_run_id ? (
+            // Rated records carry the Bill Run that priced them — link to it.
+            // Unrated records have no destination, so they stay non-interactive
+            // (no misleading row-level click affordance).
+            <Link
+              href={`/backend/billing/runs/${row.original.rated_in_bill_run_id}`}
+              className="rounded-sm hover:underline"
+            >
+              <Tag variant="success">{t('billing.usage.rated.yes', 'Rated')}</Tag>
+            </Link>
+          ) : (
+            <Tag variant="default">{t('billing.usage.rated.no', 'Unrated')}</Tag>
+          ),
+      },
+    ],
+    [t],
+  )
+
+  return (
+    <div className="mt-6">
+      <DataTable
+        title={t('billing.accounts.detail.usage.title', 'Usage')}
+        columns={columns}
+        data={rows}
+        isLoading={loading}
+        pagination={{ page, pageSize, total, totalPages, onPageChange: setPage }}
+        emptyState={
+          <div className="rounded-lg border bg-card p-6 text-center text-sm text-muted-foreground">
+            {t('billing.accounts.detail.usage.empty', 'No usage records for this account yet.')}
+          </div>
+        }
+      />
+    </div>
+  )
+}

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

@@ -0,0 +1,101 @@
+"use client"
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { DetailCard, DetailField } from '../DetailFields'
+import { CustomerLabel } from '../CustomerLabel'
+import { fetchCustomerNames } from '../customerNames'
+import { SUPPORTED_INVOICE_LANGUAGES } from '../../lib/invoiceLanguages'
+import { formatDate, type AccountRow } from './accountRow'
+
+/** Read-only account fields (workspace Overview tab). */
+export function AccountView({ row }: { row: AccountRow }) {
+  const t = useT()
+  const customerKind = row.customer_kind ?? 'company'
+  const [customerName, setCustomerName] = React.useState<string | null>(null)
+  React.useEffect(() => {
+    let cancelled = false
+    void fetchCustomerNames([{ customerId: row.customer_id, customerKind }]).then((names) => {
+      if (!cancelled) setCustomerName(names[row.customer_id]?.name ?? null)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [row.customer_id, customerKind])
+  const languageLabel =
+    SUPPORTED_INVOICE_LANGUAGES.find((language) => language.code === row.invoice_language)?.label ??
+    row.invoice_language
+  const addr = row.invoice_address
+  const addressText = addr
+    ? [
+        addr.line1,
+        addr.line2,
+        [addr.postal_code, addr.city].filter(Boolean).join(' '),
+        addr.country,
+      ]
+        .map((part) => (part ?? '').trim())
+        .filter(Boolean)
+        .join(', ')
+    : ''
+  return (
+    <DetailCard>
+      <DetailField label={t('billing.accounts.columns.customer', 'Customer')}>
+        <CustomerLabel
+          customerId={row.customer_id}
+          customerKind={customerKind}
+          name={customerName}
+          linkToCustomer
+        />
+      </DetailField>
+      <DetailField label={t('billing.accounts.columns.currency', 'Currency')}>
+        {row.currency_code}
+      </DetailField>
+      <DetailField label={t('billing.accounts.columns.mode', 'Mode')}>
+        {row.billing_mode === 'prepaid' ? (
+          <Tag variant="brand">{t('billing.mode.prepaid', 'Prepaid')}</Tag>
+        ) : (
+          <Tag variant="neutral">{t('billing.mode.postpaid', 'Postpaid')}</Tag>
+        )}
+      </DetailField>
+      <DetailField label={t('billing.accounts.columns.credit_limit', 'Credit limit')}>
+        <span className="font-mono tabular-nums">{row.credit_limit}</span>
+      </DetailField>
+      <DetailField label={t('billing.accounts.form.payment_terms', 'Payment terms (days)')}>
+        {row.payment_terms_days != null
+          ? String(row.payment_terms_days)
+          : t('billing.accounts.form.payment_terms.default', 'Organization default')}
+      </DetailField>
+      <DetailField label={t('billing.accounts.form.auto_send', 'Email invoices automatically')}>
+        {row.auto_send_invoice ? t('billing.common.yes', 'Yes') : t('billing.common.no', 'No')}
+      </DetailField>
+      <DetailField label={t('billing.common.id', 'ID')}>
+        <span className="font-mono text-xs">{row.id}</span>
+      </DetailField>
+      <DetailField label={t('billing.accounts.columns.cycle', 'Cycle')}>
+        {row.bill_cycle}
+        <span className="text-muted-foreground"> · {row.bill_cycle_anchor}</span>
+      </DetailField>
+      <DetailField label={t('billing.accounts.columns.next_bill', 'Next bill')}>
+        {formatDate(row.next_bill_date)}
+      </DetailField>
+      <DetailField label={t('billing.accounts.columns.last_bill', 'Last bill')}>
+        {formatDate(row.last_bill_date)}
+      </DetailField>
+      <DetailField label={t('billing.accounts.form.invoice_email', 'Invoice email')}>
+        {row.invoice_email}
+      </DetailField>
+      <DetailField label={t('billing.accounts.form.invoice_language', 'Invoice language')}>
+        {languageLabel}
+      </DetailField>
+      <DetailField label={t('billing.accounts.form.tax_id', 'Tax ID')}>
+        {row.tax_id || '—'}
+      </DetailField>
+      <DetailField
+        label={t('billing.accounts.form.address.title', 'Invoice address')}
+        fullWidth
+      >
+        {addressText || '—'}
+      </DetailField>
+    </DetailCard>
+  )
+}

package/src/modules/billing/components/account/accountRow.ts

@@ -0,0 +1,70 @@
+import type { AccountFormValues } from '../AccountForm'
+
+/**
+ * Billing Account row as returned by `GET /api/billing/accounts` (snake_case
+ * `fields`), shared by the account workspace page and its tabs.
+ */
+export type AccountRow = {
+  id: string
+  customer_id: string
+  customer_kind: 'company' | 'person'
+  name: string
+  currency_code: string
+  bill_cycle: 'weekly' | 'monthly' | 'quarterly' | 'annually'
+  bill_cycle_anchor: string
+  invoice_email: string
+  invoice_language: string
+  tax_id: string | null
+  invoice_address: {
+    line1?: string
+    line2?: string
+    city?: string
+    postal_code?: string
+    country?: string
+  } | null
+  next_bill_date: string
+  last_bill_date: string | null
+  billing_mode: 'postpaid' | 'prepaid'
+  credit_limit: string
+  payment_terms_days: number | null
+  auto_send_invoice: boolean
+  is_active: boolean
+  created_at: string
+  updated_at: string
+}
+
+export 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 toFormValues(row: AccountRow): AccountFormValues {
+  return {
+    customerId: row.customer_id,
+    customerKind: row.customer_kind ?? 'company',
+    name: row.name,
+    currencyCode: row.currency_code,
+    billCycle: row.bill_cycle,
+    billCycleAnchor: row.bill_cycle_anchor,
+    invoiceEmail: row.invoice_email,
+    invoiceLanguage: row.invoice_language,
+    taxId: row.tax_id ?? '',
+    invoiceAddress: {
+      line1: row.invoice_address?.line1 ?? '',
+      line2: row.invoice_address?.line2 ?? '',
+      city: row.invoice_address?.city ?? '',
+      postal_code: row.invoice_address?.postal_code ?? '',
+      country: row.invoice_address?.country ?? '',
+    },
+    nextBillDate: row.next_bill_date?.slice(0, 10) ?? '',
+    isActive: row.is_active,
+    billingMode: row.billing_mode,
+    creditLimit: row.credit_limit ?? '0',
+    paymentTermsDays: row.payment_terms_days != null ? String(row.payment_terms_days) : '',
+    autoSendInvoice: row.auto_send_invoice ?? false,
+    // The threshold lives on the balance row, not the account row — blank
+    // means "leave unchanged" on save.
+    lowBalanceThreshold: '',
+  }
+}

package/src/modules/billing/components/customerNames.ts

@@ -0,0 +1,62 @@
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import type { CustomerKind } from '../data/validators'
+import {
+  customerEndpoint,
+  extractItems,
+  planCustomerLookups,
+  toCustomerSummary,
+  type CustomerSummary,
+} from '../lib/customerLookup'
+
+/**
+ * Batch-resolve customer ids → display names for billing list / detail
+ * views. One request per kind per ≤100 ids (CRUD factory `ids` filter) —
+ * never a per-row fetch.
+ *
+ * Soft dependency on the customers module: a failed or missing lookup just
+ * leaves the id unresolved, and callers fall back to showing the raw id.
+ */
+export async function fetchCustomerNames(
+  rows: Array<{ customerId: string | null | undefined; customerKind: CustomerKind | null | undefined }>,
+): Promise<Record<string, CustomerSummary>> {
+  const plan = planCustomerLookups(rows)
+  const results = await Promise.all(
+    plan.map(async ({ kind, ids }) => {
+      const params = new URLSearchParams({ ids: ids.join(','), page: '1', pageSize: String(ids.length) })
+      return safeList(`${customerEndpoint(kind)}?${params.toString()}`)
+    }),
+  )
+  const map: Record<string, CustomerSummary> = {}
+  for (const rowsOfKind of results) {
+    for (const raw of rowsOfKind) {
+      const summary = toCustomerSummary(raw)
+      if (summary) map[summary.id] = summary
+    }
+  }
+  return map
+}
+
+/**
+ * Loads the customer's addresses and returns the raw rows (the caller maps
+ * them with `mapPrimaryAddress`). Empty on any failure — prefill is a
+ * convenience, never a blocker.
+ */
+export async function fetchCustomerAddressRows(customerId: string): Promise<Array<Record<string, unknown>>> {
+  const params = new URLSearchParams({ entityId: customerId, page: '1', pageSize: '20' })
+  return safeList(`/api/customers/addresses?${params.toString()}`)
+}
+
+/**
+ * GET a customers list endpoint; any failure (non-2xx, network error, module
+ * not installed) yields an empty list. These lookups are cosmetic — the
+ * caller falls back to the raw id / no prefill — so they must never reject.
+ */
+async function safeList(url: string): Promise<Array<Record<string, unknown>>> {
+  try {
+    const call = await apiCall<unknown>(url)
+    return call.ok ? extractItems(call.result) : []
+  } catch (err) {
+    console.warn('[billing] customer lookup failed', url, err)
+    return []
+  }
+}