@managesome/eposmatic-toolkit 0.4.7 → 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 (51) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +33 -0
  2. package/esm/helpers/materialized-reports/index.js +1 -0
  3. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +982 -0
  4. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +276 -33
  5. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +327 -41
  6. package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  7. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +118 -235
  8. package/esm/schemas/models/index.js +1 -0
  9. package/esm/schemas/models/materialized_credit_bills.js +265 -0
  10. package/esm/schemas/models/materialized_tenant_reports_iterations.js +13 -0
  11. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +39 -97
  12. package/esm/schemas/types/index.js +1 -0
  13. package/esm/schemas/types/materialized_credit_bills.js +1 -0
  14. package/lib/constants/MATERIALIZED_REPORTS.d.ts +28 -2
  15. package/lib/constants/MATERIALIZED_REPORTS.js +34 -1
  16. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  17. package/lib/helpers/materialized-reports/index.js +1 -0
  18. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +307 -0
  19. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +1003 -0
  20. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +36 -2
  21. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +278 -34
  22. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +66 -8
  23. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +326 -40
  24. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +18 -2
  25. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  26. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +46 -37
  27. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +119 -238
  28. package/lib/helpers/types/materialized-reports-apis.d.ts +32 -5
  29. package/lib/schemas/models/index.d.ts +1 -0
  30. package/lib/schemas/models/index.js +1 -0
  31. package/lib/schemas/models/materialized_credit_bills.d.ts +337 -0
  32. package/lib/schemas/models/materialized_credit_bills.js +268 -0
  33. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +20 -6
  34. package/lib/schemas/models/materialized_tenant_reports_iterations.js +14 -1
  35. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +37 -165
  36. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +40 -98
  37. package/lib/schemas/types/index.d.ts +1 -0
  38. package/lib/schemas/types/index.js +1 -0
  39. package/lib/schemas/types/materialized_credit_bills.d.ts +139 -0
  40. package/lib/schemas/types/materialized_credit_bills.js +2 -0
  41. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +32 -77
  42. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.d.ts +1 -0
  43. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +715 -0
  44. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +96 -0
  45. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +9 -0
  46. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +23 -24
  47. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +327 -22
  48. package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +27 -2
  49. package/lib/tests/materialized-reports/tenant-sales-overview-formatter.test.js +12 -27
  50. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +79 -146
  51. package/package.json +1 -1
@@ -19,14 +19,13 @@ import { MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM } f
19
19
  * - `payment_type` is an open string — live stores contain values outside
20
20
  * `PAYMENT_TYPE_ENUM` (`CARD_PAYMENT`, `FOODPANDA`, …) and they must pass
21
21
  * through untouched;
22
- * - the `CREDIT_BILLS` slot of each `sale_type_metrics` key carries the
23
- * PAY_LATER ledger (issued + settled tracking / received) so platform and
24
- * status filters apply to credit bills too; report views (the Credit Bills
25
- * sale-type numbers and the credit-settlement payments line) are derived by
26
- * the frontend formatter (see `MATERIALIZED_REPORTS.md`);
27
- * - every structural write's full post-write snapshot is recorded in the
28
- * shared `materialized_tenant_reports_iterations` history — this document carries no
29
- * embedded iteration snapshot.
22
+ * NUMBERS ONLY: credit-bill COUNTERS (issued / settled / received) live in
23
+ * each `sale_type_metrics` key's `CREDIT_BILLS` slot — constant-size numbers.
24
+ * The ITEMIZED ledger (one row per bill + its receipt events) lives in the
25
+ * SHARED `materialized_tenant_credit_bills` collection, so these documents carry no
26
+ * bill rows/ids and their size no longer grows with the ledger over time.
27
+ * Iteration history (every structural write's full post-write snapshot)
28
+ * lives in the shared `materialized_tenant_reports_iterations` collection.
30
29
  */
31
30
  /** Order-level discount sums per source (`order_discount_details`), cents. */
32
31
  export interface IMaterializedReportDiscountByType {
@@ -93,79 +92,38 @@ export interface IMaterializedReportSaleTypeMetric {
93
92
  payments: IMaterializedReportPaymentMetric[];
94
93
  }
95
94
  /**
96
- * One credit bill (`PAY_LATER`) tracked by a `sale_type_metrics` key. Issued
97
- * when a day closes with an unpaid order marked as a credit bill;
98
- * `received_amount` / `settled_at` are patched when the bill is collected on
99
- * a later day.
100
- */
101
- export interface IMaterializedReportCreditBill {
102
- order_id: string;
103
- payment_id: string;
104
- /** Cents — the bill's amount at issue. */
105
- amount: number;
106
- /**
107
- * Cumulative amount received against the bill so far (0 while unpaid, less
108
- * than `amount` while partially paid). Replaces the old `is_settled` flag:
109
- * the bill is SETTLED when `received_amount >= amount` (`settled_at` is
110
- * stamped). Never an event delta — collection patches write absolute
111
- * values, so replays are idempotent.
112
- */
113
- received_amount: number;
114
- credit_note?: string;
115
- /**
116
- * When the bill was issued — the order's punch time (`createdAt`), never
117
- * `order_settled_at` (for deferred bills that is the collection moment).
118
- */
119
- issued_at: Date;
120
- settled_at: Date | null;
121
- }
122
- /** A previously-issued credit bill collected within this scope's slice. */
123
- export interface IMaterializedReportReceivedCreditBill {
124
- order_id: string;
125
- payment_id: string;
126
- /** Cents — the collected amount. */
127
- amount: number;
128
- /** Cumulative amount received as of the collection compile (reaches `amount` when fully collected). */
129
- received_amount: number;
130
- credit_note?: string;
131
- /** `YYYY-MM-DD` local day the bill was issued on (the sale's day). */
132
- issued_local_date: string;
133
- /**
134
- * Collection timestamp (`order_settled_at`) when known — stamped onto the
135
- * issue-day bill's `settled_at` by the collection patch (falls back to the
136
- * close's `computedAt`).
137
- */
138
- settled_at?: Date | null;
139
- }
140
- /**
141
- * Credit-bill (`PAY_LATER`) ledger of one `sale_type_metrics` key (see
142
- * `MATERIALIZED_REPORTS.md`):
143
- * - `issued` — bills created for this filter combination (tracking; NOT
144
- * money-in), including `settled_count` / `settled_amount` — how much of
145
- * them has been collected since (patched on settlement; analysis only);
146
- * - `received` — previous days' bills of this combination collected in this
147
- * scope (tracking; the frontend formatter derives the credit-settlement
148
- * payments line from it).
95
+ * Credit-bill counters of one `sale_type_metrics` key — NUMBERS ONLY (the
96
+ * itemized ledger lives in the shared `materialized_tenant_credit_bills` collection;
97
+ * these documents never carry bill rows/ids, so the slot is constant-size):
98
+ * - `issued` — bills created for this filter combination in this scope
99
+ * (tracking; NOT money-in); `settled_count` / `settled_amount` track how
100
+ * many / how much (Σ `amount`) have been FULLY collected — patched when a
101
+ * collection covers the bill (partial receipts never count here). These are
102
+ * EVER-SETTLED (NOW state) counters: a bill settled on any later day counts
103
+ * here. The range-pure as-of-end answer (`settled_local_date` ≤ the
104
+ * selection end) is computed from the credit documents by
105
+ * `computeMaterializedCreditBillTotalsFromReports` — the two legitimately
106
+ * differ for historical ranges (audit R5-4) and must not be rendered
107
+ * side-by-side without labeling;
108
+ * - `received` — receipt EVENTS collected in this scope: `count` = the events
109
+ * themselves (a bill collected in two installments counts twice — audit
110
+ * R5-2), `amount` = money received (Σ `received_delta`).
149
111
  *
150
112
  * Amounts are cents. The ledger never feeds gross — gross stays sales-only so
151
- * cross-day gross sums stay equal to total sales.
113
+ * cross-day gross sums stay equal to total sales. Range-pure extras
114
+ * (`outstanding*`, `collected_at_issue_*`) are READ-derived (the aggregation
115
+ * reads the shared ledger rows); they are not stored here.
152
116
  */
153
117
  export interface IMaterializedReportCreditBills {
154
118
  issued: {
155
119
  count: number;
156
120
  amount: number;
157
- /**
158
- * Of the issued bills: how many / how much (cents) have been collected
159
- * since — patched when the collection event is detected.
160
- */
161
121
  settled_count: number;
162
122
  settled_amount: number;
163
- bills: IMaterializedReportCreditBill[];
164
123
  };
165
124
  received: {
166
125
  count: number;
167
126
  amount: number;
168
- bills: IMaterializedReportReceivedCreditBill[];
169
127
  };
170
128
  }
171
129
  /**
@@ -177,11 +135,7 @@ export interface IMaterializedReportKeyMetrics {
177
135
  [REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: IMaterializedReportSaleTypeMetric;
178
136
  /** Orders with `amount_collected > 0`. */
179
137
  [REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED]: IMaterializedReportSaleTypeMetric;
180
- /**
181
- * Credit-bill (`PAY_LATER`) ledger of this filter combination — the Credit
182
- * Bills sale-type numbers are derived from it by the frontend formatter
183
- * (not stored separately).
184
- */
138
+ /** Credit-bill counters (numbers only — see `IMaterializedReportCreditBills`). */
185
139
  [REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: IMaterializedReportCreditBills;
186
140
  }
187
141
  export interface IMaterializedTenantSalesOverviewReport {
@@ -222,10 +176,11 @@ export interface IMaterializedTenantSalesOverviewReport {
222
176
  sale_type_metrics: Record<string, IMaterializedReportKeyMetrics> | null;
223
177
  /**
224
178
  * Versioned writes applied to this document (replacement / deltas; 1 = first
225
- * materialization). Received-payment patches that change the ledger bump it
226
- * too (no-op patches don't). Every bump is recorded as a row in the shared
227
- * `materialized_tenant_reports_iterations` history (full post-write snapshot;
228
- * see `MATERIALIZED_REPORTS.md`).
179
+ * materialization). Credit-bill collection closes that settle a bill patch
180
+ * this document's CREDIT_BILLS COUNTERS (the itemized ledger lives in
181
+ * `materialized_tenant_credit_bills` and is never embedded here). Every bump is
182
+ * recorded as a row in the shared `materialized_tenant_reports_iterations`
183
+ * history (full post-write snapshot; see `MATERIALIZED_REPORTS.md`).
229
184
  */
230
185
  iteration?: number;
231
186
  /** Bump on key-grammar / metric-rule changes; requires re-materialization. */