@dainamite/billing 0.20.0 → 0.22.0

package/dist/modules/billing/lib/prepaidPeriodClose.js

@@ -4,203 +4,292 @@ import {
   BillingItem,
   BillingStatement
 } from "../data/entities.js";
-import { advanceNextBillDate, addDays, deriveBillPeriod, isCycleDue } from "./billPeriod.js";
+import {
+  addDays,
+  advanceNextBillDate,
+  deriveBillPeriod,
+  isCycleDue,
+  shiftCycles
+} from "./billPeriod.js";
 import { applyBalanceMovement } from "./balanceLedger.js";
 import { resolveLowBalanceThreshold } from "./balanceStatus.js";
-import { buildInvoiceLinesFromItems } from "./invoiceWriter.js";
-import { selectItemsForPeriod } from "./itemSelector.js";
+import {
+  buildInvoiceLinesFromItems,
+  buildRecurringLineDescriptors
+} from "./invoiceWriter.js";
+import { shouldIncludeItem } from "./itemSelector.js";
+import { computeRecurringLines } from "./servicePeriods.js";
 import { absMoney, addMoney, fromUnits, subMoney, toUnits } from "./money.js";
 import {
   getLowBalanceThresholdDefault,
   getNearLimitBufferDefault,
+  getPrepaidTaxPoint,
   getStatementEnabled
 } from "./prepaidConfig.js";
+import {
+  buildVatSummary,
+  resolvePrepaidDebit
+} from "./prepaidTaxPoint.js";
 import { buildBalanceCrossingEvents } from "./balanceEvents.js";
-const SCHEDULED_CYCLE_LIMIT = 1;
+import { toIsoDate, toUtcMidnight } from "./dateOnly.js";
 const CATCH_UP_HARD_CAP = 60;
+const SKIPPED_ITEMS_WARNING_CAP = 200;
+const QUIET_SKIP_REASONS = /* @__PURE__ */ new Set(["item-inactive", "item-soft-deleted"]);
+function chargeSourceRef(line, kind) {
+  if (line.billingType === "one_time") return `one_time-${line.billingItemId}`;
+  const start = line.servicePeriodStart ? toIsoDate(line.servicePeriodStart) : "na";
+  const end = line.servicePeriodEnd ? toIsoDate(line.servicePeriodEnd) : "na";
+  return `recurring-${line.billingItemId}-${kind}-${start}-${end}`;
+}
+function money4(value) {
+  return fromUnits(Math.round(value * 1e4));
+}
+function toSkipWarning(skip) {
+  return {
+    item_id: skip.billingItemId,
+    reason: skip.reason,
+    service_period_start: skip.servicePeriodStart ? toIsoDate(skip.servicePeriodStart) : null,
+    service_period_end: skip.servicePeriodEnd ? toIsoDate(skip.servicePeriodEnd) : null
+  };
+}
+function toCharge(descriptor, kind, taxPoint) {
+  return {
+    descriptor,
+    amounts: resolvePrepaidDebit({
+      lineAmount: descriptor.lineAmount,
+      priceBasis: descriptor.priceBasis,
+      taxRate: descriptor.taxRate,
+      taxPoint
+    }),
+    sourceRef: chargeSourceRef(descriptor, kind)
+  };
+}
 async function processPrepaidAccount(em, account, billRun, params) {
-  const maxCycles = params.triggeredBy === "schedule" || !params.catchUp ? SCHEDULED_CYCLE_LIMIT : CATCH_UP_HARD_CAP;
-  const statementEnabled = await getStatementEnabled(em);
+  const scope = { tenantId: account.tenantId, organizationId: account.organizationId };
+  const cycle = account.billCycle;
   const balanceRow = await em.findOne(BillingAccountBalance, {
     tenantId: account.tenantId,
     billAccountId: account.id
   });
-  const threshold = resolveLowBalanceThreshold(
-    balanceRow?.lowBalanceThreshold ?? null,
-    await getLowBalanceThresholdDefault(em)
+  const ctx = {
+    mode: params.mode,
+    taxPoint: await getPrepaidTaxPoint(em, scope),
+    statementEnabled: await getStatementEnabled(em, scope),
+    threshold: resolveLowBalanceThreshold(
+      balanceRow?.lowBalanceThreshold ?? null,
+      await getLowBalanceThresholdDefault(em, scope)
+    ),
+    nearLimitBuffer: await getNearLimitBufferDefault(em, scope),
+    creditLimit: account.creditLimit ?? "0"
+  };
+  const items = await em.find(BillingItem, {
+    tenantId: account.tenantId,
+    organizationId: account.organizationId,
+    billAccountId: account.id,
+    deletedAt: null
+  });
+  const recurringItems = items.filter((it) => it.type === "recurring");
+  const oneTimeItems = items.filter((it) => it.type === "one_time");
+  const watermarks = new Map(
+    recurringItems.map((it) => [it.id, it.billedToDate ? toUtcMidnight(it.billedToDate) : null])
   );
-  const nearLimitBuffer = await getNearLimitBufferDefault(em);
-  const creditLimit = account.creditLimit ?? "0";
-  let cyclesEmitted = 0;
-  let lastStatementId = null;
-  const statementEvents = [];
+  const billedOneTimes = new Set(oneTimeItems.filter((it) => it.billedToDate).map((it) => it.id));
+  let billDate = toUtcMidnight(account.nextBillDate);
   let previousClosing = null;
-  while (cyclesEmitted < maxCycles && isCycleDue(account.nextBillDate, params.asOfDate)) {
-    const period = deriveBillPeriod(account.nextBillDate, account.billCycle);
-    if (params.mode !== "dry") {
-      const existing = await em.findOne(BillingStatement, {
-        tenantId: account.tenantId,
-        billAccountId: account.id,
-        periodStart: period.periodStart,
-        periodEnd: period.periodEnd
-      });
-      if (existing) {
-        return {
-          status: "skipped_existing_statement",
-          warnings: null,
-          statementId: existing.id,
-          cyclesEmitted,
-          statementEvents
-        };
-      }
+  const cycles = [];
+  const skippedItems = [];
+  const warnings = {};
+  const statementEvents = [];
+  let lastStatementId = null;
+  const pushSkips = (skips) => {
+    for (const skip of skips) {
+      if (QUIET_SKIP_REASONS.has(skip.reason)) continue;
+      if (skippedItems.length < SKIPPED_ITEMS_WARNING_CAP) skippedItems.push(toSkipWarning(skip));
     }
-    const cycle = await closePrepaidPeriod(em, account, period, billRun, {
-      mode: params.mode,
-      statementEnabled,
-      previousClosing,
-      threshold,
-      nearLimitBuffer,
-      creditLimit
-    });
-    previousClosing = cycle.closingBalance;
-    statementEvents.push(...cycle.crossingEvents);
-    if (cycle.statementId) {
-      lastStatementId = cycle.statementId;
-      statementEvents.push({
-        id: "billing.statement.generated",
-        payload: {
-          statementId: cycle.statementId,
-          billAccountId: account.id,
-          tenantId: account.tenantId,
-          organizationId: account.organizationId,
-          billRunId: billRun.id,
-          periodStart: period.periodStart.toISOString().slice(0, 10),
-          periodEnd: period.periodEnd.toISOString().slice(0, 10),
-          currencyCode: account.currencyCode,
-          openingBalance: cycle.openingBalance,
-          closingBalance: cycle.closingBalance,
-          totalTopups: cycle.totalTopups,
-          totalUsage: cycle.totalUsage,
-          totalRecurring: cycle.totalRecurring,
-          totalAdjustments: cycle.totalAdjustments
-        }
+  };
+  while (isCycleDue(billDate, params.asOfDate)) {
+    if (cycles.length >= CATCH_UP_HARD_CAP) {
+      warnings.catch_up_cap_reached = true;
+      break;
+    }
+    const nextBillDate = advanceNextBillDate(billDate, cycle);
+    const period = deriveBillPeriod(billDate, cycle);
+    const charges = [];
+    const watermarkUpdates = /* @__PURE__ */ new Map();
+    for (const item of recurringItems) {
+      const unitPrice = item.rateJson?.unit_price;
+      if (typeof unitPrice !== "number") continue;
+      const computed = computeRecurringLines(
+        {
+          id: item.id,
+          chargeTiming: item.chargeTiming ?? "in_advance",
+          prorate: item.prorate ?? true,
+          billStartDate: item.billStartDate,
+          billEndDate: item.billEndDate ?? null,
+          billedToDate: watermarks.get(item.id) ?? null,
+          unitPrice,
+          isActive: item.isActive,
+          deletedAt: item.deletedAt ?? null
+        },
+        { billDate, cycle }
+      );
+      pushSkips(computed.skipped);
+      if (computed.newBilledToDate?.getTime() !== watermarks.get(item.id)?.getTime()) {
+        watermarkUpdates.set(item.id, computed.newBilledToDate);
+      }
+      const descriptors = buildRecurringLineDescriptors(item, computed.lines);
+      descriptors.forEach((descriptor, index) => {
+        charges.push(toCharge(descriptor, computed.lines[index]?.kind ?? "charge", ctx.taxPoint));
       });
     }
+    const oneTimeWindow = {
+      periodStart: shiftCycles(billDate, cycle, -1),
+      periodEnd: addDays(nextBillDate, -1)
+    };
+    const oneTimesThisCycle = oneTimeItems.filter(
+      (it) => !billedOneTimes.has(it.id) && shouldIncludeItem(it, oneTimeWindow).include
+    );
+    for (const descriptor of buildInvoiceLinesFromItems(oneTimesThisCycle)) {
+      charges.push(toCharge(descriptor, "charge", ctx.taxPoint));
+    }
+    const closed = await closePrepaidPeriod(em, account, billRun, { billDate, period, charges, previousClosing }, ctx);
+    previousClosing = closed.closingBalance;
+    statementEvents.push(...closed.events);
+    if (closed.statementId) lastStatementId = closed.statementId;
+    cycles.push(closed.record);
+    for (const [itemId, watermark] of watermarkUpdates) watermarks.set(itemId, watermark);
+    for (const item of oneTimesThisCycle) billedOneTimes.add(item.id);
     if (params.mode === "real") {
-      account.nextBillDate = advanceNextBillDate(
-        account.nextBillDate,
-        account.billCycle
-      );
+      const now = /* @__PURE__ */ new Date();
+      for (const item of recurringItems) {
+        if (!watermarkUpdates.has(item.id)) continue;
+        item.billedToDate = watermarkUpdates.get(item.id) ?? null;
+        item.updatedAt = now;
+      }
+      for (const item of oneTimesThisCycle) {
+        item.billedToDate = period.periodEnd;
+        item.updatedAt = now;
+      }
+      account.nextBillDate = nextBillDate;
       account.lastBillDate = period.periodEnd;
-      account.updatedAt = /* @__PURE__ */ new Date();
+      account.updatedAt = now;
       await em.flush();
-    } else {
-      cyclesEmitted += 1;
-      break;
     }
-    cyclesEmitted += 1;
+    billDate = nextBillDate;
   }
+  const finalWarnings = {
+    ...warnings,
+    ...skippedItems.length ? { skipped_items: skippedItems } : {}
+  };
   return {
-    status: "success",
-    warnings: null,
+    status: warnings.catch_up_cap_reached ? "success_with_warnings" : "success",
+    warnings: Object.keys(finalWarnings).length ? finalWarnings : null,
     statementId: lastStatementId,
-    cyclesEmitted,
+    cyclesEmitted: cycles.filter((c) => c.status === "charged" || c.status === "previewed").length,
+    cycles,
     statementEvents
   };
 }
-async function closePrepaidPeriod(em, account, period, billRun, opts) {
-  const periodEndISO = period.periodEnd.toISOString().slice(0, 10);
-  const items = await em.find(BillingItem, {
+async function closePrepaidPeriod(em, account, billRun, input, ctx) {
+  const { period, charges } = input;
+  const periodStartIso = toIsoDate(period.periodStart);
+  const periodEndIso = toIsoDate(period.periodEnd);
+  const existingStatement = ctx.mode === "real" ? await em.findOne(BillingStatement, {
     tenantId: account.tenantId,
-    organizationId: account.organizationId,
     billAccountId: account.id,
-    deletedAt: null
-  });
-  const { included } = selectItemsForPeriod(items, period);
-  const billableItems = included;
-  const lines = buildInvoiceLinesFromItems(billableItems);
-  const windowStart = period.periodStart;
-  const windowEnd = addDays(period.periodEnd, 1);
-  const openingBalance = await resolveOpeningBalance(em, account, period, opts.previousClosing);
+    periodStart: periodStartIso,
+    periodEnd: periodEndIso
+  }) : null;
+  const windowStart = addDays(period.periodStart, 1);
+  const windowEnd = addDays(input.billDate, 1);
+  const openingBalance = await resolveOpeningBalance(em, account, windowStart, period, input.previousClosing);
   const totalTopups = await sumByTypeInWindow(em, account, "topup", windowStart, windowEnd);
-  const totalUsage = absMoney(
-    await sumByTypeInWindow(em, account, "usage", windowStart, windowEnd)
-  );
+  const totalUsage = absMoney(await sumByTypeInWindow(em, account, "usage", windowStart, windowEnd));
   const totalAdjustments = addMoney(
     await sumByTypeInWindow(em, account, "adjustment", windowStart, windowEnd),
     await sumByTypeInWindow(em, account, "reversal", windowStart, windowEnd)
   );
   let totalRecurring = "0.0000";
+  let totalNet = "0.0000";
   const breakdown = [];
   const chargeTransactionIds = [];
-  let recurringBalanceBefore = null;
-  let recurringBalanceAfter = null;
-  if (opts.mode === "real") {
-    const now = /* @__PURE__ */ new Date();
-    for (const line of lines) {
-      const movement = await applyBalanceMovement(em, {
-        organizationId: account.organizationId,
-        tenantId: account.tenantId,
-        billAccountId: account.id,
-        currencyCode: account.currencyCode,
-        type: line.billingType === "one_time" ? "one_time" : "recurring",
-        amount: fromUnits(-toUnits(line.totalNetAmount)),
-        description: line.description,
-        billingItemId: line.billingItemId,
-        sourceRef: `recurring-${line.billingItemId}-${periodEndISO}`,
-        metadata: {
-          bill_period_start: period.periodStart.toISOString().slice(0, 10),
-          bill_period_end: periodEndISO,
-          bill_run_id: billRun.id
-        }
-      });
-      if (recurringBalanceBefore === null) recurringBalanceBefore = movement.balanceBefore;
-      recurringBalanceAfter = movement.balanceAfter;
-      totalRecurring = addMoney(totalRecurring, line.totalNetAmount);
-      if (!movement.deduplicated) chargeTransactionIds.push(movement.transaction.id);
-      breakdown.push({
-        billing_item_id: line.billingItemId,
-        billing_type: line.billingType,
-        quantity: line.quantity,
-        amount: line.totalNetAmount
-      });
-      const item = billableItems.find((it) => it.id === line.billingItemId);
-      if (item) {
-        item.billedToDate = period.periodEnd;
-        item.updatedAt = now;
-      }
-    }
-    await em.flush();
-  } else {
-    for (const line of lines) {
-      totalRecurring = addMoney(totalRecurring, line.totalNetAmount);
-      breakdown.push({
-        billing_item_id: line.billingItemId,
-        billing_type: line.billingType,
-        quantity: line.quantity,
-        amount: line.totalNetAmount
-      });
-    }
+  let balanceBefore = null;
+  let balanceAfter = null;
+  for (const charge of charges) {
+    const { descriptor, amounts } = charge;
+    const debit = money4(amounts.debit);
+    totalRecurring = addMoney(totalRecurring, debit);
+    totalNet = addMoney(totalNet, money4(amounts.net));
+    const metadata = {
+      bill_date: toIsoDate(input.billDate),
+      bill_period_start: periodStartIso,
+      bill_period_end: periodEndIso,
+      bill_run_id: billRun.id,
+      service_period_start: descriptor.servicePeriodStart ? toIsoDate(descriptor.servicePeriodStart) : null,
+      service_period_end: descriptor.servicePeriodEnd ? toIsoDate(descriptor.servicePeriodEnd) : null,
+      net: money4(amounts.net),
+      tax: money4(amounts.tax),
+      tax_rate: String(amounts.taxRate),
+      tax_point: ctx.taxPoint,
+      ...descriptor.metadataExtra ?? {}
+    };
+    breakdown.push({
+      billing_item_id: descriptor.billingItemId,
+      billing_type: descriptor.billingType,
+      description: descriptor.description,
+      quantity: descriptor.quantity,
+      amount: debit,
+      net: metadata.net,
+      tax: metadata.tax,
+      tax_rate: metadata.tax_rate,
+      service_period_start: metadata.service_period_start,
+      service_period_end: metadata.service_period_end,
+      proration: descriptor.metadataExtra?.proration ?? null
+    });
+    if (ctx.mode !== "real") continue;
+    const movement = await applyBalanceMovement(em, {
+      organizationId: account.organizationId,
+      tenantId: account.tenantId,
+      billAccountId: account.id,
+      currencyCode: account.currencyCode,
+      // Credits back (an item ended inside a charged period) stay typed as the
+      // charge they reverse: adjustments are summed by date window on
+      // statements and would be counted twice.
+      type: descriptor.billingType === "one_time" ? "one_time" : "recurring",
+      amount: fromUnits(-toUnits(debit)),
+      description: descriptor.description,
+      billingItemId: descriptor.billingItemId,
+      sourceRef: charge.sourceRef,
+      metadata
+    });
+    if (balanceBefore === null) balanceBefore = movement.balanceBefore;
+    balanceAfter = movement.balanceAfter;
+    if (!movement.deduplicated) chargeTransactionIds.push(movement.transaction.id);
   }
+  if (ctx.mode === "real" && charges.length > 0) await em.flush();
   const closingBalance = subMoney(
     subMoney(addMoney(addMoney(openingBalance, totalTopups), totalAdjustments), totalUsage),
     totalRecurring
   );
-  const crossingEvents = recurringBalanceBefore !== null && recurringBalanceAfter !== null ? buildBalanceCrossingEvents({
+  const vatSummary = buildVatSummary(
+    charges.map((c) => c.amounts),
+    ctx.taxPoint
+  );
+  const events = balanceBefore !== null && balanceAfter !== null ? buildBalanceCrossingEvents({
     scope: {
       billAccountId: account.id,
       tenantId: account.tenantId,
       organizationId: account.organizationId,
       currencyCode: account.currencyCode
     },
-    balanceBefore: recurringBalanceBefore,
-    balanceAfter: recurringBalanceAfter,
-    threshold: opts.threshold,
-    creditLimit: opts.creditLimit,
-    nearLimitBuffer: opts.nearLimitBuffer
+    balanceBefore,
+    balanceAfter,
+    threshold: ctx.threshold,
+    creditLimit: ctx.creditLimit,
+    nearLimitBuffer: ctx.nearLimitBuffer
   }) : [];
-  let statementId = null;
-  if (opts.mode === "real" && opts.statementEnabled) {
+  let createdStatementId = null;
+  if (ctx.mode === "real" && ctx.statementEnabled && !existingStatement) {
     const now = /* @__PURE__ */ new Date();
     const statement = em.create(BillingStatement, {
       organizationId: account.organizationId,
@@ -216,34 +305,64 @@ async function closePrepaidPeriod(em, account, period, billRun, opts) {
       totalRecurring,
       totalAdjustments,
       closingBalance,
-      debitBreakdown: { items: breakdown },
+      debitBreakdown: { items: breakdown, bill_date: toIsoDate(input.billDate), tax_point: ctx.taxPoint },
+      vatSummary,
       status: "generated",
       createdAt: now,
       updatedAt: now
     });
     em.persist(statement);
     await em.flush();
-    statementId = statement.id;
+    createdStatementId = statement.id;
     if (chargeTransactionIds.length > 0) {
       await em.nativeUpdate(
         BillingAccountTransaction,
         { id: { $in: chargeTransactionIds } },
-        { statementId }
+        { statementId: createdStatementId }
       );
     }
+    events.push({
+      id: "billing.statement.generated",
+      payload: {
+        statementId: createdStatementId,
+        billAccountId: account.id,
+        tenantId: account.tenantId,
+        organizationId: account.organizationId,
+        billRunId: billRun.id,
+        periodStart: periodStartIso,
+        periodEnd: periodEndIso,
+        currencyCode: account.currencyCode,
+        openingBalance,
+        closingBalance,
+        totalTopups,
+        totalUsage,
+        totalRecurring,
+        totalAdjustments
+      }
+    });
   }
+  let status;
+  if (ctx.mode !== "real") status = charges.length > 0 ? "previewed" : "empty";
+  else if (existingStatement && chargeTransactionIds.length === 0) status = "skipped_existing";
+  else status = chargeTransactionIds.length > 0 ? "charged" : "empty";
   return {
-    statementId,
-    openingBalance,
-    totalTopups,
-    totalUsage,
-    totalRecurring,
-    totalAdjustments,
+    record: {
+      bill_date: toIsoDate(input.billDate),
+      period_start: periodStartIso,
+      period_end: periodEndIso,
+      status,
+      line_count: charges.length,
+      total_net: totalNet,
+      total_debit: totalRecurring,
+      invoice_id: null,
+      statement_id: createdStatementId ?? existingStatement?.id ?? null
+    },
+    statementId: createdStatementId,
     closingBalance,
-    crossingEvents
+    events
   };
 }
-async function resolveOpeningBalance(em, account, period, previousClosing) {
+async function resolveOpeningBalance(em, account, windowStart, period, previousClosing) {
   if (previousClosing !== null) return previousClosing;
   const prior = await em.findOne(
     BillingStatement,
@@ -251,12 +370,12 @@ async function resolveOpeningBalance(em, account, period, previousClosing) {
       tenantId: account.tenantId,
       organizationId: account.organizationId,
       billAccountId: account.id,
-      periodEnd: { $lt: period.periodStart }
+      periodEnd: { $lt: toIsoDate(period.periodStart) }
     },
     { orderBy: { periodEnd: "DESC" } }
   );
   if (prior) return fromUnits(toUnits(prior.closingBalance));
-  return sumAmountsBefore(em, account, period.periodStart);
+  return sumAmountsBefore(em, account, windowStart);
 }
 async function sumAmountsBefore(em, account, before) {
   const rows = await em.execute(