@dainamite/billing 0.20.0 → 0.22.0

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

@@ -0,0 +1,171 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { PAYMENT_IMPORT_MAX_ROWS } from '../data/validators'
+
+/**
+ * Bank payment CSV parser (Spec C, demo-grade fixed format). Pure.
+ *
+ *   date,amount,currency,reference,payer_name,payer_account
+ *   2026-11-20,123.00,PLN,"Payment for INV/2026/11/0003",ACME Sp. z o.o.,PL61…
+ *
+ * UTF-8 (BOM tolerated), comma separated, RFC-4180 quoting (`""` escapes,
+ * commas and newlines inside quotes), header required, `.` decimal
+ * separator, amount > 0 (refunds are out of scope), ≤ 5,000 data rows.
+ * Invalid rows are reported with their line number and skipped; they never
+ * abort the file.
+ */
+
+export const PAYMENT_CSV_HEADER = ['date', 'amount', 'currency', 'reference', 'payer_name', 'payer_account'] as const
+
+export type PaymentCsvRow = {
+  line: number
+  receivedAt: string
+  amount: string
+  currency: string
+  reference: string | null
+  payerName: string | null
+  payerAccount: string | null
+}
+
+export type PaymentCsvResult = {
+  rows: PaymentCsvRow[]
+  errors: Array<{ row: number; message: string }>
+  fatal: string | null
+}
+
+const rowSchema = z.object({
+  date: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'date must be YYYY-MM-DD')
+    .refine((value) => !Number.isNaN(new Date(`${value}T00:00:00Z`).getTime()), 'date is not a valid day'),
+  amount: z
+    .string()
+    .regex(/^\d+(\.\d{1,4})?$/, 'amount must be a positive number with "." as decimal separator')
+    .refine((value) => Number.parseFloat(value) > 0, 'amount must be greater than 0'),
+  currency: z.string().regex(/^[A-Za-z]{3}$/, 'currency must be a 3-letter code'),
+  reference: z.string().max(500, 'reference is longer than 500 characters'),
+  payer_name: z.string().max(255),
+  payer_account: z.string().max(64),
+})
+
+/** Splits CSV text into records of fields (RFC 4180). Returns the 1-based start line of each record. */
+export function splitCsv(text: string): Array<{ line: number; fields: string[] }> {
+  const records: Array<{ line: number; fields: string[] }> = []
+  let fields: string[] = []
+  let field = ''
+  let inQuotes = false
+  let line = 1
+  let recordLine = 1
+  const pushRecord = () => {
+    fields.push(field)
+    if (!(fields.length === 1 && fields[0].trim() === '')) records.push({ line: recordLine, fields })
+    fields = []
+    field = ''
+  }
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i]
+    if (inQuotes) {
+      if (char === '"') {
+        if (text[i + 1] === '"') {
+          field += '"'
+          i += 1
+        } else {
+          inQuotes = false
+        }
+      } else {
+        if (char === '\n') line += 1
+        field += char
+      }
+      continue
+    }
+    if (char === '"' && field.trim() === '') {
+      field = ''
+      inQuotes = true
+    } else if (char === ',') {
+      fields.push(field)
+      field = ''
+    } else if (char === '\n' || char === '\r') {
+      if (char === '\r' && text[i + 1] === '\n') i += 1
+      pushRecord()
+      line += 1
+      recordLine = line
+    } else {
+      field += char
+    }
+  }
+  if (field !== '' || fields.length > 0) pushRecord()
+  return records
+}
+
+export function parsePaymentCsv(text: string): PaymentCsvResult {
+  const records = splitCsv(text.replace(/^/, ''))
+  if (records.length === 0) return { rows: [], errors: [], fatal: 'The file is empty' }
+  const header = records[0].fields.map((f) => f.trim().toLowerCase())
+  if (header.join(',') !== PAYMENT_CSV_HEADER.join(',')) {
+    return { rows: [], errors: [], fatal: `The header must be: ${PAYMENT_CSV_HEADER.join(',')}` }
+  }
+  const data = records.slice(1)
+  if (data.length > PAYMENT_IMPORT_MAX_ROWS) {
+    return { rows: [], errors: [], fatal: `The file has more than ${PAYMENT_IMPORT_MAX_ROWS} rows` }
+  }
+  const rows: PaymentCsvRow[] = []
+  const errors: PaymentCsvResult['errors'] = []
+  for (const record of data) {
+    if (record.fields.length !== PAYMENT_CSV_HEADER.length) {
+      errors.push({ row: record.line, message: `expected ${PAYMENT_CSV_HEADER.length} columns, got ${record.fields.length}` })
+      continue
+    }
+    const raw = Object.fromEntries(PAYMENT_CSV_HEADER.map((key, i) => [key, record.fields[i].trim()]))
+    const parsed = rowSchema.safeParse(raw)
+    if (!parsed.success) {
+      errors.push({ row: record.line, message: parsed.error.issues.map((issue) => issue.message).join('; ') })
+      continue
+    }
+    rows.push({
+      line: record.line,
+      receivedAt: parsed.data.date,
+      amount: Number.parseFloat(parsed.data.amount).toFixed(4),
+      currency: parsed.data.currency.toUpperCase(),
+      reference: parsed.data.reference || null,
+      payerName: parsed.data.payer_name || null,
+      payerAccount: parsed.data.payer_account ? parsed.data.payer_account.replace(/\s+/g, '').toUpperCase() : null,
+    })
+  }
+  return { rows, errors, fatal: null }
+}
+
+/**
+ * Duplicate guard (P-D7): the same bank line uploaded again yields the same
+ * key; identical lines inside one file differ by their occurrence index.
+ */
+export function paymentSourceRef(
+  scope: { tenantId: string; organizationId: string },
+  row: Pick<PaymentCsvRow, 'receivedAt' | 'amount' | 'currency' | 'reference' | 'payerAccount'>,
+  occurrence: number,
+): string {
+  const key = [
+    scope.tenantId,
+    scope.organizationId,
+    row.receivedAt,
+    row.amount,
+    row.currency,
+    row.reference ?? '',
+    row.payerAccount ?? '',
+    String(occurrence),
+  ].join('|')
+  return `csv:${createHash('sha256').update(key).digest('hex')}`
+}
+
+/** Source refs for all rows of a file, counting identical lines (occurrence index). */
+export function sourceRefsForRows(
+  scope: { tenantId: string; organizationId: string },
+  rows: PaymentCsvRow[],
+): string[] {
+  const seen = new Map<string, number>()
+  return rows.map((row) => {
+    const identity = [row.receivedAt, row.amount, row.currency, row.reference ?? '', row.payerAccount ?? ''].join('|')
+    const occurrence = (seen.get(identity) ?? 0) + 1
+    seen.set(identity, occurrence)
+    return paymentSourceRef(scope, row, occurrence)
+  })
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Optional payment-gateway integration (Spec 0, E-D1).
+ *
+ * Billing no longer requires the `payment_gateways` module. When it is
+ * installed, online top-ups open a checkout session through its
+ * `paymentGatewayService`; when it isn't, top-ups via the gateway are
+ * unavailable (501) and the UI hides the "Top up" button. Bank-transfer
+ * top-ups are recorded through payments (billing Spec C).
+ *
+ * The structural type below covers only what billing calls, so billing never
+ * deep-imports the gateway module's types.
+ */
+
+export type GatewaySessionRequest = {
+  providerKey: string
+  paymentId: string
+  amount: number
+  currencyCode: string
+  captureMethod: 'automatic' | 'manual'
+  successUrl?: string
+  cancelUrl?: string
+  metadata?: Record<string, unknown>
+  organizationId: string
+  tenantId: string
+}
+
+export type GatewaySessionResult = {
+  transaction: { id: string }
+  session: { redirectUrl?: string | null; clientSecret?: string | null; sessionId?: string | null }
+}
+
+export type TopupPaymentGateway = {
+  createPaymentSession(request: GatewaySessionRequest): Promise<GatewaySessionResult>
+}
+
+type ContainerLike = {
+  hasRegistration?: (name: string) => boolean
+  resolve: (name: string) => unknown
+}
+
+export const PAYMENT_GATEWAY_SERVICE = 'paymentGatewayService'
+
+export function isPaymentGatewayAvailable(container: ContainerLike): boolean {
+  return typeof container.hasRegistration === 'function' && container.hasRegistration(PAYMENT_GATEWAY_SERVICE)
+}
+
+/** The gateway service, or null when the `payment_gateways` module isn't installed. */
+export function resolvePaymentGateway(container: ContainerLike): TopupPaymentGateway | null {
+  if (!isPaymentGatewayAvailable(container)) return null
+  const service = container.resolve(PAYMENT_GATEWAY_SERVICE) as Partial<TopupPaymentGateway> | null
+  return service && typeof service.createPaymentSession === 'function' ? (service as TopupPaymentGateway) : null
+}

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

@@ -0,0 +1,228 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { BillingPayment, BillingPaymentImport } from '../data/entities'
+import { withAccountLock } from './accountLock'
+import {
+  allocate,
+  applyAccountCredit,
+  emptyEffects,
+  loadOpenReceivables,
+  mergeEffects,
+  toCents,
+  type AllocationEffects,
+  type ArScope,
+} from './allocation'
+import { parsePaymentCsv, sourceRefsForRows, type PaymentCsvRow } from './paymentCsv'
+import { extractInvoiceTokens, matchPayment, type MatchDecision, type MatchableDocument } from './paymentMatcher'
+
+/**
+ * CSV payment import (Spec C, C-D4):
+ *
+ *   1. parse (row errors are reported, never fatal);
+ *   2. duplicate guard — one query for the file's source refs (P-D7);
+ *   3. one batched invoice-number lookup for every token of the file (P-D6);
+ *   4. create the import batch + one `BillingPayment` per new row;
+ *   5. per account, inside `withAccountLock`: allocate to the referenced
+ *      invoices (oldest due first), then spend any remainder as credit on the
+ *      account's other open receivables (D12);
+ *   6. finalise the batch counts from the payments' final statuses.
+ *
+ * Returns the summary plus the allocation effects; the caller emits events
+ * after everything committed.
+ */
+
+export type ImportCounts = {
+  allocated: number
+  partially_allocated: number
+  matched: number
+  unmatched: number
+  duplicate: number
+  rejected: number
+}
+
+export type ImportSummary = {
+  importId: string
+  fileName: string
+  rowCount: number
+  counts: ImportCounts
+  errors: Array<{ row: number; message: string }>
+}
+
+const MAX_STORED_ERRORS = 200
+
+async function existingSourceRefs(em: EntityManager, scope: ArScope, refs: string[]): Promise<Set<string>> {
+  if (refs.length === 0) return new Set()
+  const rows = (await em.execute(
+    `SELECT source_ref FROM billing_payments
+      WHERE tenant_id = ? AND organization_id = ? AND deleted_at IS NULL AND source_ref = ANY(?::text[])`,
+    [scope.tenantId, scope.organizationId, `{${refs.map((r) => `"${r}"`).join(',')}}`],
+  )) as unknown as Array<{ source_ref: string }>
+  return new Set((rows ?? []).map((row) => row.source_ref))
+}
+
+/** Batched lookup of every number-like token of the file (one query). */
+export async function lookupDocumentsByNumber(
+  em: EntityManager,
+  scope: ArScope,
+  references: Array<string | null>,
+): Promise<Map<string, MatchableDocument>> {
+  const tokens = [...new Set(references.flatMap((ref) => extractInvoiceTokens(ref)))]
+  if (tokens.length === 0) return new Map()
+  const rows = (await em.execute(
+    `SELECT i.id, i.number, i.bill_account_id, a.billing_mode, i.currency_code, i.document_type, i.status, i.outstanding
+       FROM billing_invoices i
+       JOIN billing_accounts a ON a.id = i.bill_account_id AND a.tenant_id = i.tenant_id
+      WHERE i.tenant_id = ? AND i.organization_id = ? AND i.deleted_at IS NULL AND i.test_run = false
+        AND i.series IS NOT NULL
+        AND upper(i.number) = ANY(?::text[])`,
+    [scope.tenantId, scope.organizationId, `{${tokens.map((t) => `"${t.replace(/"/g, '')}"`).join(',')}}`],
+  )) as unknown as Array<{
+    id: string
+    number: string
+    bill_account_id: string
+    billing_mode: string
+    currency_code: string
+    document_type: string
+    status: string
+    outstanding: string
+  }>
+  const map = new Map<string, MatchableDocument>()
+  for (const row of rows ?? []) {
+    map.set(row.number.toUpperCase(), {
+      invoiceId: row.id,
+      number: row.number,
+      billAccountId: row.bill_account_id,
+      billingMode: row.billing_mode,
+      currencyCode: row.currency_code,
+      documentType: row.document_type,
+      status: row.status,
+      outstanding: row.outstanding,
+    })
+  }
+  return map
+}
+
+type Planned = { payment: BillingPayment; decision: MatchDecision }
+
+/** Allocates one matched payment inside the account lock (referenced invoices first, then credit). */
+async function settlePayment(tem: EntityManager, scope: ArScope, planned: Planned): Promise<AllocationEffects> {
+  const effects = emptyEffects()
+  const { payment, decision } = planned
+  if (decision.outcome === 'unmatched') return effects
+  const account = { id: decision.billAccountId, currencyCode: payment.currencyCode }
+  const source = { type: 'payment' as const, id: payment.id }
+  if (decision.outcome === 'allocate') {
+    let available = toCents(payment.amount)
+    const receivables = await loadOpenReceivables(tem, scope, account, decision.invoiceIds)
+    for (const receivable of receivables) {
+      if (available <= 0) break
+      const take = Math.min(available, receivable.outstandingCents)
+      if (take <= 0) continue
+      mergeEffects(effects, await allocate(tem, scope, { source, invoiceId: receivable.id, amountCents: take, by: 'auto' }))
+      available -= take
+    }
+  }
+  mergeEffects(effects, await applyAccountCredit(tem, scope, account, { onlySources: [source] }))
+  return effects
+}
+
+export async function importPayments(
+  em: EntityManager,
+  params: { scope: ArScope; fileName: string; content: string; userId?: string | null },
+): Promise<{ summary: ImportSummary; effects: AllocationEffects; paymentIds: string[] }> {
+  const { scope } = params
+  const parsed = parsePaymentCsv(params.content)
+  if (parsed.fatal) {
+    throw new CrudHttpError(400, { error: parsed.fatal, code: 'billing.payment_import.invalid_file' })
+  }
+  const refs = sourceRefsForRows(scope, parsed.rows)
+  const existing = await existingSourceRefs(em, scope, refs)
+  const fresh: Array<{ row: PaymentCsvRow; sourceRef: string }> = []
+  let duplicates = 0
+  parsed.rows.forEach((row, i) => {
+    if (existing.has(refs[i])) duplicates += 1
+    else fresh.push({ row, sourceRef: refs[i] })
+  })
+
+  const documents = await lookupDocumentsByNumber(em, scope, fresh.map((f) => f.row.reference))
+  const now = new Date()
+  const batch = em.create(BillingPaymentImport, {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    fileName: params.fileName,
+    rowCount: parsed.rows.length + parsed.errors.length,
+    userId: params.userId ?? null,
+    createdAt: now,
+    updatedAt: now,
+  })
+  em.persist(batch)
+  await em.flush()
+
+  const planned: Planned[] = fresh.map(({ row, sourceRef }) => {
+    const decision = matchPayment({ reference: row.reference, currency: row.currency }, documents)
+    const payment = em.create(BillingPayment, {
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      receivedAt: new Date(`${row.receivedAt}T00:00:00Z`),
+      amount: row.amount,
+      currencyCode: row.currency,
+      reference: row.reference,
+      payerName: row.payerName,
+      payerAccount: row.payerAccount,
+      source: 'csv',
+      importId: batch.id,
+      billAccountId: decision.billAccountId,
+      status: decision.outcome === 'unmatched' ? 'unmatched' : 'matched',
+      unallocatedAmount: row.amount,
+      matchReason: decision.outcome === 'allocate' ? null : decision.reason,
+      sourceRef,
+      metadata: { csv_line: row.line },
+      createdAt: now,
+      updatedAt: now,
+    })
+    em.persist(payment)
+    return { payment, decision }
+  })
+  await em.flush()
+
+  // Settle per account, one lock per account (operations queue per account).
+  const effects = emptyEffects()
+  const byAccount = new Map<string, Planned[]>()
+  for (const item of planned) {
+    if (item.decision.outcome === 'unmatched') continue
+    const list = byAccount.get(item.decision.billAccountId) ?? []
+    list.push(item)
+    byAccount.set(item.decision.billAccountId, list)
+  }
+  for (const [billAccountId, items] of byAccount) {
+    await withAccountLock(em, { tenantId: scope.tenantId, billAccountId }, async (tem) => {
+      for (const item of items) mergeEffects(effects, await settlePayment(tem, scope, item))
+    })
+  }
+
+  const paymentIds = planned.map((p) => p.payment.id)
+  const statuses = paymentIds.length
+    ? ((await em.execute(
+        `SELECT status, COUNT(*)::int AS n FROM billing_payments
+          WHERE tenant_id = ? AND organization_id = ? AND import_id = ? GROUP BY status`,
+        [scope.tenantId, scope.organizationId, batch.id],
+      )) as unknown as Array<{ status: string; n: number }>)
+    : []
+  const count = (status: string) => Number(statuses.find((s) => s.status === status)?.n ?? 0)
+  const counts: ImportCounts = {
+    allocated: count('allocated'),
+    partially_allocated: count('partially_allocated'),
+    matched: count('matched'),
+    unmatched: count('unmatched'),
+    duplicate: duplicates,
+    rejected: parsed.errors.length,
+  }
+  const errors = parsed.errors.slice(0, MAX_STORED_ERRORS)
+  await em.nativeUpdate(BillingPaymentImport, { id: batch.id } as never, { counts, errors, updatedAt: new Date() } as never)
+
+  return {
+    summary: { importId: batch.id, fileName: params.fileName, rowCount: batch.rowCount, counts, errors },
+    effects,
+    paymentIds,
+  }
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Payment auto-matcher (Spec C, C-D1) — pure.
+ *
+ * Matching uses ONLY invoice numbers found in the payment reference:
+ *   1. `extractInvoiceTokens` pulls number-like tokens out of the title;
+ *   2. the import looks up all tokens of the whole file in one query and
+ *      passes the hits as a map (upper-cased number → document);
+ *   3. `matchPayment` decides per row.
+ *
+ * Exact, full-number, case-insensitive matches only (false positives are
+ * worse than misses; every auto allocation is un-allocatable anyway).
+ */
+
+export type MatchableDocument = {
+  invoiceId: string
+  number: string
+  billAccountId: string
+  billingMode: string
+  currencyCode: string
+  documentType: string
+  status: string
+  outstanding: string
+}
+
+export type MatchDecision =
+  | {
+      outcome: 'allocate'
+      billAccountId: string
+      /** Referenced open receivables, in the order they appear in the title. */
+      invoiceIds: string[]
+    }
+  | {
+      /** Account known but nothing referenced is open → the amount becomes credit. */
+      outcome: 'credit'
+      billAccountId: string
+      reason: 'invoice_already_paid'
+    }
+  | {
+      outcome: 'unmatched'
+      billAccountId: string | null
+      reason: 'no_reference' | 'currency_mismatch' | 'prepaid_account'
+    }
+
+const TOKEN_RE = /[A-Za-z0-9][A-Za-z0-9/_.\-]{1,62}[A-Za-z0-9]/g
+
+/** Number-like tokens of a payment title, upper-cased, de-duplicated, in order. */
+export function extractInvoiceTokens(reference: string | null | undefined): string[] {
+  if (!reference) return []
+  const tokens: string[] = []
+  for (const match of reference.matchAll(TOKEN_RE)) {
+    const token = match[0].toUpperCase()
+    // A number needs at least one digit; plain words are never invoice numbers.
+    if (!/\d/.test(token)) continue
+    if (!tokens.includes(token)) tokens.push(token)
+  }
+  return tokens
+}
+
+const OPEN = ['posted', 'partially_paid']
+const RECEIVABLE = ['invoice', 'debit_memo']
+
+export function matchPayment(
+  payment: { reference: string | null; currency: string },
+  documentsByNumber: ReadonlyMap<string, MatchableDocument>,
+): MatchDecision {
+  const hits = extractInvoiceTokens(payment.reference)
+    .map((token) => documentsByNumber.get(token))
+    .filter((doc): doc is MatchableDocument => Boolean(doc))
+  if (hits.length === 0) return { outcome: 'unmatched', billAccountId: null, reason: 'no_reference' }
+
+  const accounts = new Set(hits.map((doc) => doc.billAccountId))
+  // References to several customers are ambiguous — the operator decides.
+  if (accounts.size > 1) return { outcome: 'unmatched', billAccountId: null, reason: 'no_reference' }
+  const billAccountId = hits[0].billAccountId
+
+  // Prepaid accounts (or their top-up receipts): never allocated (C-D3).
+  if (hits.some((doc) => doc.billingMode === 'prepaid' || doc.documentType === 'receipt')) {
+    return { outcome: 'unmatched', billAccountId, reason: 'prepaid_account' }
+  }
+  if (hits.some((doc) => doc.currencyCode !== payment.currency.toUpperCase())) {
+    return { outcome: 'unmatched', billAccountId, reason: 'currency_mismatch' }
+  }
+  const open = hits.filter(
+    (doc) => RECEIVABLE.includes(doc.documentType) && OPEN.includes(doc.status) && Number.parseFloat(doc.outstanding) > 0,
+  )
+  if (open.length === 0) return { outcome: 'credit', billAccountId, reason: 'invoice_already_paid' }
+  return { outcome: 'allocate', billAccountId, invoiceIds: open.map((doc) => doc.invoiceId) }
+}

package/src/modules/billing/lib/pdf/attachmentStore.ts

@@ -0,0 +1,60 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { Attachment } from '@open-mercato/core/modules/attachments/data/entities'
+import { StorageDriverFactory } from '@open-mercato/core/modules/attachments/lib/drivers'
+import { createAttachmentFromBuffer } from '@open-mercato/core/modules/attachments/lib/createFromBuffer'
+
+/**
+ * Thin adapter over core `attachments` (a platform module billing requires,
+ * P-D1): stores frozen invoice PDFs and reads stored files (PDFs, the
+ * settings logo). The only place billing touches the attachments module, so
+ * tests mock this file instead of storage drivers.
+ */
+
+export type StoredFile = { bytes: Uint8Array; mimeType: string; fileName: string }
+export type FileScope = { tenantId: string; organizationId: string }
+
+export async function storeAttachment(
+  em: EntityManager,
+  scope: FileScope,
+  params: { entityId: string; recordId: string; fileName: string; mimeType: string; bytes: Uint8Array },
+): Promise<string> {
+  const created = await createAttachmentFromBuffer({
+    em,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    entityId: params.entityId,
+    recordId: params.recordId,
+    fileName: params.fileName,
+    mimeType: params.mimeType,
+    buffer: Buffer.from(params.bytes),
+  })
+  return created.id
+}
+
+/** Reads a stored attachment of this scope; null when missing or unreadable. */
+export async function readAttachment(em: EntityManager, scope: FileScope, attachmentId: string): Promise<StoredFile | null> {
+  const attachment = await em.findOne(Attachment, {
+    id: attachmentId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  } as never)
+  if (!attachment) return null
+  try {
+    const driver = await new StorageDriverFactory(em).resolveForPartition(attachment.partitionCode, scope)
+    const { buffer } = await driver.read(attachment.partitionCode, attachment.storagePath)
+    return {
+      bytes: new Uint8Array(buffer),
+      mimeType: attachment.mimeType ?? 'application/octet-stream',
+      fileName: attachment.fileName,
+    }
+  } catch (err) {
+    console.warn('[billing.pdf] attachment could not be read', attachmentId, err)
+    return null
+  }
+}
+
+/** Attachment id from an `/api/attachments/file/<id>` (or image) URL — e.g. `Organization.logo_url`. */
+export function attachmentIdFromUrl(url: string | null | undefined): string | null {
+  const match = /\/api\/attachments\/(?:file|image)\/([0-9a-f-]{36})/i.exec(url ?? '')
+  return match ? match[1] : null
+}