@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/data/entityIds.ts

@@ -1,17 +1,22 @@
 /**
- * Canonical entity IDs for the billing module.
+ * Canonical entity IDs for the billing module — the single source of truth.
+ * Billing code (CRUD factory `entityId`, indexer `entityType`, response
+ * enricher `targetEntity`, …) imports from here; a package must not import
+ * the app's `#generated/entities.ids.generated`.
  *
- * Mirrors what `E.billing.<entity>` would be in
- * `.mercato/generated/entities.ids.generated.ts` if the standalone-app
- * CLI properly discovered `@dainamite/*` workspace entities (see the
- * Phase 0 deviation note in `xd-249-billing-spec.md`). Until the CLI
- * gap is closed upstream, this is the single source of truth — every
- * place that previously would have referenced `E.billing.*` (CRUD
- * factory `entityId`, indexer `entityType`, response enricher
- * `targetEntity`, etc.) imports from here instead.
+ * The build turns this object into the shipped registry
+ * `generated/entities.ids.generated.ts` (scripts/generate-entity-registry.mjs),
+ * which a consuming app's `mercato generate` reads to register these ids in
+ * its own `E.billing`. Without that, the query index rejects billing writes
+ * and `mercato entities install` treats the ids as virtual custom entities.
  *
- * When the CLI is fixed, this file can be replaced by `import { E }
- * from '#generated/entities.ids.generated'` in one PR.
+ * Adding an entity: add it here, then `yarn workspace @dainamite/billing
+ * build` and commit `generated/`. The id suffix must be the snake_case of
+ * the entity class name (`billing_run` → `BillingRun`): that is how the
+ * framework maps an id to its table, and the build fails otherwise. Do not
+ * rely on its table-name fallback — on Open Mercato 0.9 with MikroORM 7 it
+ * never matches (it iterates `MetadataStorage.getAll()` as an array, but
+ * that returns a Map).
  */
 export const billingEntityIds = {
   account: 'billing:billing_account',
@@ -25,6 +30,15 @@ export const billingEntityIds = {
   transaction: 'billing:billing_account_transaction',
   topup: 'billing:billing_topup',
   statement: 'billing:billing_statement',
+  // Spec 0 (standalone invoice ledger)
+  invoice: 'billing:billing_invoice',
+  invoiceLine: 'billing:billing_invoice_line',
+  documentSequence: 'billing:billing_document_sequence',
+  settings: 'billing:billing_settings',
+  // Spec C (payments)
+  payment: 'billing:billing_payment',
+  allocation: 'billing:billing_allocation',
+  paymentImport: 'billing:billing_payment_import',
 } as const
 
 export type BillingEntityId = (typeof billingEntityIds)[keyof typeof billingEntityIds]

package/src/modules/billing/data/validators.ts

@@ -1,4 +1,7 @@
 import { z } from 'zod'
+import { DEFAULT_INVOICE_LANGUAGE, INVOICE_LANGUAGE_CODES } from '../lib/invoiceLanguages'
+import { DOCUMENT_SERIES, validateMask } from '../lib/numbering'
+import { isValidBic, isValidIban, normalizeIban } from '../lib/iban'
 
 // ─── Enums ───────────────────────────────────────────────────────
 
@@ -8,6 +11,19 @@ export type BillingItemType = (typeof BILLING_ITEM_TYPES)[number]
 export const BILL_CYCLES = ['weekly', 'monthly', 'quarterly', 'annually'] as const
 export type BillCycle = (typeof BILL_CYCLES)[number]
 
+// Spec A: when a recurring item is charged relative to the bill date —
+// for the coming period (in advance, default) or the period just ended.
+export const CHARGE_TIMINGS = ['in_advance', 'in_arrears'] as const
+export type ChargeTiming = (typeof CHARGE_TIMINGS)[number]
+
+// Spec F (F-D2): the basis the item price was entered on.
+export const PRICE_BASES = ['net', 'gross'] as const
+export type PriceBasis = (typeof PRICE_BASES)[number]
+
+// Spec F (F-D3): where prepaid VAT is charged.
+export const PREPAID_TAX_POINTS = ['topup', 'consumption'] as const
+export type PrepaidTaxPoint = (typeof PREPAID_TAX_POINTS)[number]
+
 export const BILL_RUN_TRIGGERS = ['schedule', 'manual'] as const
 export type BillRunTrigger = (typeof BILL_RUN_TRIGGERS)[number]
 
@@ -28,9 +44,14 @@ export type BillRunOutcomeStatus = (typeof BILL_RUN_OUTCOME_STATUSES)[number]
 export const DRAFT_INVOICE_EDIT_ACTIONS = ['line_added', 'line_removed', 'line_edited'] as const
 export type DraftInvoiceEditAction = (typeof DRAFT_INVOICE_EDIT_ACTIONS)[number]
 
-export const INVOICE_STATUSES = ['draft', 'posted', 'paid', 'void'] as const
+// Spec 0: billing-owned document statuses. No 'void' — a posted document is
+// only neutralised by a credit memo ('credited'); drafts are deleted.
+export const INVOICE_STATUSES = ['draft', 'posted', 'partially_paid', 'paid', 'credited'] as const
 export type InvoiceStatus = (typeof INVOICE_STATUSES)[number]
 
+export const DOCUMENT_TYPES = ['invoice', 'credit_memo', 'debit_memo', 'receipt'] as const
+export type DocumentType = (typeof DOCUMENT_TYPES)[number]
+
 // ─── Prepaid (SPEC-002) enums ────────────────────────────────────
 
 export const BILLING_MODES = ['postpaid', 'prepaid'] as const
@@ -55,6 +76,13 @@ export const TOPUP_STATUSES = [
 ] as const
 export type TopupStatus = (typeof TOPUP_STATUSES)[number]
 
+// Spec E (B2C): a billing account belongs to a company or a person. Both
+// live in the customers module under one `customer_entities` id space, so
+// `customer_id` is kind-agnostic — `customer_kind` only drives the lookup
+// and the label.
+export const CUSTOMER_KINDS = ['company', 'person'] as const
+export type CustomerKind = (typeof CUSTOMER_KINDS)[number]
+
 export const STATEMENT_STATUSES = ['generated', 'sent'] as const
 export type StatementStatus = (typeof STATEMENT_STATUSES)[number]
 
@@ -255,14 +283,24 @@ const listPaginationBase = {
 // 4dp string at persist time.
 const moneyNonNegative = z.number().finite().nonnegative()
 
+// Invoice language must be one the document template supports (Spec E, D22).
+// Case/whitespace-tolerant on input, canonical lowercase code on output.
+// Spec B: payment terms in days (0 = due on issue).
+const paymentTermsDaysSchema = z.coerce.number().int().min(0).max(365)
+
+const invoiceLanguageSchema = z.string().trim().toLowerCase().pipe(z.enum(INVOICE_LANGUAGE_CODES))
+
 export const billingAccountCreateSchema = scopedSchema.extend({
   customerId: z.string().min(1).max(255),
+  // Immutable after create (like customerId). Default 'company' keeps
+  // existing callers (CPQ connector, seeds) unaffected.
+  customerKind: z.enum(CUSTOMER_KINDS).default('company'),
   name: z.string().trim().min(1).max(255),
   currencyCode: z.string().trim().toUpperCase().length(3),
   billCycle: z.enum(BILL_CYCLES),
   billCycleAnchor: billCycleAnchorSchema,
   invoiceEmail: z.string().trim().email().max(320),
-  invoiceLanguage: z.string().trim().toLowerCase().min(2).max(5),
+  invoiceLanguage: invoiceLanguageSchema.default(DEFAULT_INVOICE_LANGUAGE),
   // Nullable + optional — consistent with the update schema, and the
   // cpq-billing-connector's shell-account seed sends `taxId: null`
   // for customers with no tax id.
@@ -279,6 +317,9 @@ export const billingAccountCreateSchema = scopedSchema.extend({
   // Initial low-balance threshold for a prepaid account's balance row.
   // Null = resolve the tenant config default at read time.
   lowBalanceThreshold: moneyNonNegative.nullable().optional(),
+  // Spec B: null/omitted = the organization default payment terms.
+  paymentTermsDays: paymentTermsDaysSchema.nullable().optional(),
+  autoSendInvoice: z.boolean().optional(),
 })
 
 export type BillingAccountCreateInput = z.infer<typeof billingAccountCreateSchema>
@@ -289,7 +330,7 @@ export const billingAccountUpdateSchema = scopedSchema.extend({
   billCycle: z.enum(BILL_CYCLES).optional(),
   billCycleAnchor: billCycleAnchorSchema.optional(),
   invoiceEmail: z.string().trim().email().max(320).optional(),
-  invoiceLanguage: z.string().trim().toLowerCase().min(2).max(5).optional(),
+  invoiceLanguage: invoiceLanguageSchema.optional(),
   taxId: z.string().trim().max(64).nullable().optional(),
   invoiceAddress: invoiceAddressSchema.optional(),
   nextBillDate: z.coerce.date().optional(),
@@ -302,10 +343,13 @@ export const billingAccountUpdateSchema = scopedSchema.extend({
   // Editing the prepaid balance row's low-balance threshold. Null clears it
   // back to the tenant config default.
   lowBalanceThreshold: moneyNonNegative.nullable().optional(),
+  paymentTermsDays: paymentTermsDaysSchema.nullable().optional(),
+  autoSendInvoice: z.boolean().optional(),
   // `currencyCode` is intentionally NOT updatable — currency is frozen at
   // account create time so historical invoices keep their currency context.
   // `customerId` is also immutable; create a new account if the customer
-  // FK changes.
+  // FK changes. `customerKind` follows `customerId` and is likewise not
+  // updatable.
 })
 
 export type BillingAccountUpdateInput = z.infer<typeof billingAccountUpdateSchema>
@@ -321,11 +365,17 @@ export const billingAccountListQuerySchema = z
     ...listPaginationBase,
     id: z.string().uuid().optional(),
     customerId: z.string().optional(),
+    customerKind: z.enum(CUSTOMER_KINDS).optional(),
     currencyCode: z.string().optional(),
     billCycle: z.enum(BILL_CYCLES).optional(),
     billingMode: z.enum(BILLING_MODES).optional(),
     isActive: z.coerce.boolean().optional(),
     search: z.string().optional(),
+    // Spec F (F8): only accounts with at least one overdue receivable.
+    hasOverdue: z
+      .union([z.boolean(), z.enum(['true', 'false'])])
+      .transform((value) => value === true || value === 'true')
+      .optional(),
   })
   .passthrough()
 
@@ -333,6 +383,49 @@ export type BillingAccountListQuery = z.infer<typeof billingAccountListQuerySche
 
 // ─── BillingItem payloads ────────────────────────────────────────
 
+// Spec A: `chargeTiming` / `prorate` only mean something for recurring
+// items. Omitted → the command applies the defaults (in_advance, true).
+// Setting a non-default value on another type is a client mistake.
+// Spec B (B-D1): VAT rate in percent. Omitted on create → the command fills
+// the organization default; never re-filled on update.
+const taxRateSchema = z.coerce.number().finite().min(0).max(100)
+
+const chargeTimingFields = {
+  chargeTiming: z.enum(CHARGE_TIMINGS).optional(),
+  prorate: z.boolean().optional(),
+  // Spec F (F-D2). Omitted → 'net' on create; unchanged on update.
+  priceBasis: z.enum(PRICE_BASES).optional(),
+}
+
+export const GROSS_TIERED_UNSUPPORTED_MESSAGE = 'billing.item.gross_tiered_unsupported'
+
+/** Tiered usage rates (`{ model, tiers }`) are always net (Spec F, P-D4). */
+export function isTieredRate(rateJson: unknown): boolean {
+  return typeof rateJson === 'object' && rateJson !== null && 'model' in rateJson && 'tiers' in rateJson
+}
+
+function refinePriceBasis(val: { priceBasis?: PriceBasis; rateJson: unknown }, ctx: z.RefinementCtx): void {
+  if (val.priceBasis === 'gross' && isTieredRate(val.rateJson)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['priceBasis'], message: GROSS_TIERED_UNSUPPORTED_MESSAGE })
+  }
+}
+
+export const CHARGE_TIMING_RECURRING_ONLY_MESSAGE =
+  'chargeTiming / prorate can only be set on recurring items'
+
+function refineChargeTiming(
+  val: { type: BillingItemType; chargeTiming?: ChargeTiming; prorate?: boolean },
+  ctx: z.RefinementCtx,
+): void {
+  if (val.type === 'recurring') return
+  if (val.chargeTiming !== undefined && val.chargeTiming !== 'in_advance') {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['chargeTiming'], message: CHARGE_TIMING_RECURRING_ONLY_MESSAGE })
+  }
+  if (val.prorate === false) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['prorate'], message: CHARGE_TIMING_RECURRING_ONLY_MESSAGE })
+  }
+}
+
 const ratePayloadByType = z
   .object({
     type: z.enum(BILLING_ITEM_TYPES),
@@ -363,10 +456,14 @@ export const billingItemCreateSchema = scopedSchema
     subscriptionItemId: z.string().trim().max(255).optional(),
     // `source_ref` is the idempotency key. NULL → no dedup, always create.
     sourceRef: z.string().trim().min(1).max(255).optional(),
+    taxRate: taxRateSchema.optional(),
+    ...chargeTimingFields,
     // currency_mismatch and billed_to_date are system-managed, never set by
     // clients on create.
   })
   .superRefine((val, ctx) => {
+    refineChargeTiming(val, ctx)
+    refinePriceBasis(val, ctx)
     try {
       validateRateJson(val.type, val.rateJson)
     } catch (err) {
@@ -403,8 +500,12 @@ const billingItemBulkEntrySchema = z
     subscriptionId: z.string().trim().max(255).optional(),
     subscriptionItemId: z.string().trim().max(255).optional(),
     sourceRef: z.string().trim().min(1).max(255).optional(),
+    taxRate: taxRateSchema.optional(),
+    ...chargeTimingFields,
   })
   .superRefine((val, ctx) => {
+    refineChargeTiming(val, ctx)
+    refinePriceBasis(val, ctx)
     try {
       validateRateJson(val.type, val.rateJson)
     } catch (err) {
@@ -445,10 +546,26 @@ export const billingItemUpdateSchema = scopedSchema.extend({
   subscriptionItemId: z.string().trim().max(255).nullable().optional(),
   // `source_ref` immutable — it's the idempotency identity of the item.
   isActive: z.boolean().optional(),
+  // Affects future invoices only — posted lines keep their snapshot.
+  taxRate: taxRateSchema.optional(),
+  // Recurring only (enforced by the command, which knows the item type).
+  // Safe to change after billing: the `billed_to_date` watermark prevents
+  // any day from being billed twice.
+  ...chargeTimingFields,
 })
 
 export type BillingItemUpdateInput = z.infer<typeof billingItemUpdateSchema>
 
+// Change a recurring item's price from a date on: end the item the day
+// before, start a copy with the new price (see lib/itemPriceChange.ts).
+export const billingItemChangePriceSchema = scopedSchema.extend({
+  id: z.string().uuid(),
+  effectiveDate: z.coerce.date(),
+  unitPrice: z.coerce.number().finite().nonnegative(),
+})
+
+export type BillingItemChangePriceInput = z.infer<typeof billingItemChangePriceSchema>
+
 export const billingItemDeleteSchema = scopedSchema.extend({
   id: z.string().uuid(),
 })
@@ -524,7 +641,9 @@ export const billingRunTriggerSchema = scopedSchema.extend({
   mode: z.enum(BILL_RUN_MODES).default('real'),
   asOfDate: z.coerce.date().optional(),
   scopedAccountIds: z.array(z.string().uuid()).optional(),
-  catchUp: z.boolean().optional(),
+  // Spec A: there is no `catchUp` flag — every run bills all due cycles up
+  // to `asOfDate`. Old clients still sending it are not rejected: the
+  // object schema strips unknown keys.
 })
 
 export type BillingRunTriggerInput = z.infer<typeof billingRunTriggerSchema>
@@ -546,6 +665,8 @@ export const billingRunListQuerySchema = z
     parentRunId: z.string().uuid().optional(),
     asOfDateFrom: z.coerce.date().optional(),
     asOfDateTo: z.coerce.date().optional(),
+    // Spec F (F1): narrow the list to one run mode.
+    mode: z.enum(['real', 'test', 'dry']).optional(),
   })
   .passthrough()
 
@@ -559,14 +680,20 @@ export const billingInvoicePostSchema = scopedSchema.extend({
 
 export type BillingInvoicePostInput = z.infer<typeof billingInvoicePostSchema>
 
+// Spec B — email a posted document (manual send / resend).
+export const billingInvoiceSendSchema = scopedSchema.extend({
+  invoiceId: z.string().uuid(),
+})
+
+export type BillingInvoiceSendInput = z.infer<typeof billingInvoiceSendSchema>
+
 // ─── Draft invoice edits (Phase 4b) ──────────────────────────────
 
 /**
  * Fields the operator may change on a draft invoice line. Per spec:
  * "operator CAN: add lines, remove lines, edit line description /
- * quantity / unit_price / amount". `taxRate` is owned by core/sales
- * tax service and `currencyCode` is frozen at account create — both
- * intentionally absent from this schema.
+ * quantity / unit_price / amount". Spec B adds `taxRate` (VAT % of the
+ * line). `currencyCode` is frozen at account create and intentionally absent.
  */
 const lineEditableFields = z.object({
   description: z.string().trim().min(1).max(500).optional(),
@@ -577,6 +704,7 @@ const lineEditableFields = z.object({
   // credits or rounding fix-ups). When provided, it short-circuits
   // the auto-compute path.
   totalNetAmount: z.coerce.number().finite().optional(),
+  taxRate: taxRateSchema.optional(),
 })
 
 export const billingInvoiceEditLineSchema = scopedSchema.extend({
@@ -597,6 +725,8 @@ export const billingInvoiceAddLineSchema = scopedSchema.extend({
   // Billing Item.
   billingItemId: z.string().uuid().optional(),
   billingType: z.enum(BILLING_ITEM_TYPES).optional(),
+  // Omitted → the organization default VAT rate.
+  taxRate: taxRateSchema.optional(),
 })
 
 export type BillingInvoiceAddLineInput = z.infer<typeof billingInvoiceAddLineSchema>
@@ -617,6 +747,24 @@ export const billingWipeTestInvoicesSchema = scopedSchema.extend({
 
 export type BillingWipeTestInvoicesInput = z.infer<typeof billingWipeTestInvoicesSchema>
 
+// Spec F (F-D1): test and dry runs can be deleted (real runs never).
+export const billingRunDeleteSchema = scopedSchema.extend({
+  billRunId: z.string().uuid(),
+})
+
+export type BillingRunDeleteInput = z.infer<typeof billingRunDeleteSchema>
+
+// Post the draft invoices of a REAL run, one bounded batch per call; the
+// caller passes back `nextCursor` until `remaining` is 0.
+export const billingRunPostDraftsSchema = scopedSchema.extend({
+  billRunId: z.string().uuid(),
+  /** Continue after this invoice id (ids are processed in ascending order). */
+  afterInvoiceId: z.string().uuid().optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+})
+
+export type BillingRunPostDraftsInput = z.infer<typeof billingRunPostDraftsSchema>
+
 // ─── Prepaid: top-ups (SPEC-002 P2) ──────────────────────────────
 
 export const billingTopupCreateSchema = scopedSchema.extend({
@@ -704,3 +852,235 @@ export const billingStatementListQuerySchema = z
 export type BillingStatementListQuery = z.infer<typeof billingStatementListQuerySchema>
 
 
+
+// ─── Spec 0 — invoice ledger + billing settings ──────────────────
+
+// Query-string boolean: only the literal strings count ("false" must NOT
+// coerce to true the way z.coerce.boolean() would).
+const queryBoolean = z.preprocess(
+  (value) => (value === 'true' || value === true ? true : value === 'false' || value === false ? false : undefined),
+  z.boolean().optional(),
+)
+
+export const billingInvoiceListQuerySchema = z
+  .object({
+    ...listPaginationBase,
+    id: z.string().uuid().optional(),
+    status: z.enum(INVOICE_STATUSES).optional(),
+    documentType: z.enum(DOCUMENT_TYPES).optional(),
+    billRunId: z.string().uuid().optional(),
+    billAccountId: z.string().uuid().optional(),
+    testRun: queryBoolean,
+    search: z.string().trim().max(100).optional(),
+    // Spec B: computed overdue (B-D6) and due-date window.
+    overdue: queryBoolean,
+    dueFrom: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    dueTo: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+  })
+  .passthrough()
+
+export type BillingInvoiceListQuery = z.infer<typeof billingInvoiceListQuerySchema>
+
+const numberMaskSchema = z
+  .string()
+  .trim()
+  .superRefine((mask, ctx) => {
+    for (const code of validateMask(mask)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: code })
+    }
+  })
+
+const moneyString = z.coerce.number().finite().nonnegative()
+
+/** Trimmed optional text; '' → null (clears the field). */
+function optionalText(max: number) {
+  return z
+    .string()
+    .trim()
+    .max(max)
+    .transform((value) => (value === '' ? null : value))
+    .nullable()
+    .optional()
+}
+
+// Seller address: same shape (and country rule) as the buyer's invoice address.
+const sellerAddressSchema = invoiceAddressSchema
+
+export const billingSettingsUpdateSchema = scopedSchema.extend({
+  lowBalanceThresholdDefault: moneyString.optional(),
+  nearLimitBufferDefault: moneyString.optional(),
+  statementEnabled: z.boolean().optional(),
+  topupTaxRate: z.coerce.number().finite().min(0).max(100).optional(),
+  topupProvider: z.string().trim().min(1).max(64).optional(),
+  numberMasks: z
+    .object(Object.fromEntries(DOCUMENT_SERIES.map((series) => [series, numberMaskSchema.optional()])) as Record<
+      (typeof DOCUMENT_SERIES)[number],
+      z.ZodOptional<typeof numberMaskSchema>
+    >)
+    .strict()
+    .optional(),
+  // Seller / payment / document fields (Spec B). Empty string clears.
+  legalName: optionalText(255),
+  sellerAddress: sellerAddressSchema.nullable().optional(),
+  taxId: optionalText(64),
+  bankName: optionalText(255),
+  iban: z
+    .string()
+    .transform(normalizeIban)
+    .refine((value) => value === '' || isValidIban(value), { message: 'billing.settings.error.iban_invalid' })
+    .transform((value) => (value === '' ? null : value))
+    .nullable()
+    .optional(),
+  bic: z
+    .string()
+    .trim()
+    .toUpperCase()
+    .refine((value) => value === '' || isValidBic(value), { message: 'billing.settings.error.bic_invalid' })
+    .transform((value) => (value === '' ? null : value))
+    .nullable()
+    .optional(),
+  invoiceFooter: optionalText(2000),
+  logoAttachmentId: z.string().uuid().nullable().optional(),
+  defaultPaymentTermsDays: paymentTermsDaysSchema.optional(),
+  defaultTaxRate: taxRateSchema.optional(),
+  // Spec F (F-D3).
+  prepaidTaxPoint: z.enum(PREPAID_TAX_POINTS).optional(),
+})
+
+export type BillingSettingsUpdateInput = z.infer<typeof billingSettingsUpdateSchema>
+
+// ─── Spec C — payments ───────────────────────────────────────────
+
+export const PAYMENT_STATUSES = [
+  'unmatched',
+  'matched',
+  'partially_allocated',
+  'allocated',
+  'ignored',
+  'converted_to_topup',
+] as const
+export type PaymentStatus = (typeof PAYMENT_STATUSES)[number]
+
+export const PAYMENT_SOURCES = ['csv', 'manual', 'gateway'] as const
+export type PaymentSource = (typeof PAYMENT_SOURCES)[number]
+
+export const PAYMENT_MATCH_REASONS = [
+  'no_reference',
+  'currency_mismatch',
+  'invoice_already_paid',
+  'prepaid_account',
+  'manual',
+] as const
+export type PaymentMatchReason = (typeof PAYMENT_MATCH_REASONS)[number]
+
+export const ALLOCATION_SOURCE_TYPES = ['payment', 'credit_memo'] as const
+export type AllocationSourceType = (typeof ALLOCATION_SOURCE_TYPES)[number]
+
+export const ALLOCATED_BY = ['auto', 'credit', 'user', 'gateway'] as const
+export type AllocatedBy = (typeof ALLOCATED_BY)[number]
+
+const isoDateString = z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+const positiveMoney = z.coerce.number().finite().positive()
+
+export const billingPaymentCreateSchema = scopedSchema.extend({
+  receivedAt: isoDateString,
+  amount: positiveMoney,
+  currencyCode: z.string().trim().toUpperCase().length(3),
+  reference: z.string().trim().max(500).optional(),
+  payerName: z.string().trim().max(255).optional(),
+  payerAccount: z.string().trim().max(64).optional(),
+  // Known account → status `matched` and credit auto-apply; else `unmatched`.
+  billAccountId: z.string().uuid().optional(),
+})
+export type BillingPaymentCreateInput = z.infer<typeof billingPaymentCreateSchema>
+
+export const billingPaymentAssignSchema = scopedSchema.extend({
+  paymentId: z.string().uuid(),
+  billAccountId: z.string().uuid(),
+})
+export type BillingPaymentAssignInput = z.infer<typeof billingPaymentAssignSchema>
+
+export const billingPaymentAllocateSchema = scopedSchema.extend({
+  paymentId: z.string().uuid(),
+  allocations: z
+    .array(z.object({ invoiceId: z.string().uuid(), amount: positiveMoney }))
+    .min(1)
+    .max(100),
+})
+export type BillingPaymentAllocateInput = z.infer<typeof billingPaymentAllocateSchema>
+
+export const billingAllocationRemoveSchema = scopedSchema.extend({
+  allocationId: z.string().uuid(),
+})
+export type BillingAllocationRemoveInput = z.infer<typeof billingAllocationRemoveSchema>
+
+export const billingPaymentIdSchema = scopedSchema.extend({
+  paymentId: z.string().uuid(),
+})
+export type BillingPaymentIdInput = z.infer<typeof billingPaymentIdSchema>
+
+export const billingPaymentConvertSchema = scopedSchema.extend({
+  paymentId: z.string().uuid(),
+  billAccountId: z.string().uuid(),
+})
+export type BillingPaymentConvertInput = z.infer<typeof billingPaymentConvertSchema>
+
+// CSV upload: 2 MB of text, ≤ 5,000 data rows (checked by the parser).
+export const PAYMENT_IMPORT_MAX_BYTES = 2 * 1024 * 1024
+export const PAYMENT_IMPORT_MAX_ROWS = 5000
+
+export const billingPaymentImportSchema = scopedSchema.extend({
+  fileName: z.string().trim().min(1).max(255),
+  content: z.string().max(PAYMENT_IMPORT_MAX_BYTES),
+})
+export type BillingPaymentImportInput = z.infer<typeof billingPaymentImportSchema>
+
+export const billingPaymentListQuerySchema = z
+  .object({
+    ...listPaginationBase,
+    id: z.string().uuid().optional(),
+    status: z.enum(PAYMENT_STATUSES).optional(),
+    billAccountId: z.string().uuid().optional(),
+    importId: z.string().uuid().optional(),
+    receivedFrom: isoDateString.optional(),
+    receivedTo: isoDateString.optional(),
+    search: z.string().trim().max(100).optional(),
+  })
+  .passthrough()
+export type BillingPaymentListQuery = z.infer<typeof billingPaymentListQuerySchema>
+
+export const billingPaymentImportListQuerySchema = z
+  .object({ ...listPaginationBase, id: z.string().uuid().optional() })
+  .passthrough()
+export type BillingPaymentImportListQuery = z.infer<typeof billingPaymentImportListQuerySchema>
+
+// ─── Spec D — credit / debit memos ───────────────────────────────
+
+export const MEMO_TYPES = ['credit_memo', 'debit_memo'] as const
+export type MemoType = (typeof MEMO_TYPES)[number]
+
+const memoLineSchema = z.object({
+  // Copied from the original (credit prefill). The original line's VAT rate wins.
+  correctsLineId: z.string().uuid().optional(),
+  description: z.string().trim().min(1).max(500),
+  quantity: z.coerce.number().finite().positive(),
+  unitPriceNet: z.coerce.number().finite().nonnegative(),
+  // New lines: omitted → organization default rate.
+  taxRate: z.coerce.number().finite().min(0).max(100).optional(),
+})
+export type MemoLineInput = z.infer<typeof memoLineSchema>
+
+export const billingMemoCreateSchema = scopedSchema.extend({
+  invoiceId: z.string().uuid(),
+  type: z.enum(MEMO_TYPES),
+  reason: z.string().trim().min(1, 'billing.memo.error.reason_required').max(1000),
+  // Credit memo without lines = full credit (all original lines). Debit memo
+  // without lines = empty draft (lines are added on the draft).
+  lines: z.array(memoLineSchema).max(200).optional(),
+})
+export type BillingMemoCreateInput = z.infer<typeof billingMemoCreateSchema>
+
+export const billingDraftDeleteSchema = scopedSchema.extend({
+  invoiceId: z.string().uuid(),
+})
+export type BillingDraftDeleteInput = z.infer<typeof billingDraftDeleteSchema>