Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

9.2 KB
Raw Blame
import type { Invoice, InvoiceCustomFieldDef, InvoiceState, InvoiceTemplate } from '@/types'

/**
 * Pure helpers for the invoicing ledger.
 *
 * Everything here is a function of data the server already sent. In
 * particular, none of it recomputes `state`: the server derives it from
 * allocations and the due date, and a second implementation on this side
 * is exactly how the two would come to disagree. What lives here is
 * presentation — how a state looks, what may be done to it, and what the
 * document says its own labels are.
 */

/** How a derived state paints. Keyed by state so a new one is a compile
 *  error here rather than an unstyled badge in production. */
export const STATE_TONE: Record<InvoiceState, string> = {
  draft: 'bg-muted text-muted-foreground border-border',
  open: 'bg-blue-500/10 text-blue-600 border-blue-500/20 dark:text-blue-400',
  partial: 'bg-amber-500/10 text-amber-600 border-amber-500/20 dark:text-amber-400',
  paid: 'bg-emerald-500/10 text-emerald-600 border-emerald-500/20 dark:text-emerald-400',
  overdue: 'bg-red-500/10 text-red-600 border-red-500/20 dark:text-red-400',
  void: 'bg-muted text-muted-foreground border-border line-through',
  uncollectible: 'bg-muted text-muted-foreground border-border',
}

/** The states that represent money still expected. Used for the "open"
 *  filter and for anything that counts receivables. `uncollectible` is
 *  deliberately absent — it is a decision to stop expecting. */
export const OUTSTANDING_STATES: InvoiceState[] = ['open', 'partial', 'overdue']

export function isOutstanding(invoice: Invoice): boolean {
  return OUTSTANDING_STATES.includes(invoice.state)
}

/** Which actions the UI should offer. Mirrors the server's rules so the
 *  user is never shown a button that will come back 400 — the server
 *  still enforces every one of these, this only avoids the dead end. */
export function availableActions(invoice: Invoice): {
  canEdit: boolean
  canDelete: boolean
  canIssue: boolean
  canVoid: boolean
  canWriteOff: boolean
  canReopen: boolean
  canAllocate: boolean
} {
  const isDraft = invoice.status === 'draft'
  const isOpen = invoice.status === 'open'
  const hasMoney = invoice.allocations.length > 0
  const settled = Number(invoice.balance) <= 0
  return {
    // Financial fields are frozen once issued; notes stay editable, which
    // is why the detail view keeps a notes field either way.
    canEdit: isDraft,
    // An issued invoice is never deleted. Void keeps the paper trail.
    canDelete: isDraft,
    canIssue: isDraft,
    // Voiding with money attached would strand the allocation.
    canVoid: isOpen && !hasMoney,
    canWriteOff: isOpen,
    canReopen: invoice.status === 'uncollectible',
    canAllocate: isOpen && !settled,
  }
}

/** The number as a person reads it: the prefix the document carried plus
 *  the sequence. Drafts have no number at all, and saying so beats
 *  printing a placeholder that looks like one.
 *
 *  The snapshot is authoritative whenever it exists — including when it
 *  recorded *no* prefix, which is a real answer and not a missing one.
 *  An invoice issued as "2" must keep reading as "2" after someone sets
 *  a prefix, or the app renames a document the client already has.
 *  Live settings are consulted only when there is no snapshot at all.
 *
 *  None of that applies to a document we did not write. An import arrives
 *  already named, and that name is reproduced verbatim from
 *  `external_number` — ours would rename a supplier's reference. */
export function displayNumber(invoice: Invoice, prefix?: string | null): string | null {
  if (invoice.origin === 'imported') return invoice.external_number || null
  if (invoice.number == null) return null
  const resolved = invoice.snapshot
    ? ((invoice.snapshot.number_prefix as string | null) ?? '')
    : (prefix ?? '')
  return `${resolved}${invoice.number}`
}

/** Labels come from the issued document when there is one, and from live
 *  settings while it is still a draft. */
export function resolveTemplate(
  invoice: Invoice | null,
  settingsTemplate: InvoiceTemplate | null | undefined,
): InvoiceTemplate {
  const frozen = invoice?.snapshot?.template as InvoiceTemplate | undefined
  return frozen ?? settingsTemplate ?? {}
}

export function customFieldDefs(template: InvoiceTemplate | null | undefined): InvoiceCustomFieldDef[] {
  const defs = template?.custom_fields
  return Array.isArray(defs) ? defs.filter((d) => d && typeof d.key === 'string') : []
}

/** Total of the lines, computed client-side purely so the draft form can
 *  show a running total while typing. The server recomputes on save and
 *  its answer is the one that is stored. */
export function linesTotal(lines: { quantity: string; unit_price: string }[]): number {
  return lines.reduce((sum, line) => {
    const quantity = Number(line.quantity)
    const price = Number(line.unit_price)
    if (!Number.isFinite(quantity) || !Number.isFinite(price)) return sum
    return sum + quantity * price
  }, 0)
}

/** Days until due, negative once past. Used for the "vence em 3 dias"
 *  hint; `days_overdue` from the server is the authority once it is
 *  actually late. */
export function daysUntilDue(invoice: Invoice, today = new Date()): number {
  const due = new Date(`${invoice.due_date}T00:00:00`)
  const reference = new Date(today.getFullYear(), today.getMonth(), today.getDate())
  return Math.round((due.getTime() - reference.getTime()) / 86_400_000)
}

/** Map a server rule violation onto a translation key. The server sends
 *  a stable `code`; matching on the English message would break the
 *  moment either side is reworded. */
export function invoiceErrorKey(error: unknown): string | null {
  const detail = (error as { response?: { data?: { detail?: { code?: string } } } })?.response?.data
    ?.detail
  const code = detail && typeof detail === 'object' ? detail.code : undefined
  return code ? `invoices.errors.${code}` : null
}

/** A person, not a strategy. Mirrors `MANUAL_METHOD` on the server. */
export const MANUAL_METHOD = 'manual'

/**
 * How to describe the origin of an allocation.
 *
 * `method` is either `manual` or the **id of the matching strategy** that
 * produced the link — ids that come from the reconciliation policy, a
 * document that will eventually be user-editable. So this deliberately
 * does not switch on a closed list: it separates "a person did this" from
 * "a rule did this", and hands the id back so the caller can show *which*
 * rule once the policy is readable from the client.
 *
 * Until then an unknown id still reads as an explanation rather than as a
 * mystery, which is the whole reason the column stores it.
 */
export function allocationOrigin(method: string): {
  automatic: boolean
  strategyId: string | null
} {
  const automatic = method !== MANUAL_METHOD
  return { automatic, strategyId: automatic ? method : null }
}


/** A file size as a person reads it. Bytes below a kilobyte, then whole
 *  kilobytes, then one decimal of a megabyte — the precision stops where
 *  it stops being information. */
export function formatFileSize(bytes: number): string {
  if (!Number.isFinite(bytes) || bytes < 0) return '0 B'
  if (bytes < 1024) return `${Math.round(bytes)} B`
  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
}

/** How a filed document can be shown in the page.
 *
 *  `pdf` and `image` render in place; everything else has to be opened,
 *  because guessing at a preview for a format the browser cannot draw
 *  produces an empty frame rather than an answer. */
export function previewKind(contentType: string | null | undefined): 'pdf' | 'image' | 'none' {
  const type = (contentType ?? '').toLowerCase()
  if (type === 'application/pdf') return 'pdf'
  if (type.startsWith('image/')) return 'image'
  return 'none'
}

/** Whether the Document tab has a real page to show.
 *
 *  Three outcomes, and the middle one is the point: an imported invoice
 *  with nothing filed must show neither a file (there is none) nor our
 *  own render (we did not write it, and drawing one invents a document
 *  somebody else issued). */
export function documentSource(
  origin: string,
  sourceFile: unknown | null | undefined,
): 'filed' | 'missing' | 'rendered' {
  if (sourceFile) return 'filed'
  return origin === 'imported' ? 'missing' : 'rendered'
}

/** The source stamped on the page we render and file at the moment an
 *  invoice is issued. */
export const ISSUED_BY_US = 'issued'

/** Where a filed document came from, as a person reads it.
 *
 *  A source id is a machine name (`gateway`, `nfe`, `email`), so it is
 *  shown as it is rather than translated — renaming somebody's system in
 *  our own words helps nobody trying to work out which integration
 *  delivered which file. Two sources are our word rather than theirs: a
 *  file with no source was uploaded here by hand, and one stamped
 *  `issued` is the page we drew ourselves, which read as the literal
 *  "De issued" until it was given a name.
 */
export function documentProvenance(
  source: string | null | undefined,
): { kind: 'uploaded' } | { kind: 'ours' } | { kind: 'system'; name: string } {
  const name = (source ?? '').trim()
  if (name === ISSUED_BY_US) return { kind: 'ours' }
  return name ? { kind: 'system', name } : { kind: 'uploaded' }
}