@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/lib/billRunLabel.ts

@@ -1,7 +1,7 @@
 /**
  * Human-readable label for a Bill Run.
  *
- * The BillRun entity has no `name` column — the engine keys runs by id.
+ * The BillingRun entity has no `name` column — the engine keys runs by id.
  * The admin UI derives a stable, scannable label from the run's as-of
  * date so operators see `BILL_RUN_2026-05-20` instead of a raw UUID.
  */

package/src/modules/billing/lib/billingSettings.ts

@@ -0,0 +1,145 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { BillingSettings } from '../data/entities'
+import { DEFAULT_NUMBER_MASKS, maskFor, type DocumentSeries } from './numbering'
+
+/**
+ * Per-organization billing settings (Spec 0, E-D2 / E-D5).
+ *
+ * Replaces the tenant-wide core `configs` rows billing used to seed. One row
+ * per (tenant, organization), created lazily with today's defaults on first
+ * read so every caller can rely on it existing. Spec B adds the seller /
+ * payment / document fields (the INSERT below relies on their DB defaults:
+ * 14 days terms, 23 % VAT, seller fields empty).
+ */
+
+export type SettingsScope = { tenantId: string; organizationId: string }
+
+export const BILLING_SETTINGS_DEFAULTS = {
+  lowBalanceThresholdDefault: '0',
+  nearLimitBufferDefault: '0',
+  statementEnabled: true,
+  topupTaxRate: '0',
+  topupProvider: 'stripe',
+  numberMasks: { ...DEFAULT_NUMBER_MASKS } as Record<string, string>,
+  defaultPaymentTermsDays: 14,
+  defaultTaxRate: '23',
+  prepaidTaxPoint: 'topup',
+} as const
+
+/**
+ * VAT rate printed on top-up receipts (Spec F, P-D11): `topup_tax_rate` when
+ * the prepaid tax point is `topup`, 0 in `consumption` mode (VAT is charged
+ * on each debit instead — never twice).
+ */
+export function receiptTaxRate(settings: Pick<BillingSettings, 'topupTaxRate' | 'prepaidTaxPoint'>): number {
+  if (settings.prepaidTaxPoint === 'consumption') return 0
+  const n = Number.parseFloat(String(settings.topupTaxRate ?? '0'))
+  return Number.isFinite(n) && n > 0 ? n : 0
+}
+
+/** numeric(7,4) column value for a VAT percentage. */
+export function taxRateColumn(ratePercent: number): string {
+  return (Math.round(ratePercent * 10000) / 10000).toString()
+}
+
+/** Seller fields a posted (printable) invoice requires — Spec B, P-D4. */
+export const REQUIRED_SELLER_FIELDS = ['legalName', 'sellerAddress', 'taxId', 'iban'] as const
+export type RequiredSellerField = (typeof REQUIRED_SELLER_FIELDS)[number]
+
+export function missingSellerFields(
+  settings: Pick<BillingSettings, RequiredSellerField>,
+): RequiredSellerField[] {
+  return REQUIRED_SELLER_FIELDS.filter((field) => {
+    const value = settings[field]
+    if (value === null || value === undefined) return true
+    if (typeof value === 'string') return value.trim() === ''
+    return Object.keys(value).length === 0
+  })
+}
+
+/**
+ * Seller block frozen onto an invoice at post, so later settings edits never
+ * change an issued document.
+ */
+export function buildSellerSnapshot(settings: BillingSettings): Record<string, unknown> {
+  return {
+    organization_id: settings.organizationId,
+    legal_name: settings.legalName ?? null,
+    address: settings.sellerAddress ?? null,
+    tax_id: settings.taxId ?? null,
+    bank_name: settings.bankName ?? null,
+    iban: settings.iban ?? null,
+    bic: settings.bic ?? null,
+    invoice_footer: settings.invoiceFooter ?? null,
+    logo_attachment_id: settings.logoAttachmentId ?? null,
+  }
+}
+
+export async function getBillingSettings(em: EntityManager, scope: SettingsScope): Promise<BillingSettings> {
+  const where = { tenantId: scope.tenantId, organizationId: scope.organizationId, deletedAt: null }
+  const existing = await em.findOne(BillingSettings, where as never)
+  if (existing) return existing
+  // Race-safe create: a concurrent first read may insert the same row; the
+  // partial unique index makes ours a no-op and we re-read the winner.
+  const now = new Date()
+  await em.execute(
+    `INSERT INTO billing_settings
+       (tenant_id, organization_id, low_balance_threshold_default, near_limit_buffer_default,
+        statement_enabled, topup_tax_rate, topup_provider, number_masks, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?::jsonb, ?, ?)
+     ON CONFLICT (tenant_id, organization_id) WHERE deleted_at IS NULL DO NOTHING`,
+    [
+      scope.tenantId,
+      scope.organizationId,
+      BILLING_SETTINGS_DEFAULTS.lowBalanceThresholdDefault,
+      BILLING_SETTINGS_DEFAULTS.nearLimitBufferDefault,
+      BILLING_SETTINGS_DEFAULTS.statementEnabled,
+      BILLING_SETTINGS_DEFAULTS.topupTaxRate,
+      BILLING_SETTINGS_DEFAULTS.topupProvider,
+      JSON.stringify(BILLING_SETTINGS_DEFAULTS.numberMasks),
+      now,
+      now,
+    ],
+  )
+  const created = await em.findOne(BillingSettings, where as never)
+  if (!created) throw new Error('Billing settings could not be initialised')
+  return created
+}
+
+/** Mask for a series, falling back to the default when unset or invalid. */
+export function numberMaskFor(settings: Pick<BillingSettings, 'numberMasks'>, series: DocumentSeries): string {
+  return maskFor(settings.numberMasks ?? null, series)
+}
+
+function numberOr(value: string | number | null | undefined, fallback: number): number {
+  const n = typeof value === 'number' ? value : Number.parseFloat(value ?? '')
+  return Number.isFinite(n) ? n : fallback
+}
+
+/** Plain view of the settings — what the API returns and the UI edits. */
+export function serializeBillingSettings(settings: BillingSettings) {
+  return {
+    id: settings.id,
+    lowBalanceThresholdDefault: numberOr(settings.lowBalanceThresholdDefault, 0),
+    nearLimitBufferDefault: numberOr(settings.nearLimitBufferDefault, 0),
+    statementEnabled: settings.statementEnabled,
+    topupTaxRate: numberOr(settings.topupTaxRate, 0),
+    prepaidTaxPoint: settings.prepaidTaxPoint === 'consumption' ? ('consumption' as const) : ('topup' as const),
+    topupProvider: settings.topupProvider,
+    numberMasks: {
+      invoice: numberMaskFor(settings, 'invoice'),
+      credit_memo: numberMaskFor(settings, 'credit_memo'),
+      receipt: numberMaskFor(settings, 'receipt'),
+    },
+    legalName: settings.legalName ?? '',
+    sellerAddress: settings.sellerAddress ?? null,
+    taxId: settings.taxId ?? '',
+    bankName: settings.bankName ?? '',
+    iban: settings.iban ?? '',
+    bic: settings.bic ?? '',
+    invoiceFooter: settings.invoiceFooter ?? '',
+    logoAttachmentId: settings.logoAttachmentId ?? null,
+    defaultPaymentTermsDays: settings.defaultPaymentTermsDays ?? BILLING_SETTINGS_DEFAULTS.defaultPaymentTermsDays,
+    defaultTaxRate: numberOr(settings.defaultTaxRate, 23),
+  }
+}

package/src/modules/billing/lib/commandRoute.ts

@@ -0,0 +1,112 @@
+import { NextResponse } from 'next/server'
+import type { ZodType } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import {
+  organizationScopeRequiredResponse,
+  resolveActiveOrganizationId,
+} from '@open-mercato/shared/lib/auth/organizationScope'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { bridgeLegacyGuard, runMutationGuards } from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+
+/**
+ * Shared handler for billing's custom POST action routes (Spec C payments,
+ * Spec D memos): authenticates, resolves the organization, validates the
+ * body, runs the shared mutation guards (record locks etc.) as `update` on
+ * the target resource, executes the command and maps `CrudHttpError`s.
+ *
+ * `requireFeatures` stays on each route's exported `metadata` (enforced by
+ * the API dispatcher).
+ */
+
+export type CommandRouteOptions<TBody> = {
+  commandId: string
+  /** Body schema WITHOUT tenant / organization (they come from auth). */
+  bodySchema: ZodType<TBody>
+  resourceKind: string
+  resourceId: (body: TBody) => string | null
+  /** Mutation-guard operation (default `update`, the usual one for action routes). */
+  operation?: 'create' | 'update' | 'delete'
+  /** Optional input mapping (default: body + scope). */
+  toInput?: (body: TBody, scope: { tenantId: string; organizationId: string }) => Record<string, unknown>
+  logLabel: string
+}
+
+function userFeatures(auth: unknown): string[] {
+  const features = (auth as { features?: unknown })?.features
+  return Array.isArray(features) ? features.filter((value): value is string => typeof value === 'string') : []
+}
+
+export async function readRequestBody(req: Request): Promise<unknown> {
+  try {
+    return await req.json()
+  } catch {
+    return {}
+  }
+}
+
+export async function runCommandRoute<TBody>(
+  req: Request,
+  options: CommandRouteOptions<TBody>,
+  rawBody?: unknown,
+): Promise<Response> {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const organizationId = resolveActiveOrganizationId(auth)
+    if (!organizationId) return organizationScopeRequiredResponse()
+    const parsed = options.bodySchema.safeParse(rawBody === undefined ? await readRequestBody(req) : rawBody)
+    if (!parsed.success) {
+      return NextResponse.json(
+        { error: 'Invalid request', code: 'billing.request.invalid', issues: parsed.error.issues },
+        { status: 400 },
+      )
+    }
+    const scope = { tenantId: auth.tenantId, organizationId }
+    const guardInput = {
+      tenantId: auth.tenantId,
+      organizationId,
+      userId: auth.sub ?? '',
+      resourceKind: options.resourceKind,
+      resourceId: options.resourceId(parsed.data),
+      operation: options.operation ?? ('update' as const),
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    }
+    const legacyGuard = bridgeLegacyGuard(container)
+    const guard = legacyGuard
+      ? await runMutationGuards([legacyGuard], guardInput, { userFeatures: userFeatures(auth) })
+      : { ok: true as const, afterSuccessCallbacks: [] }
+    if (!guard.ok) {
+      return NextResponse.json(guard.errorBody ?? { error: 'Operation blocked by guard' }, { status: guard.errorStatus ?? 422 })
+    }
+    const ctx: CommandRuntimeContext = {
+      container,
+      auth,
+      organizationScope: null,
+      selectedOrganizationId: organizationId,
+      organizationIds: [organizationId],
+      request: req,
+    }
+    const commandBus = container.resolve('commandBus') as CommandBus
+    const input = options.toInput
+      ? options.toInput(parsed.data, scope)
+      : { ...(parsed.data as Record<string, unknown>), ...scope }
+    const response = await commandBus.execute(options.commandId, { input, ctx })
+    for (const callback of guard.afterSuccessCallbacks) {
+      if (!callback.guard.afterSuccess) continue
+      try {
+        await callback.guard.afterSuccess({ ...guardInput, resourceId: guardInput.resourceId ?? '', metadata: callback.metadata ?? null })
+      } catch (err) {
+        console.error(`[${options.logLabel}] guard afterSuccess failed`, err)
+      }
+    }
+    return NextResponse.json((response as { result?: unknown }).result ?? { ok: true })
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    console.error(`[${options.logLabel}]`, err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}

package/src/modules/billing/lib/customerLookup.ts

@@ -0,0 +1,157 @@
+import type { CustomerKind } from '../data/validators'
+
+/**
+ * Pure helpers for linking a Billing Account to a customer record (Spec E).
+ *
+ * Billing never imports the customers module: `customer_id` is a string FK
+ * and every read goes through the customers REST API from the UI (a soft
+ * dependency — if it is unavailable the form degrades to a raw id and no
+ * prefill). These helpers keep the response-shape knowledge in one tested
+ * place so the React components stay thin.
+ */
+
+export type CustomerSummary = {
+  id: string
+  name: string
+  email: string | null
+}
+
+export type PrefillAddress = {
+  line1: string
+  line2: string
+  city: string
+  postal_code: string
+  country: string
+}
+
+export type PrefillTarget = {
+  name: string
+  invoiceEmail: string
+  invoiceAddress: PrefillAddress
+}
+
+type RawRecord = Record<string, unknown>
+
+const CUSTOMER_ENDPOINTS: Record<CustomerKind, string> = {
+  company: '/api/customers/companies',
+  person: '/api/customers/people',
+}
+
+const CUSTOMER_DETAIL_PATHS: Record<CustomerKind, string> = {
+  company: '/backend/customers/companies',
+  person: '/backend/customers/people',
+}
+
+/** Max ids per batched lookup — the CRUD factory caps `pageSize` at 100. */
+export const CUSTOMER_LOOKUP_CHUNK = 100
+
+export function customerEndpoint(kind: CustomerKind): string {
+  return CUSTOMER_ENDPOINTS[kind]
+}
+
+export function customerDetailHref(kind: CustomerKind, customerId: string): string {
+  return `${CUSTOMER_DETAIL_PATHS[kind]}/${encodeURIComponent(customerId)}`
+}
+
+function str(value: unknown): string {
+  if (typeof value === 'string') return value.trim()
+  if (typeof value === 'number') return String(value)
+  return ''
+}
+
+/** Extracts the row array from a list response (`{ items }` or a bare array). */
+export function extractItems(result: unknown): RawRecord[] {
+  const raw = Array.isArray(result)
+    ? result
+    : result && typeof result === 'object' && Array.isArray((result as { items?: unknown }).items)
+      ? (result as { items: unknown[] }).items
+      : []
+  return raw.filter((row): row is RawRecord => !!row && typeof row === 'object')
+}
+
+/** Maps a customers list row (snake_case or camelCase) to a summary. */
+export function toCustomerSummary(row: RawRecord): CustomerSummary | null {
+  const id = str(row.id)
+  if (!id) return null
+  const name = str(row.display_name) || str(row.displayName) || str(row.name) || id
+  const email = str(row.primary_email) || str(row.primaryEmail) || str(row.email)
+  return { id, name, email: email || null }
+}
+
+/**
+ * Picks the customer's primary address (else the first usable one) and maps
+ * it onto the billing `invoice_address` shape. Returns null when no row has
+ * the parts billing requires (line 1, city, postal code, country).
+ */
+export function mapPrimaryAddress(rows: RawRecord[]): PrefillAddress | null {
+  const ordered = [...rows].sort((a, b) => Number(b.is_primary === true) - Number(a.is_primary === true))
+  for (const row of ordered) {
+    const street = str(row.address_line1) || str(row.addressLine1)
+    const building = str(row.building_number) || str(row.buildingNumber)
+    const flat = str(row.flat_number) || str(row.flatNumber)
+    let line1 = street
+    if (line1 && building) line1 = `${line1} ${building}`
+    if (line1 && building && flat) line1 = `${line1}/${flat}`
+    const city = str(row.city)
+    const postalCode = str(row.postal_code) || str(row.postalCode)
+    const country = (str(row.country) || str(row.country_code) || str(row.countryCode)).toUpperCase()
+    if (!line1 || !city || !postalCode || country.length < 2 || country.length > 3) continue
+    return {
+      line1,
+      line2: str(row.address_line2) || str(row.addressLine2),
+      city,
+      postal_code: postalCode,
+      country,
+    }
+  }
+  return null
+}
+
+function isAddressEmpty(address: PrefillAddress): boolean {
+  return !address.line1.trim() && !address.line2.trim() && !address.city.trim() && !address.postal_code.trim()
+}
+
+/**
+ * Fills ONLY empty fields from the customer record (decision E2-D2) — never
+ * overwrites what the operator typed. The address is taken as a whole block
+ * (and only if the form's address is still blank) so we never mix a typed
+ * street with a prefilled city. Country alone does not count as "typed": the
+ * form ships a default country.
+ */
+export function applyCustomerPrefill<T extends PrefillTarget>(
+  current: T,
+  customer: CustomerSummary | null,
+  address: PrefillAddress | null,
+): T {
+  let next = current
+  if (customer) {
+    if (!current.name.trim() && customer.name) next = { ...next, name: customer.name }
+    if (!current.invoiceEmail.trim() && customer.email) next = { ...next, invoiceEmail: customer.email }
+  }
+  if (address && isAddressEmpty(current.invoiceAddress)) {
+    next = { ...next, invoiceAddress: { ...address } }
+  }
+  return next
+}
+
+/** Groups ids by kind and chunks them for batched `?ids=` lookups. */
+export function planCustomerLookups(
+  rows: Array<{ customerId: string | null | undefined; customerKind: CustomerKind | null | undefined }>,
+): Array<{ kind: CustomerKind; ids: string[] }> {
+  const byKind = new Map<CustomerKind, Set<string>>()
+  for (const row of rows) {
+    const id = (row.customerId ?? '').trim()
+    if (!id) continue
+    const kind: CustomerKind = row.customerKind === 'person' ? 'person' : 'company'
+    if (!byKind.has(kind)) byKind.set(kind, new Set())
+    byKind.get(kind)!.add(id)
+  }
+  const plan: Array<{ kind: CustomerKind; ids: string[] }> = []
+  for (const [kind, ids] of byKind) {
+    const all = Array.from(ids)
+    for (let i = 0; i < all.length; i += CUSTOMER_LOOKUP_CHUNK) {
+      plan.push({ kind, ids: all.slice(i, i + CUSTOMER_LOOKUP_CHUNK) })
+    }
+  }
+  return plan
+}

package/src/modules/billing/lib/dateOnly.ts

@@ -0,0 +1,22 @@
+/**
+ * Date-only helpers (Spec F, P-D5).
+ *
+ * MikroORM v7 hydrates `date` columns as `YYYY-MM-DD` strings while the
+ * engine computes with `Date`s; and `pg` serialises a `Date` query
+ * parameter in the server's time zone, which can shift a `date` comparison
+ * by a day. Every date-only value the billing engine compares or sends to a
+ * `date` column goes through these helpers: compare as UTC midnight, query
+ * with the ISO day string.
+ */
+
+/** UTC-midnight `Date` for a `Date`, ISO string or timestamp. */
+export function toUtcMidnight(value: Date | string | number): Date {
+  const date = typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) ? new Date(`${value}T00:00:00Z`) : new Date(value)
+  date.setUTCHours(0, 0, 0, 0)
+  return date
+}
+
+/** `YYYY-MM-DD` (UTC) for a `Date`, ISO string or timestamp. */
+export function toIsoDate(value: Date | string | number): string {
+  return toUtcMidnight(value).toISOString().slice(0, 10)
+}

package/src/modules/billing/lib/documentParties.ts

@@ -0,0 +1,23 @@
+import type { BillingAccount } from '../data/entities'
+
+/**
+ * Parties printed on a billing document. Posting freezes them as snapshots
+ * on the invoice (buyer from the account, seller from `billingSettings`), so
+ * later account / settings edits never change an issued document; drafts
+ * render from the live rows.
+ */
+
+/** Frozen "issued to" block — later account edits never change a posted document. */
+export function buildBuyerSnapshot(account: BillingAccount): Record<string, unknown> {
+  return {
+    bill_account_id: account.id,
+    name: account.name,
+    customer_id: account.customerId,
+    customer_kind: account.customerKind ?? 'company',
+    tax_id: account.taxId ?? null,
+    invoice_email: account.invoiceEmail,
+    invoice_language: account.invoiceLanguage,
+    invoice_address: account.invoiceAddress ?? null,
+  }
+}
+

package/src/modules/billing/lib/documentTypes.ts

@@ -0,0 +1,37 @@
+/**
+ * Billing document type helpers (Spec 0 / Spec D). Pure.
+ *
+ *   invoice     — receivable, `invoice` series
+ *   debit_memo  — receivable (supplementary invoice), `invoice` series (D-D8)
+ *   credit_memo — credit source, `credit_memo` series; amounts stored positive (D-D5)
+ *   receipt     — prepaid top-up receipt, `receipt` series, never corrected (D-D6)
+ */
+
+export type DocumentType = 'invoice' | 'credit_memo' | 'debit_memo' | 'receipt'
+
+export function isReceivable(type: string): boolean {
+  return type === 'invoice' || type === 'debit_memo'
+}
+
+export function isMemo(type: string): boolean {
+  return type === 'credit_memo' || type === 'debit_memo'
+}
+
+/** Numbering series of a document type. */
+export function seriesFor(type: string): 'invoice' | 'credit_memo' | 'receipt' {
+  if (type === 'credit_memo') return 'credit_memo'
+  if (type === 'receipt') return 'receipt'
+  return 'invoice'
+}
+
+/** Sign used for DISPLAY only — credit memos read as negative amounts. */
+export function displaySign(type: string): 1 | -1 {
+  return type === 'credit_memo' ? -1 : 1
+}
+
+/** Originals a memo may correct (D-D3): posted, partially paid, paid (credited → debit only). */
+export function canCorrect(original: { documentType: string; status: string; testRun: boolean }, memoType: string): boolean {
+  if (original.testRun || original.documentType !== 'invoice') return false
+  if (['posted', 'partially_paid', 'paid'].includes(original.status)) return true
+  return original.status === 'credited' && memoType === 'debit_memo'
+}

package/src/modules/billing/lib/dueDate.ts

@@ -0,0 +1,26 @@
+/**
+ * Due-date math for posted invoices (Spec B). Pure, date-only, UTC.
+ *
+ * `due_date = issue_date + payment terms (days)`, where the terms come from
+ * the account (`payment_terms_days`) and fall back to the organization
+ * default (`billing_settings.default_payment_terms_days`).
+ */
+
+export function resolvePaymentTermsDays(
+  accountTermsDays: number | null | undefined,
+  defaultTermsDays: number | null | undefined,
+): number {
+  if (typeof accountTermsDays === 'number' && Number.isInteger(accountTermsDays) && accountTermsDays >= 0) {
+    return accountTermsDays
+  }
+  if (typeof defaultTermsDays === 'number' && Number.isInteger(defaultTermsDays) && defaultTermsDays >= 0) {
+    return defaultTermsDays
+  }
+  return 14
+}
+
+/** Issue date (any time of day) + N calendar days, at UTC midnight. */
+export function computeDueDate(issueDate: Date, termsDays: number): Date {
+  const base = new Date(issueDate)
+  return new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth(), base.getUTCDate() + termsDays))
+}

package/src/modules/billing/lib/iban.ts

@@ -0,0 +1,36 @@
+/**
+ * IBAN / BIC helpers for the seller's payment instructions (Spec B). Pure.
+ *
+ * `normalizeIban` strips spaces and upper-cases; `isValidIban` checks the
+ * structure (country code, check digits, 11–30 alphanumerics after) and the
+ * ISO 13616 mod-97 checksum. Country-specific lengths are not enforced — the
+ * checksum already rejects typos, and a missing country table never blocks a
+ * legitimate account.
+ */
+
+export function normalizeIban(value: string): string {
+  return value.replace(/\s+/g, '').toUpperCase()
+}
+
+export function isValidIban(value: string): boolean {
+  const iban = normalizeIban(value)
+  if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban)) return false
+  const rearranged = iban.slice(4) + iban.slice(0, 4)
+  let remainder = 0
+  for (const char of rearranged) {
+    const digits = /[A-Z]/.test(char) ? String(char.charCodeAt(0) - 55) : char
+    for (const digit of digits) {
+      remainder = (remainder * 10 + Number(digit)) % 97
+    }
+  }
+  return remainder === 1
+}
+
+/** Groups of 4 for display ("PL61 1090 1014 …"). */
+export function formatIban(value: string): string {
+  return normalizeIban(value).replace(/(.{4})/g, '$1 ').trim()
+}
+
+export function isValidBic(value: string): boolean {
+  return /^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$/.test(value.trim().toUpperCase())
+}