@managesome/eposmatic-toolkit 0.4.5 → 0.4.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +33 -0
  2. package/esm/constants/REPORT_CALENDAR.js +47 -0
  3. package/esm/constants/index.js +1 -0
  4. package/esm/helpers/materialized-reports/index.js +2 -0
  5. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +982 -0
  6. package/esm/helpers/materialized-reports/materialized-reports-read-helpers.js +1 -76
  7. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +716 -0
  8. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +327 -41
  9. package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  10. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +118 -235
  11. package/esm/helpers/types/index.js +1 -0
  12. package/esm/schemas/models/index.js +1 -0
  13. package/esm/schemas/models/materialized_credit_bills.js +265 -0
  14. package/esm/schemas/models/materialized_tenant_reports_iterations.js +13 -0
  15. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +39 -97
  16. package/esm/schemas/types/index.js +1 -0
  17. package/esm/schemas/types/materialized_credit_bills.js +1 -0
  18. package/lib/constants/MATERIALIZED_REPORTS.d.ts +28 -2
  19. package/lib/constants/MATERIALIZED_REPORTS.js +34 -1
  20. package/lib/constants/REPORT_CALENDAR.d.ts +31 -0
  21. package/lib/constants/REPORT_CALENDAR.js +50 -0
  22. package/lib/constants/index.d.ts +1 -0
  23. package/lib/constants/index.js +1 -0
  24. package/lib/helpers/materialized-reports/index.d.ts +2 -0
  25. package/lib/helpers/materialized-reports/index.js +2 -0
  26. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +307 -0
  27. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +1003 -0
  28. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.d.ts +0 -30
  29. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.js +0 -76
  30. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +59 -0
  31. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +723 -0
  32. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +66 -8
  33. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +326 -40
  34. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +18 -2
  35. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  36. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +46 -37
  37. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +119 -238
  38. package/lib/helpers/types/index.d.ts +1 -0
  39. package/lib/helpers/types/index.js +1 -0
  40. package/lib/helpers/types/materialized-reports-apis.d.ts +46 -17
  41. package/lib/helpers/types/report-calendar.d.ts +20 -0
  42. package/lib/helpers/types/report-calendar.js +2 -0
  43. package/lib/schemas/models/index.d.ts +1 -0
  44. package/lib/schemas/models/index.js +1 -0
  45. package/lib/schemas/models/materialized_credit_bills.d.ts +337 -0
  46. package/lib/schemas/models/materialized_credit_bills.js +268 -0
  47. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +20 -6
  48. package/lib/schemas/models/materialized_tenant_reports_iterations.js +14 -1
  49. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +37 -165
  50. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +40 -98
  51. package/lib/schemas/types/index.d.ts +1 -0
  52. package/lib/schemas/types/index.js +1 -0
  53. package/lib/schemas/types/materialized_credit_bills.d.ts +139 -0
  54. package/lib/schemas/types/materialized_credit_bills.js +2 -0
  55. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +32 -77
  56. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.d.ts +1 -0
  57. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +715 -0
  58. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.d.ts +1 -0
  59. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +262 -0
  60. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +9 -0
  61. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +23 -24
  62. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +327 -22
  63. package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +27 -2
  64. package/lib/tests/materialized-reports/tenant-sales-overview-formatter.test.js +12 -27
  65. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +79 -146
  66. package/package.json +1 -1
  67. package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.js +0 -100
  68. /package/{lib/tests/materialized-reports/materialized-reports-read-helpers.test.d.ts → esm/helpers/types/report-calendar.js} +0 -0
@@ -93,7 +93,7 @@ const pruneMetricsMap = (keyFilters, metrics, filters) => {
93
93
  }
94
94
  return kept;
95
95
  };
96
- /** Drops non-matching keys from a document's metric map (bills included). */
96
+ /** Drops non-matching keys from a document's metric map (credit counters included). */
97
97
  const pruneReportForFilters = (doc, filters) => {
98
98
  const kept = pruneMetricsMap(doc.sale_type_key_filters ?? [], doc.sale_type_metrics, filters);
99
99
  return { ...doc, sale_type_metrics: kept };
@@ -180,7 +180,12 @@ const buildEmptyPageData = (scopeContext, tenantIds) => ({
180
180
  credit_bills: {
181
181
  issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0 },
182
182
  received: { count: 0, amount: 0 },
183
+ outstanding_count: 0,
183
184
  outstanding_amount: 0,
185
+ outstanding_now_count: 0,
186
+ outstanding_now_amount: 0,
187
+ collected_at_issue_count: 0,
188
+ collected_at_issue_amount: 0,
184
189
  },
185
190
  weekday: scopeContext != null && MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX.includes(scopeContext) ? [] : null,
186
191
  hourly: scopeContext === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR ? [] : null,
@@ -256,6 +261,7 @@ const buildPageDataForDocs = (docs, scopeContext, filters) => {
256
261
  const supportsDayIndex = scopeContext != null && MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX.includes(scopeContext);
257
262
  return buildPageDataFromMetrics(merged, tenantIds, supportsDayIndex ? buildWeekdaySection(scopedDocs, filters) : null, scopeContext === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR ? buildHourlySection(scopedDocs, filters) : null);
258
263
  };
264
+ const creditLedgerCountersOf = (entry) => entry[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS] ?? {};
259
265
  /**
260
266
  * Shared page assembly — identical for the raw read (one merged document) and
261
267
  * the AGGREGATED read (one pipeline record): every section derives from the
@@ -270,7 +276,18 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
270
276
  const cancelledRaw = createRawOrderMetric();
271
277
  const paymentsMap = {};
272
278
  const channelsMap = {};
273
- const issuedRaw = { count: 0, amount: 0, settled_count: 0, settled_amount: 0 };
279
+ const issuedRaw = {
280
+ count: 0,
281
+ amount: 0,
282
+ settled_count: 0,
283
+ settled_amount: 0,
284
+ outstanding_count: 0,
285
+ outstanding_amount: 0,
286
+ outstanding_now_count: 0,
287
+ outstanding_now_amount: 0,
288
+ collected_at_issue_count: 0,
289
+ collected_at_issue_amount: 0,
290
+ };
274
291
  const receivedRaw = { count: 0, amount: 0 };
275
292
  for (const [key, entry] of Object.entries(merged.sale_type_metrics ?? {})) {
276
293
  const components = (0, key_helpers_1.parseMaterializedReportKey)(key);
@@ -278,7 +295,7 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
278
295
  continue;
279
296
  const totalSales = entry[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES];
280
297
  const amountCollected = entry[constants_1.REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED];
281
- const creditBills = entry[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS];
298
+ const creditBills = creditLedgerCountersOf(entry);
282
299
  // Cancelled facet: cancelled orders are materialized under `CANCELLED:*`
283
300
  // keys and excluded from every other facet (payments included).
284
301
  if (isCancelledKey(components, keyFilters)) {
@@ -290,12 +307,30 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
290
307
  for (const payment of totalSales?.payments ?? []) {
291
308
  addRawPayment(paymentsMap, payment);
292
309
  }
293
- issuedRaw.count += creditBills?.issued?.count ?? 0;
294
- issuedRaw.amount += creditBills?.issued?.amount ?? 0;
295
- issuedRaw.settled_count += creditBills?.issued?.settled_count ?? 0;
296
- issuedRaw.settled_amount += creditBills?.issued?.settled_amount ?? 0;
297
- receivedRaw.count += creditBills?.received?.count ?? 0;
298
- receivedRaw.amount += creditBills?.received?.amount ?? 0;
310
+ const issuedCounters = creditBills.issued ?? {};
311
+ const receivedCounters = creditBills.received ?? {};
312
+ // Stored documents carry COUNTERS only (the itemized ledger lives in
313
+ // `materialized_tenant_credit_bills`) — sum them per KEPT key (client-side
314
+ // filters included). Range-pure extras (`outstanding*`,
315
+ // `collected_at_issue_*`) ride only on AGGREGATED records; stored
316
+ // documents fall back to the ever-settled / zero basis (direct-
317
+ // inspection seam only — the aggregation is the canonical read).
318
+ issuedRaw.count += issuedCounters.count ?? 0;
319
+ issuedRaw.amount += issuedCounters.amount ?? 0;
320
+ issuedRaw.settled_count += issuedCounters.settled_count ?? 0;
321
+ issuedRaw.settled_amount += issuedCounters.settled_amount ?? 0;
322
+ const outstandingCountFallback = Math.max(0, (issuedCounters.count ?? 0) - (issuedCounters.settled_count ?? 0));
323
+ const outstandingAmountFallback = Math.max(0, (issuedCounters.amount ?? 0) - (issuedCounters.settled_amount ?? 0));
324
+ issuedRaw.outstanding_count += issuedCounters.outstanding_count ?? outstandingCountFallback;
325
+ issuedRaw.outstanding_amount += issuedCounters.outstanding_amount ?? outstandingAmountFallback;
326
+ issuedRaw.outstanding_now_count +=
327
+ issuedCounters.outstanding_now_count ?? issuedCounters.outstanding_count ?? outstandingCountFallback;
328
+ issuedRaw.outstanding_now_amount +=
329
+ issuedCounters.outstanding_now_amount ?? issuedCounters.outstanding_amount ?? outstandingAmountFallback;
330
+ issuedRaw.collected_at_issue_count += issuedCounters.collected_at_issue_count ?? 0;
331
+ issuedRaw.collected_at_issue_amount += issuedCounters.collected_at_issue_amount ?? 0;
332
+ receivedRaw.count += receivedCounters.count ?? 0;
333
+ receivedRaw.amount += receivedCounters.amount ?? 0;
299
334
  const platform = getKeyDimValue(components, keyFilters, MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM) ?? '';
300
335
  const channel = channelsMap[platform] ?? (channelsMap[platform] = { platform, count: 0, gross_amount: 0 });
301
336
  channel.count += totalSales?.orders?.count ?? 0;
@@ -338,7 +373,12 @@ const buildPageDataFromMetrics = (merged, tenantIds, weekday, hourly) => {
338
373
  settled_amount: toDecimal(issuedRaw.settled_amount),
339
374
  },
340
375
  received: { count: receivedRaw.count, amount: toDecimal(receivedRaw.amount) },
341
- outstanding_amount: toDecimal(issuedRaw.amount - issuedRaw.settled_amount),
376
+ outstanding_count: issuedRaw.outstanding_count,
377
+ outstanding_amount: toDecimal(issuedRaw.outstanding_amount),
378
+ outstanding_now_count: issuedRaw.outstanding_now_count,
379
+ outstanding_now_amount: toDecimal(issuedRaw.outstanding_now_amount),
380
+ collected_at_issue_count: issuedRaw.collected_at_issue_count,
381
+ collected_at_issue_amount: toDecimal(issuedRaw.collected_at_issue_amount),
342
382
  },
343
383
  weekday,
344
384
  hourly,
@@ -411,7 +451,18 @@ const mergeAggregatedKeyMetrics = (reports) => {
411
451
  [TOTAL_SALES]: { orders: createRawOrderMetric(), payments: [] },
412
452
  [AMOUNT_COLLECTED]: { orders: createRawOrderMetric() },
413
453
  [CREDIT_BILLS]: {
414
- issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0 },
454
+ issued: {
455
+ count: 0,
456
+ amount: 0,
457
+ settled_count: 0,
458
+ settled_amount: 0,
459
+ outstanding_count: 0,
460
+ outstanding_amount: 0,
461
+ outstanding_now_count: 0,
462
+ outstanding_now_amount: 0,
463
+ collected_at_issue_count: 0,
464
+ collected_at_issue_amount: 0,
465
+ },
415
466
  received: { count: 0, amount: 0 },
416
467
  },
417
468
  });
@@ -424,6 +475,16 @@ const mergeAggregatedKeyMetrics = (reports) => {
424
475
  entry[CREDIT_BILLS].issued.amount += metrics[CREDIT_BILLS]?.issued?.amount ?? 0;
425
476
  entry[CREDIT_BILLS].issued.settled_count += metrics[CREDIT_BILLS]?.issued?.settled_count ?? 0;
426
477
  entry[CREDIT_BILLS].issued.settled_amount += metrics[CREDIT_BILLS]?.issued?.settled_amount ?? 0;
478
+ entry[CREDIT_BILLS].issued.outstanding_count += metrics[CREDIT_BILLS]?.issued?.outstanding_count ?? 0;
479
+ entry[CREDIT_BILLS].issued.outstanding_amount += metrics[CREDIT_BILLS]?.issued?.outstanding_amount ?? 0;
480
+ entry[CREDIT_BILLS].issued.outstanding_now_count += metrics[CREDIT_BILLS]?.issued?.outstanding_now_count ?? 0;
481
+ entry[CREDIT_BILLS].issued.outstanding_now_amount += metrics[CREDIT_BILLS]?.issued?.outstanding_now_amount ?? 0;
482
+ // At-issue money rides as a COUNTER on aggregated records (derived from
483
+ // the ledger rows server-side); stored documents degrade to 0.
484
+ entry[CREDIT_BILLS].issued.collected_at_issue_count +=
485
+ metrics[CREDIT_BILLS]?.issued?.collected_at_issue_count ?? 0;
486
+ entry[CREDIT_BILLS].issued.collected_at_issue_amount +=
487
+ metrics[CREDIT_BILLS]?.issued?.collected_at_issue_amount ?? 0;
427
488
  entry[CREDIT_BILLS].received.count += metrics[CREDIT_BILLS]?.received?.count ?? 0;
428
489
  entry[CREDIT_BILLS].received.amount += metrics[CREDIT_BILLS]?.received?.amount ?? 0;
429
490
  }
@@ -1,6 +1,7 @@
1
1
  import mongoose from 'mongoose';
2
2
  import { IOrder, IOrderPayment } from '../../schemas';
3
- import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, IMaterializedTenantSalesOverviewReport } from '../../schemas/types/materialized_tenant_sales_overview_reports';
3
+ import { IMaterializedReportKeyMetrics, IMaterializedTenantSalesOverviewReport } from '../../schemas/types/materialized_tenant_sales_overview_reports';
4
+ import { ICreditBillEventCandidate, ICreditBillIssuedCandidate, isMaterializedCreditBillPayment } from './materialized-credit-bills-helpers';
4
5
  /**
5
6
  * Backend materialization helpers for `materialized_tenant_sales_overview_reports`
6
7
  * (see `MATERIALIZED_REPORTS.md` "Backend materialization cycle").
@@ -9,11 +10,14 @@ import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, I
9
10
  *
10
11
  * 1. **JSON building** — `convertOrdersToMaterializedTenantSalesOverviewReports`
11
12
  * compiles one tenant-day of raw orders into plain-JSON scope documents
12
- * (24h-hour + period scopes) plus the credit bills collected that day.
13
+ * (24h-hour + period scopes) plus the credit-bill ledger CANDIDATES
14
+ * collected that day (`credit_bill_issues` + `credit_bill_events` — the
15
+ * close-day plan resolves them and materializes both the report counters
16
+ * and `materialized_tenant_credit_bills` from that ONE resolution).
13
17
  * `sumMaterializedTenantSalesOverviewReports` accumulates those into
14
18
  * longer-period documents (week → year) and
15
19
  * `updateMaterializedTenantSalesOverviewReport` patches an existing document
16
- * (delta amounts / credit-bill receipt tracking).
20
+ * (delta amounts).
17
21
  * 2. **Persistence** — `convertMaterializedTenantSalesOverviewReportJsonToBson`
18
22
  * casts a JSON document through the mongoose schema so the job can upsert it.
19
23
  *
@@ -24,7 +28,7 @@ import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, I
24
28
  * - orders are attributed to the tenant-local BUSINESS day held by
25
29
  * `order.localDate` (falls back to the `localDate` argument when absent);
26
30
  * orders whose business day differs from the day being compiled only
27
- * produce `received_payments` (credit-bill collections), never sales;
31
+ * produce `credit_bill_events` (credit-bill collections), never sales;
28
32
  * - hour buckets: SALES orders use the punch hour (`order.localHour` →
29
33
  * `gmtOffset` → `order_settled_at_mins ÷ 60`); credit-bill COLLECTION
30
34
  * events use the SETTLEMENT hour (`gmtOffset` + `order_settled_at` →
@@ -33,13 +37,14 @@ import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, I
33
37
  * - INPUT CONTRACT: pass plain JSON documents (`.lean()` recommended). A
34
38
  * hydrated document's map-cast `sale_type_metrics` is normalized
35
39
  * defensively, but its other mongoose internals are not supported;
36
- * - `CREDIT_BILLS` ledger: `issued.bills[].received_amount` and
37
- * `received.bills[].received_amount` are CUMULATIVE "received so far" values
38
- * (never event deltas) — a bill is settled when `received_amount >= amount`
39
- * (the patch stamps `settled_at` with the received entry's true collection
40
- * timestamp, falling back to `computedAt`); patches are absolute and
41
- * idempotent, and a patch that CHANGES the ledger is a versioned write
42
- * (bumps `iteration`);
40
+ * - credit bills (`PAY_LATER`): these documents store COUNTERS ONLY (the
41
+ * `issued` / `settled` / `received` numbers — constant size, no bill rows
42
+ * or ids). The ITEMIZED ledger lives in the SHARED
43
+ * `materialized_tenant_credit_bills` collection: the compile emits
44
+ * `credit_bill_issues` (issue candidates) + `credit_bill_events`
45
+ * (collection candidates) for the close-day plan to resolve — the plan then
46
+ * materializes the credit documents and patches the issue-day documents'
47
+ * SETTLED counters from the same resolution;
43
48
  * - cancelled orders are materialized fully under their `CANCELLED:*` keys —
44
49
  * the read layer excludes them for TOTAL_SALES parity and derives the
45
50
  * Cancelled facet from those keys;
@@ -77,7 +82,10 @@ export interface IConvertOrdersToMaterializedReportsOptions {
77
82
  /** Result of a tenant-day compile. */
78
83
  export interface IConvertOrdersToMaterializedReportsResult {
79
84
  materializedReports: IMaterializedTenantSalesOverviewReport[];
80
- received_payments: IMaterializedReportReceivedCreditBill[];
85
+ /** Issue candidates for `materialized_tenant_credit_bills` (resolved by the close plan). */
86
+ credit_bill_issues: ICreditBillIssuedCandidate[];
87
+ /** Receipt-event candidates for `materialized_tenant_credit_bills` (resolved by the close plan). */
88
+ credit_bill_events: ICreditBillEventCandidate[];
81
89
  }
82
90
  /** `PAY_LATER` is reported as `UNPAID` (live-aggregation behavior). */
83
91
  export declare function normalizeMaterializedPaymentType(paymentType: string): string;
@@ -94,8 +102,7 @@ export declare function isPaymentIncludedInMaterializedSalesOverview(payment: IO
94
102
  * - refunded: negative — `-amount_due` for UNPAID, else `-amount_refunded`.
95
103
  */
96
104
  export declare function getMaterializedPaymentGross(payment: IOrderPayment): number;
97
- /** Whether a payment row represents a credit bill (`PAY_LATER`). */
98
- export declare function isMaterializedCreditBillPayment(payment: IOrderPayment): boolean;
105
+ export { isMaterializedCreditBillPayment };
99
106
  /**
100
107
  * Plain-record view of a report's `sale_type_metrics`. The schema stores the
101
108
  * map as a mongoose `Map` of subdocuments, so a hydrated document
@@ -142,10 +149,9 @@ export declare function convertMaterializedTenantSalesOverviewReportJsonToBson(r
142
149
  * the period document (month / quarter / year …) FIRST so the result keeps its
143
150
  * identity while day documents are accumulated into it.
144
151
  *
145
- * Metric trees are summed per key; credit-bill bills are concatenated and
146
- * de-duplicated by `(order_id, payment_id)` keeping the most-collected state,
147
- * then all ledger counters are recomputed from the itemized bills — so
148
- * overlapping compiles never double-count.
152
+ * Metric trees are summed per key — including the credit-bill COUNTERS
153
+ * (`issued` / `settled` / `received` numbers; the itemized ledger lives in
154
+ * `materialized_tenant_credit_bills` and is not part of these documents).
149
155
  *
150
156
  * Returns `null` (never throws) when the inputs cannot be summed — empty list
151
157
  * or mismatched tenant / brand / schema version / key filters. `null` means a
@@ -164,8 +170,9 @@ export declare function sumMaterializedTenantSalesOverviewReports(reports: IMate
164
170
  * the stored `localDate` doc of day D IS the delta previously folded into the
165
171
  * period docs.
166
172
  *
167
- * Bills are removed by `(order_id, payment_id)`; ledger counters are recomputed
168
- * from the remaining bills. Returns `null` (never throws) on mismatched inputs.
173
+ * Credit-bill counters are subtracted numerically (numbers only — these
174
+ * documents carry no bill rows). Returns `null` (never throws) on mismatched
175
+ * inputs.
169
176
  */
170
177
  export declare function subtractMaterializedTenantSalesOverviewReports(minuend: IMaterializedTenantSalesOverviewReport, subtrahend: IMaterializedTenantSalesOverviewReport): IMaterializedTenantSalesOverviewReport | null;
171
178
  /** Update descriptor of `updateMaterializedTenantSalesOverviewReport`. */
@@ -188,16 +195,18 @@ export interface IUpdateMaterializedTenantSalesOverviewReportInput {
188
195
  */
189
196
  additions?: IMaterializedTenantSalesOverviewReport[];
190
197
  /**
191
- * Credit-bill collection events (`received_payments` of a day compile) used
192
- * to patch the document's `issued` ledger — applies to the ISSUE-day
193
- * documents: `received_amount` is set to the cumulative received value;
194
- * `credit_note` and `settled_at` (the received entry's collection timestamp,
195
- * falling back to `computedAt`) are recorded when full collection is
196
- * reached. Absolute values keep replays idempotent; a patch that changes
197
- * the ledger is a versioned write (bumps `iteration` — append its history
198
- * row), a no-op patch bumps nothing.
198
+ * Credit-bill SETTLEMENT counter patches (numbers only — the itemized
199
+ * ledger lives in `materialized_tenant_credit_bills`): for every entry whose key
200
+ * exists on this document, `issued.settled_count` increases by 1 and
201
+ * `issued.settled_amount` by `amount` — the close-day plan emits an entry
202
+ * ONLY on the stored ledger's unsettled→settled transition, so replays
203
+ * emit nothing and the patch stays idempotent. A changing patch is a
204
+ * versioned write (bumps `iteration` — append its history row).
199
205
  */
200
- received_payments?: IMaterializedReportReceivedCreditBill[];
206
+ settled_credit_bills?: {
207
+ key: string;
208
+ amount: number;
209
+ }[];
201
210
  }
202
211
  /**
203
212
  * Versioned write on an existing JSON report (never throws; `null` on
@@ -206,15 +215,15 @@ export interface IUpdateMaterializedTenantSalesOverviewReportInput {
206
215
  * 1. metrics: `replacement` swaps the tree wholesale (day/hour docs);
207
216
  * otherwise `subtract` first (previously applied deltas), then `additions`
208
217
  * (newly calculated ones) — the reconcile/retry pattern;
209
- * 2. `received_payments` patches matching `issued` bills (`received_amount`
210
- * cumulative, `credit_note`, `settled_at` — the received entry's true
211
- * collection timestamp, falling back to `computedAt`, stamped when
212
- * `received_amount >= amount`);
218
+ * 2. `settled_credit_bills` patches the SETTLED counters of matching keys
219
+ * (`settled_count` +1 / `settled_amount` + `amount` — counters only, the
220
+ * itemized ledger lives in `materialized_tenant_credit_bills`);
213
221
  * 3. versioning: metric writes (`replacement` / `subtract` / `additions`) AND
214
- * received-payment patches that change the ledger bump `iteration` — the
215
- * returned document is recorded as a `materialized_tenant_reports_iterations`
216
- * row by the caller (`buildMaterializedTenantReportIteration`); no-op
217
- * patches bump nothing, so replays stay churn-free;
222
+ * settlement counter patches that change the counters bump `iteration` —
223
+ * the returned document is recorded as a
224
+ * `materialized_tenant_reports_iterations` row by the caller
225
+ * (`buildMaterializedTenantReportIteration`); no-op patches bump nothing,
226
+ * so replays stay churn-free;
218
227
  * 4. `source_watermark` advances to the max of the existing and the incoming
219
228
  * (`replacement` / `additions`) watermarks — monotonic, never regressed
220
229
  * (rollbacks / replays keep the previously folded maximum).