@managesome/eposmatic-toolkit 0.3.10 → 0.4.0

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 (145) hide show
  1. package/esm/constants/ENUMS.js +17 -1988
  2. package/esm/constants/MATERIALIZED_REPORTS.js +105 -0
  3. package/esm/constants/enums/cash.js +45 -0
  4. package/esm/constants/enums/communications.js +329 -0
  5. package/esm/constants/enums/delivery.js +35 -0
  6. package/esm/constants/enums/geo.js +150 -0
  7. package/esm/constants/enums/hr.js +130 -0
  8. package/esm/constants/enums/internal.js +132 -0
  9. package/esm/constants/enums/items.js +126 -0
  10. package/esm/constants/enums/misc.js +35 -0
  11. package/esm/constants/enums/offers.js +102 -0
  12. package/esm/constants/enums/order.js +135 -0
  13. package/esm/constants/enums/payments.js +186 -0
  14. package/esm/constants/enums/platform.js +215 -0
  15. package/esm/constants/enums/printing.js +107 -0
  16. package/esm/constants/enums/users.js +245 -0
  17. package/esm/constants/enums/wallet.js +32 -0
  18. package/esm/helpers/materialized-reports/index.js +5 -0
  19. package/esm/helpers/materialized-reports/key-helpers.js +59 -0
  20. package/esm/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +60 -0
  21. package/esm/helpers/materialized-reports/scope-helpers.js +107 -0
  22. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +251 -0
  23. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +860 -0
  24. package/esm/helpers/store/cart-actions.js +1 -1
  25. package/esm/helpers/store/common-tenant-purchase-order-actions.js +7 -7
  26. package/esm/helpers/store/common-warehouse-purchase-order-actions.js +1 -1
  27. package/esm/helpers/store/common-warehouse-purchase-order-rfq-actions.js +1 -1
  28. package/esm/helpers/store/common-warehouse-sale-order-actions.js +1 -1
  29. package/esm/helpers/store/common-warehouse-sale-order-rfq-actions.js +1 -1
  30. package/esm/helpers/store/offline-ordering.js +1 -1
  31. package/esm/helpers/store/tenant-purchase-orders-cart-actions.js +1 -1
  32. package/esm/helpers/store/warehouse-purchase-order-rfq-cart-actions.js +1 -1
  33. package/esm/helpers/store/warehouse-purchase-orders-cart-actions.js +1 -1
  34. package/esm/helpers/store/warehouse-sale-order-rfq-cart-actions.js +1 -1
  35. package/esm/helpers/store/warehouse-sale-orders-cart-actions.js +1 -1
  36. package/esm/helpers/utils/cancellation-helpers.js +7 -0
  37. package/esm/helpers/utils/common.js +0 -46
  38. package/esm/helpers/utils/getFormFieldsDiff.js +1 -1
  39. package/esm/helpers/utils/index.js +2 -0
  40. package/esm/helpers/utils/phone-helpers.js +40 -0
  41. package/esm/helpers/utils/receipt-engine.js +3 -1
  42. package/esm/helpers/utils/specials-helpers.js +1 -1
  43. package/esm/helpers/utils/void-items-report-helpers.js +2 -1
  44. package/esm/schemas/models/materialized_tenant_reports_iterations.js +82 -0
  45. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +399 -0
  46. package/esm/schemas/types/materialized_tenant_reports_iterations.js +1 -0
  47. package/esm/schemas/types/materialized_tenant_sales_overview_reports.js +1 -0
  48. package/lib/constants/ENUMS.d.ts +15 -1275
  49. package/lib/constants/ENUMS.js +31 -1994
  50. package/lib/constants/MATERIALIZED_REPORTS.d.ts +96 -0
  51. package/lib/constants/MATERIALIZED_REPORTS.js +108 -0
  52. package/lib/constants/enums/cash.d.ts +35 -0
  53. package/lib/constants/enums/cash.js +48 -0
  54. package/lib/constants/enums/communications.d.ts +79 -0
  55. package/lib/constants/enums/communications.js +332 -0
  56. package/lib/constants/enums/delivery.d.ts +26 -0
  57. package/lib/constants/enums/delivery.js +38 -0
  58. package/lib/constants/enums/geo.d.ts +133 -0
  59. package/lib/constants/enums/geo.js +153 -0
  60. package/lib/constants/enums/hr.d.ts +105 -0
  61. package/lib/constants/enums/hr.js +133 -0
  62. package/lib/constants/enums/internal.d.ts +104 -0
  63. package/lib/constants/enums/internal.js +135 -0
  64. package/lib/constants/enums/items.d.ts +94 -0
  65. package/lib/constants/enums/items.js +129 -0
  66. package/lib/constants/enums/misc.d.ts +25 -0
  67. package/lib/constants/enums/misc.js +38 -0
  68. package/lib/constants/enums/offers.d.ts +80 -0
  69. package/lib/constants/enums/offers.js +105 -0
  70. package/lib/constants/enums/order.d.ts +108 -0
  71. package/lib/constants/enums/order.js +138 -0
  72. package/lib/constants/enums/payments.d.ts +129 -0
  73. package/lib/constants/enums/payments.js +189 -0
  74. package/lib/constants/enums/platform.d.ts +100 -0
  75. package/lib/constants/enums/platform.js +218 -0
  76. package/lib/constants/enums/printing.d.ts +89 -0
  77. package/lib/constants/enums/printing.js +110 -0
  78. package/lib/constants/enums/users.d.ts +142 -0
  79. package/lib/constants/enums/users.js +248 -0
  80. package/lib/constants/enums/wallet.d.ts +26 -0
  81. package/lib/constants/enums/wallet.js +35 -0
  82. package/lib/helpers/materialized-reports/index.d.ts +5 -0
  83. package/lib/helpers/materialized-reports/index.js +21 -0
  84. package/lib/helpers/materialized-reports/key-helpers.d.ts +35 -0
  85. package/lib/helpers/materialized-reports/key-helpers.js +64 -0
  86. package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.d.ts +66 -0
  87. package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +63 -0
  88. package/lib/helpers/materialized-reports/scope-helpers.d.ts +57 -0
  89. package/lib/helpers/materialized-reports/scope-helpers.js +114 -0
  90. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +125 -0
  91. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +256 -0
  92. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +223 -0
  93. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +875 -0
  94. package/lib/helpers/store/cart-actions.js +6 -6
  95. package/lib/helpers/store/common-tenant-purchase-order-actions.d.ts +2 -2
  96. package/lib/helpers/store/common-tenant-purchase-order-actions.js +10 -10
  97. package/lib/helpers/store/common-warehouse-purchase-order-actions.js +4 -4
  98. package/lib/helpers/store/common-warehouse-purchase-order-rfq-actions.js +4 -4
  99. package/lib/helpers/store/common-warehouse-sale-order-actions.js +4 -4
  100. package/lib/helpers/store/common-warehouse-sale-order-rfq-actions.js +4 -4
  101. package/lib/helpers/store/offline-ordering.js +2 -2
  102. package/lib/helpers/store/tenant-purchase-orders-cart-actions.js +2 -2
  103. package/lib/helpers/store/warehouse-purchase-order-rfq-cart-actions.js +2 -2
  104. package/lib/helpers/store/warehouse-purchase-orders-cart-actions.js +2 -2
  105. package/lib/helpers/store/warehouse-sale-order-rfq-cart-actions.js +2 -2
  106. package/lib/helpers/store/warehouse-sale-orders-cart-actions.js +2 -2
  107. package/lib/helpers/utils/cancellation-helpers.d.ts +1 -0
  108. package/lib/helpers/utils/cancellation-helpers.js +13 -0
  109. package/lib/helpers/utils/common.d.ts +0 -6
  110. package/lib/helpers/utils/common.js +1 -54
  111. package/lib/helpers/utils/getFormFieldsDiff.js +5 -2
  112. package/lib/helpers/utils/index.d.ts +2 -0
  113. package/lib/helpers/utils/index.js +2 -0
  114. package/lib/helpers/utils/phone-helpers.d.ts +5 -0
  115. package/lib/helpers/utils/phone-helpers.js +46 -0
  116. package/lib/helpers/utils/receipt-engine.js +4 -2
  117. package/lib/helpers/utils/specials-helpers.js +2 -2
  118. package/lib/helpers/utils/void-items-report-helpers.js +3 -2
  119. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +80 -0
  120. package/lib/schemas/models/materialized_tenant_reports_iterations.js +85 -0
  121. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +569 -0
  122. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +402 -0
  123. package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +62 -0
  124. package/lib/schemas/types/materialized_tenant_reports_iterations.js +2 -0
  125. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +242 -0
  126. package/lib/schemas/types/materialized_tenant_sales_overview_reports.js +3 -0
  127. package/lib/tests/materialized-reports/fixtures.d.ts +81 -0
  128. package/lib/tests/materialized-reports/fixtures.js +87 -0
  129. package/lib/tests/materialized-reports/fixtures.test.d.ts +1 -0
  130. package/lib/tests/materialized-reports/fixtures.test.js +123 -0
  131. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.d.ts +1 -0
  132. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.js +75 -0
  133. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.d.ts +1 -0
  134. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +73 -0
  135. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.d.ts +1 -0
  136. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +207 -0
  137. package/lib/tests/materialized-reports/sales-overview-baseline.test.d.ts +1 -0
  138. package/lib/tests/materialized-reports/sales-overview-baseline.test.js +326 -0
  139. package/lib/tests/materialized-reports/sales-overview-reference.d.ts +63 -0
  140. package/lib/tests/materialized-reports/sales-overview-reference.js +131 -0
  141. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.d.ts +1 -0
  142. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +335 -0
  143. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.d.ts +1 -0
  144. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +885 -0
  145. package/package.json +5 -2
@@ -0,0 +1,223 @@
1
+ import mongoose from 'mongoose';
2
+ import { IOrder, IOrderPayment } from '../../schemas';
3
+ import { IMaterializedReportKeyMetrics, IMaterializedReportReceivedCreditBill, IMaterializedTenantSalesOverviewReport } from '../../schemas/types/materialized_tenant_sales_overview_reports';
4
+ /**
5
+ * Backend materialization helpers for `materialized_tenant_sales_overview_reports`
6
+ * (see `MATERIALIZED_REPORTS.md` "Backend materialization cycle").
7
+ *
8
+ * The backend cycle has two halves:
9
+ *
10
+ * 1. **JSON building** — `convertOrdersToMaterializedTenantSalesOverviewReports`
11
+ * 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
+ * `sumMaterializedTenantSalesOverviewReports` accumulates those into
14
+ * longer-period documents (week → year) and
15
+ * `updateMaterializedTenantSalesOverviewReport` patches an existing document
16
+ * (delta amounts / credit-bill receipt tracking).
17
+ * 2. **Persistence** — `convertMaterializedTenantSalesOverviewReportJsonToBson`
18
+ * casts a JSON document through the mongoose schema so the job can upsert it.
19
+ *
20
+ * Conventions:
21
+ * - amounts are CENTS; every metric mirrors the live Reports > Overview
22
+ * aggregation (`sales-overview-reference.ts` is the test-time twin of the
23
+ * payment/order rules below — keep them in sync);
24
+ * - orders are attributed to the tenant-local BUSINESS day held by
25
+ * `order.localDate` (falls back to the `localDate` argument when absent);
26
+ * orders whose business day differs from the day being compiled only
27
+ * produce `received_payments` (credit-bill collections), never sales;
28
+ * - hour buckets: SALES orders use the punch hour (`order.localHour` →
29
+ * `gmtOffset` → `order_settled_at_mins ÷ 60`); credit-bill COLLECTION
30
+ * events use the SETTLEMENT hour (`gmtOffset` + `order_settled_at` →
31
+ * `order_settled_at_mins ÷ 60` → punch-hour fallback) — hour views must
32
+ * reflect when money was collected, not when the bill was punched;
33
+ * - INPUT CONTRACT: pass plain JSON documents (`.lean()` recommended). A
34
+ * hydrated document's map-cast `sale_type_metrics` is normalized
35
+ * 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`);
43
+ * - cancelled orders are materialized fully under their `CANCELLED:*` keys —
44
+ * the read layer excludes them for TOTAL_SALES parity and derives the
45
+ * Cancelled facet from those keys;
46
+ * - reconcile/retry of a day re-applies it as
47
+ * `update(periodDoc, { subtract: [previousDayDoc], additions: [newDayDoc] })`
48
+ * (the stored `localDate` doc of D IS the delta previously folded into the
49
+ * period docs); every versioned write bumps `iteration` — the caller records
50
+ * the post-write state through `buildMaterializedTenantReportIteration` into
51
+ * the shared `materialized_tenant_reports_iterations` history (see
52
+ * `MATERIALIZED_REPORTS.md`);
53
+ * - VALIDATION: these helpers never throw — invalid input (malformed
54
+ * `localDate`, un-keyable `order_status` / `platform`, a `PAY_LATER`
55
+ * payment with no `payment_id`/`_id`, mismatched sums) returns `null`,
56
+ * which callers must treat as a data issue to surface/fix.
57
+ */
58
+ /** Options of `convertOrdersToMaterializedTenantSalesOverviewReports`. */
59
+ export interface IConvertOrdersToMaterializedReportsOptions {
60
+ /** Tenant brand id stored on every document (brand-level reads). */
61
+ brandId?: string;
62
+ /**
63
+ * Tenant GMT offset (e.g. `+5`) used to derive an order's local hour when
64
+ * the order does not carry local time fields itself (`order.localHour`).
65
+ * When omitted, the pre-computed `order.order_settled_at_mins` is used as
66
+ * minutes-of-the-local-day (the convention of the test fixtures).
67
+ */
68
+ gmtOffset?: number;
69
+ /**
70
+ * Tenant id used to emit the (empty) period documents for an order-less day.
71
+ * Ignored when `orders` is non-empty (tenant ids come from the orders).
72
+ */
73
+ tenantId?: string;
74
+ /** Override for `computed_at` / `createdAt` / `updatedAt` (tests, replays). */
75
+ computedAt?: Date;
76
+ }
77
+ /** Result of a tenant-day compile. */
78
+ export interface IConvertOrdersToMaterializedReportsResult {
79
+ materializedReports: IMaterializedTenantSalesOverviewReport[];
80
+ received_payments: IMaterializedReportReceivedCreditBill[];
81
+ }
82
+ /** `PAY_LATER` is reported as `UNPAID` (live-aggregation behavior). */
83
+ export declare function normalizeMaterializedPaymentType(paymentType: string): string;
84
+ /**
85
+ * Payment-level inclusion rule of the `TOTAL_PAYMENT_SALES` facet:
86
+ * settled/refunded payments, plus pending `UNPAID`/`PAY_LATER` (credit)
87
+ * payments.
88
+ */
89
+ export declare function isPaymentIncludedInMaterializedSalesOverview(payment: IOrderPayment): boolean;
90
+ /**
91
+ * Payment gross contribution in cents (mirrors the live aggregation):
92
+ * - no refund: `amount_due` for UNPAID, else `min(amount_paid, amount_due)`;
93
+ * card charges subtracted when `card_details` is present;
94
+ * - refunded: negative — `-amount_due` for UNPAID, else `-amount_refunded`.
95
+ */
96
+ 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;
99
+ /**
100
+ * Plain-record view of a report's `sale_type_metrics`. The schema stores the
101
+ * map as a mongoose `Map` of subdocuments, so a hydrated document
102
+ * (`Model.find()` / the json→BSON cast) carries non-plain values — and
103
+ * `Object.entries` on the raw `Map` is EMPTY, which would silently wipe the
104
+ * stored metrics. This guard deep-converts hydrated shapes (Map container,
105
+ * subdocument values, document arrays) into plain values. Callers should still
106
+ * pass plain JSON (`.lean()`); this guard is the defensive net, not the
107
+ * contract.
108
+ */
109
+ export declare function normalizeMaterializedSaleTypeMetrics(metrics: IMaterializedTenantSalesOverviewReport['sale_type_metrics'] | Map<string, IMaterializedReportKeyMetrics> | null | undefined): Record<string, IMaterializedReportKeyMetrics>;
110
+ /**
111
+ * Compiles one tenant-day of orders into materialized scope documents:
112
+ *
113
+ * - one `localHour` document for every hour with activity (never more than 24);
114
+ * - one document per period scope (`localDate` … `localYear`) — always emitted,
115
+ * even for order-less days (empty metrics map), so reconcile/watermark
116
+ * comparisons stay uniform;
117
+ * - `day_index` is set on the `localHour` / `localDate` documents only;
118
+ * - `CREDIT_BILLS`: bills issued by the day's orders are itemized on every
119
+ * scope document of the day; bills collected that day (orders whose business
120
+ * `order.localDate` is earlier) itemize into `received` and are returned as
121
+ * `received_payments` so the caller can patch the issue-day documents.
122
+ *
123
+ * All outputs are plain JSON (dates are `Date` instances — JSON-serializable).
124
+ * Returns `null` (never throws) when the input is invalid — a malformed
125
+ * `localDate` or an order that cannot be keyed (`order_status` / `platform`
126
+ * missing or containing reserved characters) — `null` means a data issue.
127
+ */
128
+ export declare function convertOrdersToMaterializedTenantSalesOverviewReports(localDate: string, orders: IOrder[], options?: IConvertOrdersToMaterializedReportsOptions): IConvertOrdersToMaterializedReportsResult | null;
129
+ /**
130
+ * Casts a JSON materialized report through the collection's mongoose schema,
131
+ * returning a hydrated document ready to be saved / bulk-written (the
132
+ * `sale_type_metrics` plain object becomes a `Map`, date strings become
133
+ * `Date` instances, etc.).
134
+ *
135
+ * The document is NOT validated here — `save()` / `Model.validate()` still
136
+ * runs the schema validators.
137
+ */
138
+ export declare function convertMaterializedTenantSalesOverviewReportJsonToBson(report: IMaterializedTenantSalesOverviewReport): mongoose.HydratedDocument<IMaterializedTenantSalesOverviewReport>;
139
+ /**
140
+ * Sums materialized reports that share the same tenant, brand, key filters and
141
+ * `schema_version` — the period accumulation path. The scope MAY differ: pass
142
+ * the period document (month / quarter / year …) FIRST so the result keeps its
143
+ * identity while day documents are accumulated into it.
144
+ *
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.
149
+ *
150
+ * Returns `null` (never throws) when the inputs cannot be summed — empty list
151
+ * or mismatched tenant / brand / schema version / key filters. `null` means a
152
+ * data issue the caller must surface.
153
+ */
154
+ export declare function sumMaterializedTenantSalesOverviewReports(reports: IMaterializedTenantSalesOverviewReport[], options?: {
155
+ computedAt?: Date;
156
+ }): IMaterializedTenantSalesOverviewReport | null;
157
+ /**
158
+ * Subtracts `subtrahend`'s metric tree from `minuend` — the first half of the
159
+ * reconcile/retry flow
160
+ * (`update(periodDoc, { subtract: [previousDayDoc], additions: [newDayDoc] })`):
161
+ * the stored `localDate` doc of day D IS the delta previously folded into the
162
+ * period docs.
163
+ *
164
+ * Bills are removed by `(order_id, payment_id)`; ledger counters are recomputed
165
+ * from the remaining bills. Returns `null` (never throws) on mismatched inputs.
166
+ */
167
+ export declare function subtractMaterializedTenantSalesOverviewReports(minuend: IMaterializedTenantSalesOverviewReport, subtrahend: IMaterializedTenantSalesOverviewReport): IMaterializedTenantSalesOverviewReport | null;
168
+ /** Update descriptor of `updateMaterializedTenantSalesOverviewReport`. */
169
+ export interface IUpdateMaterializedTenantSalesOverviewReportInput {
170
+ /**
171
+ * Replaces the metric tree wholesale (the envelope is kept) — the day-close
172
+ * write for `localHour` / `localDate` documents.
173
+ */
174
+ replacement?: IMaterializedTenantSalesOverviewReport;
175
+ /**
176
+ * Reports subtracted from the existing metrics BEFORE `additions` — the
177
+ * reconcile/retry flow: subtract the previously applied day delta, then add
178
+ * the newly calculated one.
179
+ */
180
+ subtract?: IMaterializedTenantSalesOverviewReport[];
181
+ /**
182
+ * Reports whose metrics are summed INTO the existing document (delta
183
+ * amounts) — e.g. a fresh day compile folded into an accumulating
184
+ * month document.
185
+ */
186
+ additions?: IMaterializedTenantSalesOverviewReport[];
187
+ /**
188
+ * Credit-bill collection events (`received_payments` of a day compile) used
189
+ * to patch the document's `issued` ledger — applies to the ISSUE-day
190
+ * documents: `received_amount` is set to the cumulative received value;
191
+ * `credit_note` and `settled_at` (the received entry's collection timestamp,
192
+ * falling back to `computedAt`) are recorded when full collection is
193
+ * reached. Absolute values keep replays idempotent; a patch that changes
194
+ * the ledger is a versioned write (bumps `iteration` — append its history
195
+ * row), a no-op patch bumps nothing.
196
+ */
197
+ received_payments?: IMaterializedReportReceivedCreditBill[];
198
+ }
199
+ /**
200
+ * Versioned write on an existing JSON report (never throws; `null` on
201
+ * mismatched inputs) — the single place that mutates a stored document:
202
+ *
203
+ * 1. metrics: `replacement` swaps the tree wholesale (day/hour docs);
204
+ * otherwise `subtract` first (previously applied deltas), then `additions`
205
+ * (newly calculated ones) — the reconcile/retry pattern;
206
+ * 2. `received_payments` patches matching `issued` bills (`received_amount`
207
+ * cumulative, `credit_note`, `settled_at` — the received entry's true
208
+ * collection timestamp, falling back to `computedAt`, stamped when
209
+ * `received_amount >= amount`);
210
+ * 3. versioning: metric writes (`replacement` / `subtract` / `additions`) AND
211
+ * received-payment patches that change the ledger bump `iteration` — the
212
+ * returned document is recorded as a `materialized_tenant_reports_iterations`
213
+ * row by the caller (`buildMaterializedTenantReportIteration`); no-op
214
+ * patches bump nothing, so replays stay churn-free;
215
+ * 4. `source_watermark` advances to the max of the existing and the incoming
216
+ * (`replacement` / `additions`) watermarks — monotonic, never regressed
217
+ * (rollbacks / replays keep the previously folded maximum).
218
+ *
219
+ * Returns a new JSON report; the input is not mutated.
220
+ */
221
+ export declare function updateMaterializedTenantSalesOverviewReport(existing: IMaterializedTenantSalesOverviewReport, updates: IUpdateMaterializedTenantSalesOverviewReportInput, options?: {
222
+ computedAt?: Date;
223
+ }): IMaterializedTenantSalesOverviewReport | null;