@dainamite/billing 0.19.0 → 0.21.0

package/dist/modules/billing/data/validators.js

@@ -1,6 +1,12 @@
 import { z } from "zod";
+import { DEFAULT_INVOICE_LANGUAGE, INVOICE_LANGUAGE_CODES } from "../lib/invoiceLanguages.js";
+import { DOCUMENT_SERIES, validateMask } from "../lib/numbering.js";
+import { isValidBic, isValidIban, normalizeIban } from "../lib/iban.js";
 const BILLING_ITEM_TYPES = ["one_time", "recurring", "usage"];
 const BILL_CYCLES = ["weekly", "monthly", "quarterly", "annually"];
+const CHARGE_TIMINGS = ["in_advance", "in_arrears"];
+const PRICE_BASES = ["net", "gross"];
+const PREPAID_TAX_POINTS = ["topup", "consumption"];
 const BILL_RUN_TRIGGERS = ["schedule", "manual"];
 const BILL_RUN_STATUSES = ["running", "completed", "partial_failure", "failed"];
 const BILL_RUN_OUTCOME_STATUSES = [
@@ -13,7 +19,8 @@ const BILL_RUN_OUTCOME_STATUSES = [
   "failed"
 ];
 const DRAFT_INVOICE_EDIT_ACTIONS = ["line_added", "line_removed", "line_edited"];
-const INVOICE_STATUSES = ["draft", "posted", "paid", "void"];
+const INVOICE_STATUSES = ["draft", "posted", "partially_paid", "paid", "credited"];
+const DOCUMENT_TYPES = ["invoice", "credit_memo", "debit_memo", "receipt"];
 const BILLING_MODES = ["postpaid", "prepaid"];
 const TRANSACTION_TYPES = [
   "topup",
@@ -30,6 +37,7 @@ const TOPUP_STATUSES = [
   "expired",
   "cancelled"
 ];
+const CUSTOMER_KINDS = ["company", "person"];
 const STATEMENT_STATUSES = ["generated", "sent"];
 const BALANCE_STATUSES = ["ok", "low", "exhausted"];
 const CREDIT_STATUSES = ["within_limit", "near_limit", "over_limit"];
@@ -134,14 +142,19 @@ const listPaginationBase = {
   sortDir: z.enum(["asc", "desc"]).optional()
 };
 const moneyNonNegative = z.number().finite().nonnegative();
+const paymentTermsDaysSchema = z.coerce.number().int().min(0).max(365);
+const invoiceLanguageSchema = z.string().trim().toLowerCase().pipe(z.enum(INVOICE_LANGUAGE_CODES));
 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.
@@ -157,7 +170,10 @@ const billingAccountCreateSchema = scopedSchema.extend({
   creditLimit: moneyNonNegative.optional(),
   // Initial low-balance threshold for a prepaid account's balance row.
   // Null = resolve the tenant config default at read time.
-  lowBalanceThreshold: moneyNonNegative.nullable().optional()
+  lowBalanceThreshold: moneyNonNegative.nullable().optional(),
+  // Spec B: null/omitted = the organization default payment terms.
+  paymentTermsDays: paymentTermsDaysSchema.nullable().optional(),
+  autoSendInvoice: z.boolean().optional()
 });
 const billingAccountUpdateSchema = scopedSchema.extend({
   id: z.string().uuid(),
@@ -165,7 +181,7 @@ 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(),
@@ -177,11 +193,14 @@ const billingAccountUpdateSchema = scopedSchema.extend({
   creditLimit: moneyNonNegative.optional(),
   // Editing the prepaid balance row's low-balance threshold. Null clears it
   // back to the tenant config default.
-  lowBalanceThreshold: moneyNonNegative.nullable().optional()
+  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.
 });
 const billingAccountDeleteSchema = scopedSchema.extend({
   id: z.string().uuid()
@@ -190,12 +209,41 @@ const billingAccountListQuerySchema = z.object({
   ...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()
+  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();
+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()
+};
+const GROSS_TIERED_UNSUPPORTED_MESSAGE = "billing.item.gross_tiered_unsupported";
+function isTieredRate(rateJson) {
+  return typeof rateJson === "object" && rateJson !== null && "model" in rateJson && "tiers" in rateJson;
+}
+function refinePriceBasis(val, ctx) {
+  if (val.priceBasis === "gross" && isTieredRate(val.rateJson)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["priceBasis"], message: GROSS_TIERED_UNSUPPORTED_MESSAGE });
+  }
+}
+const CHARGE_TIMING_RECURRING_ONLY_MESSAGE = "chargeTiming / prorate can only be set on recurring items";
+function refineChargeTiming(val, ctx) {
+  if (val.type === "recurring") return;
+  if (val.chargeTiming !== void 0 && 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),
   rateJson: z.unknown()
@@ -222,10 +270,14 @@ const billingItemCreateSchema = scopedSchema.extend({
   subscriptionId: z.string().trim().max(255).optional(),
   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()
+  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) {
@@ -250,8 +302,12 @@ const billingItemBulkEntrySchema = z.object({
   uomCode: z.string().trim().max(64).optional(),
   subscriptionId: z.string().trim().max(255).optional(),
   subscriptionItemId: z.string().trim().max(255).optional(),
-  sourceRef: z.string().trim().min(1).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) {
@@ -285,7 +341,18 @@ const billingItemUpdateSchema = scopedSchema.extend({
   subscriptionId: z.string().trim().max(255).nullable().optional(),
   subscriptionItemId: z.string().trim().max(255).nullable().optional(),
   // `source_ref` immutable — it's the idempotency identity of the item.
-  isActive: z.boolean().optional()
+  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
+});
+const billingItemChangePriceSchema = scopedSchema.extend({
+  id: z.string().uuid(),
+  effectiveDate: z.coerce.date(),
+  unitPrice: z.coerce.number().finite().nonnegative()
 });
 const billingItemDeleteSchema = scopedSchema.extend({
   id: z.string().uuid()
@@ -338,8 +405,10 @@ const billingRunTriggerSchema = scopedSchema.extend({
   // from the input shape.
   mode: z.enum(BILL_RUN_MODES).default("real"),
   asOfDate: z.coerce.date().optional(),
-  scopedAccountIds: z.array(z.string().uuid()).optional(),
-  catchUp: z.boolean().optional()
+  scopedAccountIds: z.array(z.string().uuid()).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.
 });
 const billingRunRetryFailedSchema = scopedSchema.extend({
   billRunId: z.string().uuid(),
@@ -353,11 +422,16 @@ const billingRunListQuerySchema = z.object({
   triggeredBy: z.enum(BILL_RUN_TRIGGERS).optional(),
   parentRunId: z.string().uuid().optional(),
   asOfDateFrom: z.coerce.date().optional(),
-  asOfDateTo: 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();
 const billingInvoicePostSchema = scopedSchema.extend({
   invoiceId: z.string().uuid()
 });
+const billingInvoiceSendSchema = scopedSchema.extend({
+  invoiceId: z.string().uuid()
+});
 const lineEditableFields = z.object({
   description: z.string().trim().min(1).max(500).optional(),
   quantity: z.coerce.number().finite().nonnegative().optional(),
@@ -366,7 +440,8 @@ const lineEditableFields = z.object({
   // than `unit_price × quantity`" cases (rare; mostly for negative
   // credits or rounding fix-ups). When provided, it short-circuits
   // the auto-compute path.
-  totalNetAmount: z.coerce.number().finite().optional()
+  totalNetAmount: z.coerce.number().finite().optional(),
+  taxRate: taxRateSchema.optional()
 });
 const billingInvoiceEditLineSchema = scopedSchema.extend({
   invoiceId: z.string().uuid(),
@@ -382,7 +457,9 @@ const billingInvoiceAddLineSchema = scopedSchema.extend({
   // `billing_item_id` blank because ad-hoc lines aren't tied to a
   // Billing Item.
   billingItemId: z.string().uuid().optional(),
-  billingType: z.enum(BILLING_ITEM_TYPES).optional()
+  billingType: z.enum(BILLING_ITEM_TYPES).optional(),
+  // Omitted → the organization default VAT rate.
+  taxRate: taxRateSchema.optional()
 });
 const billingInvoiceRemoveLineSchema = scopedSchema.extend({
   invoiceId: z.string().uuid(),
@@ -392,6 +469,15 @@ const billingWipeTestInvoicesSchema = scopedSchema.extend({
   /** Optional — when set, wipes only test invoices from this run. */
   billRunId: z.string().uuid().optional()
 });
+const billingRunDeleteSchema = scopedSchema.extend({
+  billRunId: z.string().uuid()
+});
+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()
+});
 const billingTopupCreateSchema = scopedSchema.extend({
   // The route maps the `/accounts/{id}/topups` path param into billAccountId.
   billAccountId: z.string().uuid(),
@@ -446,7 +532,144 @@ const billingStatementListQuerySchema = z.object({
   periodEndFrom: z.coerce.date().optional(),
   periodEndTo: z.coerce.date().optional()
 }).passthrough();
+const queryBoolean = z.preprocess(
+  (value) => value === "true" || value === true ? true : value === "false" || value === false ? false : void 0,
+  z.boolean().optional()
+);
+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();
+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();
+function optionalText(max) {
+  return z.string().trim().max(max).transform((value) => value === "" ? null : value).nullable().optional();
+}
+const sellerAddressSchema = invoiceAddressSchema;
+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()]))).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(2e3),
+  logoAttachmentId: z.string().uuid().nullable().optional(),
+  defaultPaymentTermsDays: paymentTermsDaysSchema.optional(),
+  defaultTaxRate: taxRateSchema.optional(),
+  // Spec F (F-D3).
+  prepaidTaxPoint: z.enum(PREPAID_TAX_POINTS).optional()
+});
+const PAYMENT_STATUSES = [
+  "unmatched",
+  "matched",
+  "partially_allocated",
+  "allocated",
+  "ignored",
+  "converted_to_topup"
+];
+const PAYMENT_SOURCES = ["csv", "manual", "gateway"];
+const PAYMENT_MATCH_REASONS = [
+  "no_reference",
+  "currency_mismatch",
+  "invoice_already_paid",
+  "prepaid_account",
+  "manual"
+];
+const ALLOCATION_SOURCE_TYPES = ["payment", "credit_memo"];
+const ALLOCATED_BY = ["auto", "credit", "user", "gateway"];
+const isoDateString = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+const positiveMoney = z.coerce.number().finite().positive();
+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()
+});
+const billingPaymentAssignSchema = scopedSchema.extend({
+  paymentId: z.string().uuid(),
+  billAccountId: z.string().uuid()
+});
+const billingPaymentAllocateSchema = scopedSchema.extend({
+  paymentId: z.string().uuid(),
+  allocations: z.array(z.object({ invoiceId: z.string().uuid(), amount: positiveMoney })).min(1).max(100)
+});
+const billingAllocationRemoveSchema = scopedSchema.extend({
+  allocationId: z.string().uuid()
+});
+const billingPaymentIdSchema = scopedSchema.extend({
+  paymentId: z.string().uuid()
+});
+const billingPaymentConvertSchema = scopedSchema.extend({
+  paymentId: z.string().uuid(),
+  billAccountId: z.string().uuid()
+});
+const PAYMENT_IMPORT_MAX_BYTES = 2 * 1024 * 1024;
+const PAYMENT_IMPORT_MAX_ROWS = 5e3;
+const billingPaymentImportSchema = scopedSchema.extend({
+  fileName: z.string().trim().min(1).max(255),
+  content: z.string().max(PAYMENT_IMPORT_MAX_BYTES)
+});
+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();
+const billingPaymentImportListQuerySchema = z.object({ ...listPaginationBase, id: z.string().uuid().optional() }).passthrough();
+const MEMO_TYPES = ["credit_memo", "debit_memo"];
+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()
+});
+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(1e3),
+  // 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()
+});
+const billingDraftDeleteSchema = scopedSchema.extend({
+  invoiceId: z.string().uuid()
+});
 export {
+  ALLOCATED_BY,
+  ALLOCATION_SOURCE_TYPES,
   BALANCE_STATUSES,
   BILLING_ITEM_TYPES,
   BILLING_MODES,
@@ -455,9 +678,22 @@ export {
   BILL_RUN_OUTCOME_STATUSES,
   BILL_RUN_STATUSES,
   BILL_RUN_TRIGGERS,
+  CHARGE_TIMINGS,
+  CHARGE_TIMING_RECURRING_ONLY_MESSAGE,
   CREDIT_STATUSES,
+  CUSTOMER_KINDS,
+  DOCUMENT_TYPES,
   DRAFT_INVOICE_EDIT_ACTIONS,
+  GROSS_TIERED_UNSUPPORTED_MESSAGE,
   INVOICE_STATUSES,
+  MEMO_TYPES,
+  PAYMENT_IMPORT_MAX_BYTES,
+  PAYMENT_IMPORT_MAX_ROWS,
+  PAYMENT_MATCH_REASONS,
+  PAYMENT_SOURCES,
+  PAYMENT_STATUSES,
+  PREPAID_TAX_POINTS,
+  PRICE_BASES,
   STATEMENT_STATUSES,
   TOPUP_STATUSES,
   TRANSACTION_TYPES,
@@ -466,18 +702,35 @@ export {
   billingAccountDeleteSchema,
   billingAccountListQuerySchema,
   billingAccountUpdateSchema,
+  billingAllocationRemoveSchema,
+  billingDraftDeleteSchema,
   billingInvoiceAddLineSchema,
   billingInvoiceEditLineSchema,
+  billingInvoiceListQuerySchema,
   billingInvoicePostSchema,
   billingInvoiceRemoveLineSchema,
+  billingInvoiceSendSchema,
   billingItemBulkCreateSchema,
+  billingItemChangePriceSchema,
   billingItemCreateSchema,
   billingItemDeleteSchema,
   billingItemListQuerySchema,
   billingItemUpdateSchema,
+  billingMemoCreateSchema,
+  billingPaymentAllocateSchema,
+  billingPaymentAssignSchema,
+  billingPaymentConvertSchema,
+  billingPaymentCreateSchema,
+  billingPaymentIdSchema,
+  billingPaymentImportListQuerySchema,
+  billingPaymentImportSchema,
+  billingPaymentListQuerySchema,
+  billingRunDeleteSchema,
   billingRunListQuerySchema,
+  billingRunPostDraftsSchema,
   billingRunRetryFailedSchema,
   billingRunTriggerSchema,
+  billingSettingsUpdateSchema,
   billingStatementGenerateSchema,
   billingStatementListQuerySchema,
   billingTopupCreateSchema,
@@ -488,6 +741,7 @@ export {
   billingUsageListQuerySchema,
   billingWipeTestInvoicesSchema,
   invoiceAddressSchema,
+  isTieredRate,
   rateJsonOneTime,
   rateJsonRecurring,
   rateJsonUsage,