@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
@@ -0,0 +1,265 @@
1
+ import { Schema } from 'mongoose';
2
+ import { ALL_DAY_INDEX } from '../../constants/ENUMS';
3
+ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, MATERIALIZED_CREDIT_BILLS_SCOPES, SALES_OVERVIEW_KEY_FILTERS, } from '../../constants/MATERIALIZED_REPORTS';
4
+ /**
5
+ * Mongoose schema for `materialized_tenant_credit_bills` — the SHARED
6
+ * credit-bill ledger of the materialized reports (see `MATERIALIZED_REPORTS.md`).
7
+ *
8
+ * ONE document per (tenant, scope context, scope value), scopes CAPPED AT
9
+ * `LOCAL_MONTH` (`MATERIALIZED_CREDIT_BILLS_SCOPES`) so a document can never
10
+ * grow unboundedly: a month bounds its bill volume by construction. Each
11
+ * document carries a per-key `credit_bills` map of slim `issued` / `received`
12
+ * entries (ids + credit facts — the order document stays the single source of
13
+ * the sale). See the type module `schemas/types/materialized_credit_bills.ts`
14
+ * for the entry contract. Amounts are CENTS; reads pin `schema_version`.
15
+ */
16
+ /**
17
+ * Version of the credit-entry rules of this collection. Bump when entry
18
+ * semantics change (e.g. signed REFUND / WRITE_OFF deltas) — historical
19
+ * documents must then be re-materialized. PRE-RELEASE: the collection has no
20
+ * live tenants/consumers yet, so every change so far folds into version `1`.
21
+ */
22
+ export const MATERIALIZED_CREDIT_BILLS_SCHEMA_VERSION = 1;
23
+ const CreditBillIssuedEntrySchema = new Schema({
24
+ order_id: {
25
+ type: String,
26
+ required: true,
27
+ },
28
+ payment_id: {
29
+ type: String,
30
+ required: true,
31
+ },
32
+ amount: {
33
+ type: Number, // cents — the bill's amount at issue
34
+ required: true,
35
+ min: 0,
36
+ },
37
+ issued_at: {
38
+ type: Schema.Types.Date, // punch time (order.createdAt) — NEVER order_settled_at
39
+ required: true,
40
+ },
41
+ issued_local_hour: {
42
+ type: String, // 'YYYY-MM-DD HH' punch hour (null when unknown)
43
+ default: null,
44
+ },
45
+ // Cents received BEFORE the issue day closed (prepaid partials +
46
+ // same-day settled credit). Carried forward on re-closes — never
47
+ // re-anchored to the current payment state.
48
+ received_at_issue: {
49
+ type: Number,
50
+ required: true,
51
+ default: 0,
52
+ min: 0,
53
+ },
54
+ // Cumulative received so far (NOW state) — patched by collection closes
55
+ // on the ISSUE-scope documents (bounded fan-out).
56
+ received_amount: {
57
+ type: Number,
58
+ required: true,
59
+ default: 0,
60
+ min: 0,
61
+ },
62
+ settled_at: {
63
+ type: Schema.Types.Date, // the settling receipt's timestamp when known
64
+ default: null,
65
+ },
66
+ settled_local_date: {
67
+ type: String, // 'YYYY-MM-DD' — the settling receipt event's day
68
+ default: null,
69
+ },
70
+ credit_note: {
71
+ type: String, // optional note/reference recorded with the collection
72
+ default: null,
73
+ },
74
+ }, { _id: false, minimize: false });
75
+ const CreditBillReceivedEntrySchema = new Schema({
76
+ order_id: {
77
+ type: String,
78
+ required: true,
79
+ },
80
+ payment_id: {
81
+ type: String,
82
+ required: true,
83
+ },
84
+ event_local_date: {
85
+ type: String, // 'YYYY-MM-DD' — collection business day (entry identity)
86
+ required: true,
87
+ },
88
+ amount: {
89
+ type: Number, // cents — the bill's amount at issue (receipt context)
90
+ required: true,
91
+ min: 0,
92
+ },
93
+ // Cumulative received right AFTER this event — the idempotent re-close
94
+ // anchor (`prior = received_amount − received_delta`).
95
+ received_amount: {
96
+ type: Number,
97
+ required: true,
98
+ default: 0,
99
+ min: 0,
100
+ },
101
+ // Cents collected BY this event (incremental — resolved against the
102
+ // stored pre-event cumulative at close-plan time). REFUND / WRITE_OFF
103
+ // would carry a SIGNED delta — reserved, unimplemented.
104
+ received_delta: {
105
+ type: Number,
106
+ required: true,
107
+ default: 0,
108
+ },
109
+ received_at: {
110
+ type: Schema.Types.Date, // collection timestamp (order_settled_at) when known — ordering anchor
111
+ default: null,
112
+ },
113
+ event_local_hour: {
114
+ type: String, // 'YYYY-MM-DD HH' tenant-local collection hour (null when unknown)
115
+ default: null,
116
+ },
117
+ credit_note: {
118
+ type: String,
119
+ default: null,
120
+ },
121
+ issued_local_date: {
122
+ type: String, // 'YYYY-MM-DD' — the bill's issue day (display anchor)
123
+ required: true,
124
+ },
125
+ }, { _id: false, minimize: false });
126
+ const CreditBillKeySectionSchema = new Schema({
127
+ issued: {
128
+ type: [CreditBillIssuedEntrySchema],
129
+ default: [],
130
+ },
131
+ received: {
132
+ type: [CreditBillReceivedEntrySchema],
133
+ default: [],
134
+ },
135
+ }, { _id: false, minimize: false });
136
+ export const MaterializedTenantCreditBillsReportSchema = new Schema({
137
+ _id: {
138
+ type: Schema.Types.ObjectId,
139
+ required: true,
140
+ immutable: true,
141
+ },
142
+ tenant_id: {
143
+ type: String,
144
+ required: true,
145
+ immutable: true,
146
+ ref: 'tenants',
147
+ },
148
+ brand_id: {
149
+ type: String,
150
+ required: true,
151
+ },
152
+ scope_context: {
153
+ type: String,
154
+ enum: MATERIALIZED_CREDIT_BILLS_SCOPES,
155
+ required: true,
156
+ },
157
+ scope_field: {
158
+ type: String, // format depends on scope_context — see MATERIALIZED_REPORT_SCOPE_ENUM
159
+ required: true,
160
+ },
161
+ // Denormalized weekday of scope_field — set ONLY on LOCAL_HOUR /
162
+ // LOCAL_DATE documents (MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX);
163
+ // null elsewhere.
164
+ day_index: {
165
+ type: String,
166
+ enum: ALL_DAY_INDEX,
167
+ default: null,
168
+ },
169
+ sale_type_key_filters: {
170
+ type: [String],
171
+ enum: ALL_MATERIALIZED_REPORT_KEY_FILTERS,
172
+ required: true,
173
+ default: () => [...SALES_OVERVIEW_KEY_FILTERS],
174
+ },
175
+ // Map key = the ordered filter combination, e.g. "COMPLETED:POS_WALK-IN" —
176
+ // the grammar is declared by `sale_type_key_filters` and must be built /
177
+ // parsed through the shared key helper, never ad hoc.
178
+ credit_bills: {
179
+ type: Map,
180
+ of: CreditBillKeySectionSchema,
181
+ required: true,
182
+ default: {},
183
+ },
184
+ // Versioned writes: bumped on replacement / period deltas / settlement
185
+ // patches; 1 = first materialization. Every bump is recorded in the
186
+ // shared `materialized_tenant_reports_iterations` history (full post-write
187
+ // snapshot + reason) — this document carries no embedded snapshot.
188
+ iteration: {
189
+ type: Number,
190
+ required: true,
191
+ min: 1,
192
+ default: 1,
193
+ },
194
+ schema_version: {
195
+ type: Number,
196
+ required: true,
197
+ immutable: true,
198
+ default: MATERIALIZED_CREDIT_BILLS_SCHEMA_VERSION,
199
+ },
200
+ source_watermark: {
201
+ type: Schema.Types.Date,
202
+ required: true,
203
+ },
204
+ computed_at: {
205
+ type: Schema.Types.Date,
206
+ required: true,
207
+ },
208
+ createdAt: {
209
+ type: Schema.Types.Date,
210
+ required: true,
211
+ default: () => new Date(),
212
+ immutable: true,
213
+ },
214
+ updatedAt: {
215
+ type: Schema.Types.Date,
216
+ required: true,
217
+ default: () => new Date(),
218
+ },
219
+ }, {
220
+ timestamps: true,
221
+ versionKey: false,
222
+ minimize: false,
223
+ });
224
+ export const MATERIALIZED_TENANT_CREDIT_BILLS_COLLECTION_NAME = 'materialized_tenant_credit_bills';
225
+ /**
226
+ * Describes the indexes for `materialized_tenant_credit_bills`. Values are
227
+ * Mongo key patterns that can be passed straight to `.hint()`.
228
+ *
229
+ * ONE compound index carries the whole read story (plus `_id`) — same shape
230
+ * as the other materialized collections:
231
+ * `tenant_id__scope_context__scope_field__day_index` — UNIQUE:
232
+ * - identity — one document per (tenant, scope context, scope value);
233
+ * `day_index` is a deterministic function of `scope_field` (null for period
234
+ * scopes), so including it keeps the uniqueness exactly on that identity;
235
+ * - the drill-down read — the `{ tenant_id, scope_context, scope_field }`
236
+ * prefix serves exact and ranged scope-field queries (covering-set
237
+ * resolution) for single tenants and `$in` tenant lists.
238
+ *
239
+ * There are NO `brand_id` indexes: brand-level reads always pass the brand's
240
+ * explicit tenant list (`tenant_id: { $in }`).
241
+ */
242
+ export const MATERIALIZED_TENANT_CREDIT_BILLS_COLLECTION_INDEXES = {
243
+ _id: { _id: 1 }, // Unique Index
244
+ tenant_id__scope_context__scope_field__day_index: {
245
+ tenant_id: 1,
246
+ scope_context: 1,
247
+ scope_field: 1,
248
+ day_index: 1,
249
+ },
250
+ };
251
+ /**
252
+ * Index OPTIONS the materializer must CREATE — the identity index is a UNIQUE
253
+ * business invariant (one document per tenant × scope context × scope value;
254
+ * the close-day writes upsert against it and silently degrade without it),
255
+ * so it must be created with `unique: true`. The key patterns above are what
256
+ * the read `.hint()` consumes; these options are what creation must apply.
257
+ * The materializer boot should assert them (`listIndexes`, fail closed).
258
+ */
259
+ export const MATERIALIZED_TENANT_CREDIT_BILLS_INDEX_OPTIONS = [
260
+ {
261
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, day_index: 1 },
262
+ name: 'tenant_id__scope_context__scope_field__day_index',
263
+ unique: true,
264
+ },
265
+ ];
@@ -80,3 +80,16 @@ export const MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_INDEXES = {
80
80
  _id: { _id: 1 }, // Unique Index
81
81
  report_id__iteration: { report_id: 1, iteration: -1 }, // unique — one row per (report, iteration)
82
82
  };
83
+ /**
84
+ * Index OPTIONS the materializer must CREATE — `report_id__iteration` is a
85
+ * UNIQUE business invariant: one history row per (report, iteration), and the
86
+ * idempotent upsert key (`replaceOne({ report_id, iteration }, row, { upsert: true })`)
87
+ * silently degrades into duplicates without it.
88
+ */
89
+ export const MATERIALIZED_TENANT_REPORTS_ITERATIONS_INDEX_OPTIONS = [
90
+ {
91
+ key: { report_id: 1, iteration: -1 },
92
+ name: 'report_id__iteration',
93
+ unique: true,
94
+ },
95
+ ];
@@ -12,17 +12,20 @@ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, ALL_MATERIALIZED_REPORT_SCOPES, SA
12
12
  * `MATERIALIZED_REPORTS.md`). The report's time-bias toggle (Punched At /
13
13
  * `createdAt`) is out of scope. `scope_field` formats are documented on
14
14
  * `MATERIALIZED_REPORT_SCOPE_ENUM` and in `MATERIALIZED_REPORTS.md`.
15
- * Credit bills (`PAY_LATER`) live in each `sale_type_metrics` key's
16
- * `CREDIT_BILLS` slot as a ledger (issued + settled tracking / received);
17
- * gross stays sales-only and report views are derived by the frontend
18
- * formatter. Iteration history (every structural write's full post-write
19
- * snapshot) lives in the shared `materialized_tenant_reports_iterations` collection.
15
+ * NUMBERS ONLY: credit-bill COUNTERS (issued / settled / received) live in
16
+ * each `sale_type_metrics` key's `CREDIT_BILLS` slot — constant-size numbers.
17
+ * The ITEMIZED ledger (one row per bill + its receipt events) lives in the
18
+ * SHARED `materialized_tenant_credit_bills` collection, so these documents carry no
19
+ * bill rows/ids and their size no longer grows with the ledger over time.
20
+ * Iteration history (every structural write's full post-write snapshot)
21
+ * lives in the shared `materialized_tenant_reports_iterations` collection.
20
22
  */
21
23
  /**
22
24
  * Version of the key grammar + metric rules of this collection. Bump when
23
25
  * `sale_type_key_filters`, their order, or metric semantics change —
24
26
  * historical documents must then be re-materialized (readers may branch on
25
- * this value during a rollout).
27
+ * this value during a rollout). PRE-RELEASE: the collection has no live
28
+ * tenants/consumers yet, so every change so far folds into version `1`.
26
29
  */
27
30
  export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION = 1;
28
31
  const ReportDiscountByTypeSchema = new Schema({
@@ -126,77 +129,9 @@ const ReportSaleTypeMetricSchema = new Schema({
126
129
  default: [],
127
130
  },
128
131
  }, { _id: false, minimize: false });
129
- const ReportCreditBillSchema = new Schema({
130
- order_id: {
131
- type: String,
132
- required: true,
133
- },
134
- payment_id: {
135
- type: String,
136
- required: true,
137
- },
138
- amount: {
139
- type: Number, // cents — the bill's amount at issue
140
- required: true,
141
- },
142
- // Cumulative amount received against this bill so far (0 while unpaid;
143
- // less than `amount` while partially paid). Replaces the old `is_settled`
144
- // flag: the bill is settled when `received_amount >= amount` (`settled_at`
145
- // is stamped by the collection patch). Never an event delta, so patches
146
- // stay idempotent.
147
- received_amount: {
148
- type: Number,
149
- required: true,
150
- default: 0,
151
- },
152
- credit_note: {
153
- type: String, // optional note/reference recorded with the collection
154
- default: null,
155
- },
156
- issued_at: {
157
- type: Schema.Types.Date,
158
- required: true,
159
- },
160
- // Stamped when the bill is fully collected (received_amount >= amount).
161
- settled_at: {
162
- type: Schema.Types.Date,
163
- default: null,
164
- },
165
- }, { _id: false, minimize: false });
166
- const ReportReceivedCreditBillSchema = new Schema({
167
- order_id: {
168
- type: String,
169
- required: true,
170
- },
171
- payment_id: {
172
- type: String,
173
- required: true,
174
- },
175
- amount: {
176
- type: Number, // cents — the bill's amount at issue
177
- required: true,
178
- },
179
- // Cumulative amount received for this bill as of the collection compile
180
- // (≤ `amount` while partially paid; reaches `amount` when fully collected).
181
- received_amount: {
182
- type: Number,
183
- required: true,
184
- },
185
- credit_note: {
186
- type: String, // optional note/reference recorded with the collection
187
- default: null,
188
- },
189
- issued_local_date: {
190
- type: String, // 'YYYY-MM-DD' — the sale's day (bill issue day)
191
- required: true,
192
- },
193
- // Collection timestamp (`order_settled_at`) when known — stamped onto the
194
- // issue-day bill's `settled_at` by the collection patch.
195
- settled_at: {
196
- type: Schema.Types.Date,
197
- default: null,
198
- },
199
- }, { _id: false, minimize: false });
132
+ // Credit-bill COUNTERS live here (numbers only — the itemized ledger lives in
133
+ // the shared `materialized_tenant_credit_bills` collection; these documents never
134
+ // carry bill rows/ids, so their size is stable over time).
200
135
  const ReportCreditBillsSchema = new Schema({
201
136
  issued: {
202
137
  count: {
@@ -210,8 +145,9 @@ const ReportCreditBillsSchema = new Schema({
210
145
  required: true,
211
146
  default: 0,
212
147
  },
213
- // How much of the issued bills has been collected since — patched on
214
- // settlement (tracking only; the money is counted on the collection day).
148
+ // How many / how much (Σ amount) of the issued bills have been FULLY
149
+ // collected — patched when a collection covers the bill (partial
150
+ // receipts never count here).
215
151
  settled_count: {
216
152
  type: Number,
217
153
  required: true,
@@ -223,10 +159,6 @@ const ReportCreditBillsSchema = new Schema({
223
159
  required: true,
224
160
  default: 0,
225
161
  },
226
- bills: {
227
- type: [ReportCreditBillSchema],
228
- default: [],
229
- },
230
162
  },
231
163
  received: {
232
164
  count: {
@@ -240,15 +172,8 @@ const ReportCreditBillsSchema = new Schema({
240
172
  required: true,
241
173
  default: 0,
242
174
  },
243
- bills: {
244
- type: [ReportReceivedCreditBillSchema],
245
- default: [],
246
- },
247
175
  },
248
176
  }, { _id: false, minimize: false });
249
- // Credit bills carry the PAY_LATER ledger (issued + settled tracking /
250
- // received) — report views (including the Credit Bills sale-type numbers) are
251
- // derived by the frontend formatter, not stored separately.
252
177
  const ReportKeyMetricsSchema = new Schema({
253
178
  [REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: {
254
179
  type: ReportSaleTypeMetricSchema,
@@ -262,8 +187,8 @@ const ReportKeyMetricsSchema = new Schema({
262
187
  type: ReportCreditBillsSchema,
263
188
  required: true,
264
189
  default: () => ({
265
- issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0, bills: [] },
266
- received: { count: 0, amount: 0, bills: [] },
190
+ issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0 },
191
+ received: { count: 0, amount: 0 },
267
192
  }),
268
193
  },
269
194
  }, { _id: false, minimize: false });
@@ -317,11 +242,12 @@ export const MaterializedTenantSalesOverviewReportSchema = new Schema({
317
242
  default: {},
318
243
  },
319
244
  // Versioned writes: bumped by `updateMaterializedTenantSalesOverviewReport`
320
- // on metric changes (replacement / period deltas) AND on received-payment
321
- // patches that change the ledger; 1 = first materialization. Every bump is
322
- // recorded in the shared `materialized_tenant_reports_iterations` history
323
- // (full post-write snapshot + reason) — this document carries no embedded
324
- // snapshot.
245
+ // on metric changes (replacement / period deltas) AND on credit-bill
246
+ // collection patches that change the counters (the itemized ledger lives
247
+ // in `materialized_tenant_credit_bills` and is never embedded here); 1 = first
248
+ // materialization. Every bump is recorded in the shared
249
+ // `materialized_tenant_reports_iterations` history (full post-write
250
+ // snapshot + reason) — this document carries no embedded snapshot.
325
251
  iteration: {
326
252
  type: Number,
327
253
  required: true,
@@ -391,3 +317,19 @@ export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_INDEXES = {
391
317
  day_index: 1,
392
318
  },
393
319
  };
320
+ /**
321
+ * Index OPTIONS the materializer must CREATE — the identity index is a UNIQUE
322
+ * business invariant (one document per tenant × scope context × scope value;
323
+ * the close-day writes upsert against it and silently degrade without it),
324
+ * so it must be created with `unique: true`. The key patterns above are what
325
+ * the read `.hint()` consumes; these options are what creation must apply.
326
+ * The materializer boot should assert them (`listIndexes`, fail closed — the
327
+ * read hint already fails closed without the index itself).
328
+ */
329
+ export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS = [
330
+ {
331
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, day_index: 1 },
332
+ name: 'tenant_id__scope_context__scope_field__day_index',
333
+ unique: true,
334
+ },
335
+ ];
@@ -31,6 +31,7 @@ export * from './inventory_transactions';
31
31
  export * from './item_transactions';
32
32
  export * from './items';
33
33
  export * from './marketing_fingerprints';
34
+ export * from './materialized_credit_bills';
34
35
  export * from './materialized_tenant_reports_iterations';
35
36
  export * from './materialized_tenant_sales_overview_reports';
36
37
  export * from './menus';
@@ -0,0 +1 @@
1
+ export {};
@@ -58,6 +58,16 @@ export declare const ALL_MATERIALIZED_REPORT_SCOPES: MATERIALIZED_REPORT_SCOPE_E
58
58
  * (`LOCAL_HOUR` / `LOCAL_DATE`) instead of an all-time accumulator document.
59
59
  */
60
60
  export declare const MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX: MATERIALIZED_REPORT_SCOPE_ENUM[];
61
+ /**
62
+ * Scopes materialized by `materialized_tenant_credit_bills` — the credit
63
+ * ledger is CAPPED AT `LOCAL_MONTH`: a month bounds how many bills a document
64
+ * accumulates, so no document grows unboundedly over time. Whole-year /
65
+ * multi-year reads cover their range with the month documents (plus
66
+ * date/hour documents at range edges and for hour-precise time windows).
67
+ * `LOCAL_HOUR` is kept for zoomed-in selections (e.g. a report restricted to
68
+ * certain hours of a day).
69
+ */
70
+ export declare const MATERIALIZED_CREDIT_BILLS_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
61
71
  /**
62
72
  * Filter dimensions that can be encoded into the metric keys of a materialized
63
73
  * report document (`sale_type_metrics`). The declaration order defines the key
@@ -82,6 +92,21 @@ export declare const SALES_OVERVIEW_KEY_FILTERS: MATERIALIZED_REPORT_KEY_FILTER_
82
92
  * total sales.
83
93
  */
84
94
  export declare const MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = "CREDIT_SETTLEMENT";
95
+ /**
96
+ * Kind of a credit-bill ledger receipt event (`received.bills[].event_type` of
97
+ * the `CREDIT_BILLS` slot). The compile pipeline emits `RECEIPT`s today;
98
+ * `REFUND` / `WRITE_OFF` are reserved for SIGNED adjustments and are
99
+ * deliberately unimplemented (see `MATERIALIZED_REPORTS.md`). The event
100
+ * identity is `(order_id, payment_id, event_local_date)` — the kind never
101
+ * partakes in the key, so introducing the reserved kinds cannot rewrite
102
+ * existing events.
103
+ */
104
+ export declare enum MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM {
105
+ RECEIPT = "RECEIPT",
106
+ REFUND = "REFUND",
107
+ WRITE_OFF = "WRITE_OFF"
108
+ }
109
+ export declare const ALL_MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPES: MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM[];
85
110
  /**
86
111
  * Materialized report kinds — the discriminator stored on
87
112
  * `materialized_tenant_reports_iterations` rows. A single shared history collection records
@@ -91,6 +116,7 @@ export declare const MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = "CREDIT_SETTL
91
116
  * as it lands.
92
117
  */
93
118
  export declare enum MATERIALIZED_REPORT_TYPE_ENUM {
94
- TENANT_SALES_OVERVIEW = "TENANT_SALES_OVERVIEW"
119
+ TENANT_SALES_OVERVIEW = "TENANT_SALES_OVERVIEW",
120
+ TENANT_CREDIT_BILLS = "TENANT_CREDIT_BILLS"
95
121
  }
96
- export declare const ALL_MATERIALIZED_REPORT_TYPES: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_SALES_OVERVIEW[];
122
+ export declare const ALL_MATERIALIZED_REPORT_TYPES: MATERIALIZED_REPORT_TYPE_ENUM[];
@@ -10,7 +10,7 @@
10
10
  * explicitly-enabled step.
11
11
  */
12
12
  Object.defineProperty(exports, "__esModule", { value: true });
13
- exports.ALL_MATERIALIZED_REPORT_TYPES = exports.MATERIALIZED_REPORT_TYPE_ENUM = exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = exports.SALES_OVERVIEW_KEY_FILTERS = exports.ALL_MATERIALIZED_REPORT_KEY_FILTERS = exports.MATERIALIZED_REPORT_KEY_FILTER_ENUM = exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = exports.ALL_MATERIALIZED_REPORT_SCOPES = exports.MATERIALIZED_REPORT_SCOPE_ENUM = void 0;
13
+ exports.ALL_MATERIALIZED_REPORT_TYPES = exports.MATERIALIZED_REPORT_TYPE_ENUM = exports.ALL_MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPES = exports.MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM = exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = exports.SALES_OVERVIEW_KEY_FILTERS = exports.ALL_MATERIALIZED_REPORT_KEY_FILTERS = exports.MATERIALIZED_REPORT_KEY_FILTER_ENUM = exports.MATERIALIZED_CREDIT_BILLS_SCOPES = exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = exports.ALL_MATERIALIZED_REPORT_SCOPES = exports.MATERIALIZED_REPORT_SCOPE_ENUM = void 0;
14
14
  /**
15
15
  * Time-scope of a materialized report document. Every document covers exactly
16
16
  * one tenant × one scope context × one scope value (`scope_field`), and the
@@ -65,6 +65,22 @@ exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = [
65
65
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR,
66
66
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
67
67
  ];
68
+ /**
69
+ * Scopes materialized by `materialized_tenant_credit_bills` — the credit
70
+ * ledger is CAPPED AT `LOCAL_MONTH`: a month bounds how many bills a document
71
+ * accumulates, so no document grows unboundedly over time. Whole-year /
72
+ * multi-year reads cover their range with the month documents (plus
73
+ * date/hour documents at range edges and for hour-precise time windows).
74
+ * `LOCAL_HOUR` is kept for zoomed-in selections (e.g. a report restricted to
75
+ * certain hours of a day).
76
+ */
77
+ exports.MATERIALIZED_CREDIT_BILLS_SCOPES = [
78
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR,
79
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
80
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK,
81
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR,
82
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
83
+ ];
68
84
  /**
69
85
  * Filter dimensions that can be encoded into the metric keys of a materialized
70
86
  * report document (`sale_type_metrics`). The declaration order defines the key
@@ -93,6 +109,22 @@ exports.SALES_OVERVIEW_KEY_FILTERS = [
93
109
  * total sales.
94
110
  */
95
111
  exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = 'CREDIT_SETTLEMENT';
112
+ /**
113
+ * Kind of a credit-bill ledger receipt event (`received.bills[].event_type` of
114
+ * the `CREDIT_BILLS` slot). The compile pipeline emits `RECEIPT`s today;
115
+ * `REFUND` / `WRITE_OFF` are reserved for SIGNED adjustments and are
116
+ * deliberately unimplemented (see `MATERIALIZED_REPORTS.md`). The event
117
+ * identity is `(order_id, payment_id, event_local_date)` — the kind never
118
+ * partakes in the key, so introducing the reserved kinds cannot rewrite
119
+ * existing events.
120
+ */
121
+ var MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM;
122
+ (function (MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM) {
123
+ MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM["RECEIPT"] = "RECEIPT";
124
+ MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM["REFUND"] = "REFUND";
125
+ MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM["WRITE_OFF"] = "WRITE_OFF";
126
+ })(MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM || (exports.MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM = MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM = {}));
127
+ exports.ALL_MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPES = Object.values(MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM);
96
128
  /**
97
129
  * Materialized report kinds — the discriminator stored on
98
130
  * `materialized_tenant_reports_iterations` rows. A single shared history collection records
@@ -104,5 +136,6 @@ exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = 'CREDIT_SETTLEMENT';
104
136
  var MATERIALIZED_REPORT_TYPE_ENUM;
105
137
  (function (MATERIALIZED_REPORT_TYPE_ENUM) {
106
138
  MATERIALIZED_REPORT_TYPE_ENUM["TENANT_SALES_OVERVIEW"] = "TENANT_SALES_OVERVIEW";
139
+ MATERIALIZED_REPORT_TYPE_ENUM["TENANT_CREDIT_BILLS"] = "TENANT_CREDIT_BILLS";
107
140
  })(MATERIALIZED_REPORT_TYPE_ENUM || (exports.MATERIALIZED_REPORT_TYPE_ENUM = MATERIALIZED_REPORT_TYPE_ENUM = {}));
108
141
  exports.ALL_MATERIALIZED_REPORT_TYPES = Object.values(MATERIALIZED_REPORT_TYPE_ENUM);
@@ -0,0 +1,31 @@
1
+ export declare enum CALENDAR_MODE_ENUM {
2
+ LIVE = "LIVE",
3
+ HISTORICAL = "HISTORICAL"
4
+ }
5
+ export declare const ALL_CALENDAR_MODE_ENUMS: CALENDAR_MODE_ENUM[];
6
+ export declare enum CALENDAR_VIEW_MODE_ENUM {
7
+ DATE_RANGE = "DATE_RANGE",
8
+ MULTI_DATE = "MULTI_DATE",
9
+ DATE_RANGE_TIME_WINDOW = "DATE_RANGE_TIME_WINDOW",
10
+ WEEK = "WEEK",
11
+ DIFFERENT_WEEKS = "DIFFERENT_WEEKS",
12
+ WEEK_OF_YEAR = "WEEK_OF_YEAR",
13
+ DIFFERENT_WEEKS_OF_YEAR = "DIFFERENT_WEEKS_OF_YEAR",
14
+ MONTH = "MONTH",
15
+ DIFFERENT_MONTHS = "DIFFERENT_MONTHS",
16
+ QUARTER = "QUARTER",
17
+ DIFFERENT_QUARTERS = "DIFFERENT_QUARTERS",
18
+ SEMESTER = "SEMESTER",
19
+ DIFFERENT_SEMESTERS = "DIFFERENT_SEMESTERS",
20
+ YEAR = "YEAR",
21
+ DIFFERENT_YEARS = "DIFFERENT_YEARS"
22
+ }
23
+ export declare const ALL_CALENDAR_VIEW_MODE_ENUMS: CALENDAR_VIEW_MODE_ENUM[];
24
+ /**
25
+ * Version of the `IReportCalendarSelection` spec carried by a materialized
26
+ * report READ body (`selection.spec_version`). Bump on any meaning-changing
27
+ * reshape of the selection model — the read API rejects unknown versions
28
+ * with a 400, so rolling deploys (old frontend → new backend) fail loudly
29
+ * instead of decoding a stale shape.
30
+ */
31
+ export declare const MATERIALIZED_REPORT_SELECTION_SPEC_VERSION = 1;