@managesome/eposmatic-toolkit 0.3.11 → 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 (52) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +105 -0
  2. package/esm/helpers/materialized-reports/index.js +5 -0
  3. package/esm/helpers/materialized-reports/key-helpers.js +59 -0
  4. package/esm/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +60 -0
  5. package/esm/helpers/materialized-reports/scope-helpers.js +107 -0
  6. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +251 -0
  7. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +860 -0
  8. package/esm/schemas/models/materialized_tenant_reports_iterations.js +82 -0
  9. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +399 -0
  10. package/esm/schemas/types/materialized_tenant_reports_iterations.js +1 -0
  11. package/esm/schemas/types/materialized_tenant_sales_overview_reports.js +1 -0
  12. package/lib/constants/MATERIALIZED_REPORTS.d.ts +96 -0
  13. package/lib/constants/MATERIALIZED_REPORTS.js +108 -0
  14. package/lib/helpers/materialized-reports/index.d.ts +5 -0
  15. package/lib/helpers/materialized-reports/index.js +21 -0
  16. package/lib/helpers/materialized-reports/key-helpers.d.ts +35 -0
  17. package/lib/helpers/materialized-reports/key-helpers.js +64 -0
  18. package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.d.ts +66 -0
  19. package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +63 -0
  20. package/lib/helpers/materialized-reports/scope-helpers.d.ts +57 -0
  21. package/lib/helpers/materialized-reports/scope-helpers.js +114 -0
  22. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +125 -0
  23. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +256 -0
  24. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +223 -0
  25. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +875 -0
  26. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +80 -0
  27. package/lib/schemas/models/materialized_tenant_reports_iterations.js +85 -0
  28. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +569 -0
  29. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +402 -0
  30. package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +62 -0
  31. package/lib/schemas/types/materialized_tenant_reports_iterations.js +2 -0
  32. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +242 -0
  33. package/lib/schemas/types/materialized_tenant_sales_overview_reports.js +3 -0
  34. package/lib/tests/materialized-reports/fixtures.d.ts +81 -0
  35. package/lib/tests/materialized-reports/fixtures.js +87 -0
  36. package/lib/tests/materialized-reports/fixtures.test.d.ts +1 -0
  37. package/lib/tests/materialized-reports/fixtures.test.js +123 -0
  38. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.d.ts +1 -0
  39. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.js +75 -0
  40. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.d.ts +1 -0
  41. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +73 -0
  42. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.d.ts +1 -0
  43. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +207 -0
  44. package/lib/tests/materialized-reports/sales-overview-baseline.test.d.ts +1 -0
  45. package/lib/tests/materialized-reports/sales-overview-baseline.test.js +326 -0
  46. package/lib/tests/materialized-reports/sales-overview-reference.d.ts +63 -0
  47. package/lib/tests/materialized-reports/sales-overview-reference.js +131 -0
  48. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.d.ts +1 -0
  49. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +335 -0
  50. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.d.ts +1 -0
  51. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +885 -0
  52. package/package.json +5 -2
@@ -0,0 +1,82 @@
1
+ import { Schema } from 'mongoose';
2
+ import { ALL_MATERIALIZED_REPORT_TYPES } from '../../constants/MATERIALIZED_REPORTS';
3
+ /**
4
+ * Mongoose schema for `materialized_tenant_reports_iterations` — the shared iteration
5
+ * history of every materialized report collection (see
6
+ * `MATERIALIZED_REPORTS.md`, "Iteration history").
7
+ *
8
+ * One append-only row per VERSIONED write of a report document; `snapshot`
9
+ * holds the full report document AFTER the write. `snapshot` is Mixed because
10
+ * the collection serves every report kind (`report_type` discriminates).
11
+ * Received-payment patches that change the ledger are versioned writes too
12
+ * (they bump `iteration` and append rows); no-op patches write nothing.
13
+ * Every row carries the backend-generated `reason` for the audit trail.
14
+ */
15
+ export const MaterializedTenantReportIterationSchema = new Schema({
16
+ _id: {
17
+ type: Schema.Types.ObjectId,
18
+ required: true,
19
+ immutable: true,
20
+ },
21
+ report_type: {
22
+ type: String,
23
+ enum: ALL_MATERIALIZED_REPORT_TYPES,
24
+ required: true,
25
+ immutable: true,
26
+ },
27
+ report_id: {
28
+ type: Schema.Types.ObjectId,
29
+ required: true,
30
+ immutable: true,
31
+ },
32
+ iteration: {
33
+ type: Number,
34
+ required: true,
35
+ min: 1,
36
+ },
37
+ schema_version: {
38
+ type: Number,
39
+ required: true,
40
+ },
41
+ // Why the iteration happened — backend-generated free string, e.g.
42
+ // 'NEW_DAY' | 'RECLOSE' | 'RECONCILE' | 'CREDIT_BILL_COLLECTED'.
43
+ reason: {
44
+ type: String,
45
+ required: true,
46
+ },
47
+ // Full report document as written — polymorphic across report kinds, so
48
+ // untyped/Mixed; narrow by `report_type` (see the type file).
49
+ snapshot: {
50
+ type: Schema.Types.Mixed,
51
+ required: true,
52
+ },
53
+ createdAt: {
54
+ type: Schema.Types.Date,
55
+ required: true,
56
+ default: () => new Date(),
57
+ immutable: true,
58
+ },
59
+ updatedAt: {
60
+ type: Schema.Types.Date,
61
+ required: true,
62
+ default: () => new Date(),
63
+ },
64
+ }, {
65
+ timestamps: true,
66
+ versionKey: false,
67
+ minimize: false,
68
+ });
69
+ export const MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME = 'materialized_tenant_reports_iterations';
70
+ /**
71
+ * Indexes for `materialized_tenant_reports_iterations` (values are Mongo key patterns that
72
+ * can be passed straight to `.hint()`):
73
+ * - `_id`: unique primary key.
74
+ * - `report_id__iteration`: UNIQUE — one row per (report, iteration); serves
75
+ * per-report history reads (`{ report_id }` + `.sort({ iteration: -1 })`;
76
+ * the head row mirrors the live document) and doubles as the idempotent
77
+ * upsert key (`replaceOne({ report_id, iteration }, row, { upsert: true })`).
78
+ */
79
+ export const MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_INDEXES = {
80
+ _id: { _id: 1 }, // Unique Index
81
+ report_id__iteration: { report_id: 1, iteration: -1 }, // unique — one row per (report, iteration)
82
+ };
@@ -0,0 +1,399 @@
1
+ import { Schema } from 'mongoose';
2
+ import { REPORT_SALE_TYPE_ENUM } from '../../constants';
3
+ import { ALL_DAY_INDEX } from '../../constants/ENUMS';
4
+ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, ALL_MATERIALIZED_REPORT_SCOPES, SALES_OVERVIEW_KEY_FILTERS, } from '../../constants/MATERIALIZED_REPORTS';
5
+ /**
6
+ * Mongoose schema for `materialized_tenant_sales_overview_reports` — the
7
+ * materialized Reports > Overview data (one document per tenant × scope
8
+ * context × scope value), maintained by the day-end materialization job and
9
+ * read by the analytics API. Scope slices are stamped from the order's
10
+ * business day (`order.localDate`); hour buckets use the punch hour for sales
11
+ * and the settlement hour for credit-bill collections (see
12
+ * `MATERIALIZED_REPORTS.md`). The report's time-bias toggle (Punched At /
13
+ * `createdAt`) is out of scope. `scope_field` formats are documented on
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.
20
+ */
21
+ /**
22
+ * Version of the key grammar + metric rules of this collection. Bump when
23
+ * `sale_type_key_filters`, their order, or metric semantics change —
24
+ * historical documents must then be re-materialized (readers may branch on
25
+ * this value during a rollout).
26
+ */
27
+ export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION = 1;
28
+ const ReportDiscountByTypeSchema = new Schema({
29
+ special_discount: {
30
+ type: Number, // cents — Σ order_discount_details.special_discount
31
+ required: true,
32
+ },
33
+ loyalty_discount: {
34
+ type: Number, // cents — Σ order_discount_details.loyalty_discount
35
+ required: true,
36
+ },
37
+ voucher_discount: {
38
+ type: Number, // cents — Σ order_discount_details.voucher_discount
39
+ required: true,
40
+ },
41
+ }, { _id: false, minimize: false });
42
+ const ReportOrderMetricSchema = new Schema({
43
+ count: {
44
+ type: Number,
45
+ required: true,
46
+ min: 0,
47
+ },
48
+ gross_amount: {
49
+ type: Number, // cents — Σ amount_earned of the bucket's orders
50
+ required: true,
51
+ },
52
+ discount_amount: {
53
+ type: Number, // cents — Σ total_discount_applied
54
+ required: true,
55
+ },
56
+ discount_by_type: {
57
+ type: ReportDiscountByTypeSchema,
58
+ required: true,
59
+ },
60
+ gst_amount: {
61
+ type: Number, // cents — Σ gst_amount
62
+ required: true,
63
+ },
64
+ tax_amount: {
65
+ type: Number, // cents — Σ tax_amount
66
+ required: true,
67
+ },
68
+ tip_amount: {
69
+ type: Number, // cents — Σ tip_amount
70
+ required: true,
71
+ },
72
+ tax_invoice_provider_charges: {
73
+ type: Number, // cents — Σ tax_invoice_provider_charges
74
+ required: true,
75
+ },
76
+ delivery_charges: {
77
+ type: Number, // cents — Σ delivery_details.delivery_cost
78
+ required: true,
79
+ },
80
+ }, { _id: false, minimize: false });
81
+ const ReportPaymentMetricSchema = new Schema({
82
+ payment_type: {
83
+ type: String,
84
+ // enum: ALL_PAYMENT_TYPE_NAMES, — intentionally NOT enforced: live stores
85
+ // contain legacy/aggregator values (CARD_PAYMENT, FOODPANDA, PLAZA, …)
86
+ // that must pass through reporting untouched.
87
+ required: true,
88
+ },
89
+ count: {
90
+ type: Number,
91
+ required: true,
92
+ min: 0,
93
+ },
94
+ gross_amount: {
95
+ type: Number, // cents — net of refunds & card charges; may be negative
96
+ required: true,
97
+ },
98
+ amount_due: {
99
+ type: Number,
100
+ required: true,
101
+ min: 0,
102
+ },
103
+ amount_paid: {
104
+ type: Number,
105
+ required: true,
106
+ min: 0,
107
+ },
108
+ amount_refunded: {
109
+ type: Number,
110
+ required: true,
111
+ min: 0,
112
+ },
113
+ card_charges: {
114
+ type: Number,
115
+ required: true,
116
+ min: 0,
117
+ },
118
+ }, { _id: false, minimize: false });
119
+ const ReportSaleTypeMetricSchema = new Schema({
120
+ orders: {
121
+ type: ReportOrderMetricSchema,
122
+ required: true,
123
+ },
124
+ payments: {
125
+ type: [ReportPaymentMetricSchema],
126
+ default: [],
127
+ },
128
+ }, { _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 });
200
+ const ReportCreditBillsSchema = new Schema({
201
+ issued: {
202
+ count: {
203
+ type: Number,
204
+ required: true,
205
+ min: 0,
206
+ default: 0,
207
+ },
208
+ amount: {
209
+ type: Number,
210
+ required: true,
211
+ default: 0,
212
+ },
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).
215
+ settled_count: {
216
+ type: Number,
217
+ required: true,
218
+ min: 0,
219
+ default: 0,
220
+ },
221
+ settled_amount: {
222
+ type: Number,
223
+ required: true,
224
+ default: 0,
225
+ },
226
+ bills: {
227
+ type: [ReportCreditBillSchema],
228
+ default: [],
229
+ },
230
+ },
231
+ received: {
232
+ count: {
233
+ type: Number,
234
+ required: true,
235
+ min: 0,
236
+ default: 0,
237
+ },
238
+ amount: {
239
+ type: Number,
240
+ required: true,
241
+ default: 0,
242
+ },
243
+ bills: {
244
+ type: [ReportReceivedCreditBillSchema],
245
+ default: [],
246
+ },
247
+ },
248
+ }, { _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
+ const ReportKeyMetricsSchema = new Schema({
253
+ [REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: {
254
+ type: ReportSaleTypeMetricSchema,
255
+ required: true,
256
+ },
257
+ [REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED]: {
258
+ type: ReportSaleTypeMetricSchema,
259
+ required: true,
260
+ },
261
+ [REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: {
262
+ type: ReportCreditBillsSchema,
263
+ required: true,
264
+ default: () => ({
265
+ issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0, bills: [] },
266
+ received: { count: 0, amount: 0, bills: [] },
267
+ }),
268
+ },
269
+ }, { _id: false, minimize: false });
270
+ export const MaterializedTenantSalesOverviewReportSchema = new Schema({
271
+ _id: {
272
+ type: Schema.Types.ObjectId,
273
+ required: true,
274
+ immutable: true,
275
+ },
276
+ tenant_id: {
277
+ type: String,
278
+ required: true,
279
+ immutable: true,
280
+ ref: 'tenants',
281
+ },
282
+ brand_id: {
283
+ type: String,
284
+ required: true,
285
+ },
286
+ scope_context: {
287
+ type: String,
288
+ enum: ALL_MATERIALIZED_REPORT_SCOPES,
289
+ required: true,
290
+ },
291
+ scope_field: {
292
+ type: String, // format depends on scope_context — see MATERIALIZED_REPORT_SCOPE_ENUM
293
+ required: true,
294
+ },
295
+ // Denormalized weekday of scope_field — set ONLY on LOCAL_HOUR /
296
+ // LOCAL_DATE documents (MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX);
297
+ // null elsewhere. Weekday analysis reads date/hour slices instead of an
298
+ // all-time accumulator document (see MATERIALIZED_REPORTS.md).
299
+ day_index: {
300
+ type: String,
301
+ enum: ALL_DAY_INDEX,
302
+ default: null,
303
+ },
304
+ sale_type_key_filters: {
305
+ type: [String],
306
+ enum: ALL_MATERIALIZED_REPORT_KEY_FILTERS,
307
+ required: true,
308
+ default: () => [...SALES_OVERVIEW_KEY_FILTERS],
309
+ },
310
+ // Map key = the ordered filter combination, e.g. "PLACED:POS_WALK-IN" —
311
+ // the grammar is declared by `sale_type_key_filters` and must be built /
312
+ // parsed through the shared key helper, never ad hoc.
313
+ sale_type_metrics: {
314
+ type: Map,
315
+ of: ReportKeyMetricsSchema,
316
+ required: true,
317
+ default: {},
318
+ },
319
+ // 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.
325
+ iteration: {
326
+ type: Number,
327
+ required: true,
328
+ min: 1,
329
+ default: 1,
330
+ },
331
+ schema_version: {
332
+ type: Number,
333
+ required: true,
334
+ immutable: true,
335
+ default: MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_SCHEMA_VERSION,
336
+ },
337
+ source_watermark: {
338
+ type: Schema.Types.Date,
339
+ required: true,
340
+ },
341
+ computed_at: {
342
+ type: Schema.Types.Date,
343
+ required: true,
344
+ },
345
+ createdAt: {
346
+ type: Schema.Types.Date,
347
+ required: true,
348
+ default: () => new Date(),
349
+ immutable: true,
350
+ },
351
+ updatedAt: {
352
+ type: Schema.Types.Date,
353
+ required: true,
354
+ default: () => new Date(),
355
+ },
356
+ }, {
357
+ timestamps: true,
358
+ versionKey: false,
359
+ minimize: false,
360
+ });
361
+ export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME = 'materialized_tenant_sales_overview_reports';
362
+ /**
363
+ * Describes the indexes for `materialized_tenant_sales_overview_reports`.
364
+ * Values are Mongo key patterns that can be passed straight to `.hint()`.
365
+ * - `_id`: unique primary key.
366
+ * - `tenant_id__scope_context__scope_field`: UNIQUE index — one document per
367
+ * (tenant, scope context, scope value); also serves the standardized query
368
+ * (`tenant_id` + `scope_context` + `scope_field`).
369
+ * - `brand_id__scope_context__scope_field`: brand-level reads across the
370
+ * brand's tenants (sum across their tenant documents).
371
+ * - `tenant_id__scope_context__day_index__scope_field` (+ brand variant):
372
+ * weekday queries over LOCAL_HOUR / LOCAL_DATE slices
373
+ * (`day_index` + `scope_field` range).
374
+ */
375
+ export const MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_INDEXES = {
376
+ _id: { _id: 1 }, // Unique Index
377
+ tenant_id__scope_context__scope_field: {
378
+ tenant_id: 1,
379
+ scope_context: 1,
380
+ scope_field: 1,
381
+ }, // unique — one document per (tenant, scope context, scope value)
382
+ brand_id__scope_context__scope_field: {
383
+ brand_id: 1,
384
+ scope_context: 1,
385
+ scope_field: 1,
386
+ }, // brand-level reads across the brand's tenants
387
+ tenant_id__scope_context__scope_field__day_index: {
388
+ tenant_id: 1,
389
+ scope_context: 1,
390
+ scope_field: 1,
391
+ day_index: 1,
392
+ }, // weekday queries over LOCAL_HOUR / LOCAL_DATE slices
393
+ brand_id__scope_context__scope_field__day_index: {
394
+ brand_id: 1,
395
+ scope_context: 1,
396
+ scope_field: 1,
397
+ day_index: 1,
398
+ }, // brand-level weekday queries over LOCAL_HOUR / LOCAL_DATE slices
399
+ };
@@ -0,0 +1 @@
1
+ import { REPORT_SALE_TYPE_ENUM } from '../../constants';
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Constants for the `materialized_*` report collections (see
3
+ * `MATERIALIZED_REPORTS.md`).
4
+ *
5
+ * NOTE: during the current development phase the materialized-report files
6
+ * stay self-contained — this file is NOT (yet) re-exported from
7
+ * `src/constants/index.ts`; the report schema/type files import it via
8
+ * relative paths. Wiring re-exports into the barrels is a separate,
9
+ * explicitly-enabled step.
10
+ */
11
+ /**
12
+ * Time-scope of a materialized report document. Every document covers exactly
13
+ * one tenant × one scope context × one scope value (`scope_field`), and the
14
+ * same scope set is shared by every materialized report collection.
15
+ *
16
+ * `scope_field` formats (all strings), derived from the existing toolkit time
17
+ * helpers (`getLocalDocumentFields`, `getIsoWeekOfYear`, `getCalendarWeekStart`)
18
+ * for the order's business day (`order.localDate`) — hours use the PUNCH hour
19
+ * for sales and the SETTLEMENT hour for credit-bill collections:
20
+ * - `LOCAL_HOUR`: 'YYYY-MM-DD HH' — e.g. '2026-09-15 18' (one hour of one day)
21
+ * - `LOCAL_DATE`: 'YYYY-MM-DD' — e.g. '2026-09-15'
22
+ * - `LOCAL_WEEK`: 'YYYY-MM-DD' — week start (Sun–Sat, the calendar UI's
23
+ * convention: `getCalendarWeekStart(date, 0)`)
24
+ * - `LOCAL_WEEK_OF_YEAR`: 'YYYY-Wnn' — ISO week (`getIsoWeekOfYear`); `YYYY` is the
25
+ * ISO week-year for boundary weeks
26
+ * - `LOCAL_MONTH`: 'YYYY-MM' — e.g. '2026-09'
27
+ * - `LOCAL_QUARTER`: 'YYYY-Qn' — e.g. '2026-Q3'
28
+ * - `LOCAL_SEMESTER`: 'YYYY-Sn' — e.g. '2026-S2'
29
+ * - `LOCAL_YEAR`: 'YYYY' — e.g. '2026'
30
+ *
31
+ * `DAY_INDEX` is intentionally NOT a scope: a weekday accumulator has no time
32
+ * anchor — it cannot honor date-range filters and would grow forever. Instead,
33
+ * `LOCAL_HOUR` and `LOCAL_DATE` documents carry a denormalized `day_index`
34
+ * field (`DAY_INDEX_ENUM`) so weekday filtering/grouping is a plain query over
35
+ * the date/hour slices (see `MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX`).
36
+ *
37
+ * The day-end materialization job compiles the tenant's day into the report
38
+ * collections: up to 24 `LOCAL_HOUR` documents plus one document for each
39
+ * other scope (31 per tenant-day; the longer-period documents accumulate until
40
+ * their period ends). Changing scope values or their formats requires a
41
+ * `schema_version` bump and re-materialization of history.
42
+ */
43
+ export declare enum MATERIALIZED_REPORT_SCOPE_ENUM {
44
+ LOCAL_HOUR = "localHour",
45
+ LOCAL_DATE = "localDate",
46
+ LOCAL_WEEK = "localWeek",
47
+ LOCAL_WEEK_OF_YEAR = "localWeekOfYear",
48
+ LOCAL_MONTH = "localMonth",
49
+ LOCAL_QUARTER = "localQuarter",
50
+ LOCAL_SEMESTER = "localSemester",
51
+ LOCAL_YEAR = "localYear"
52
+ }
53
+ export declare const ALL_MATERIALIZED_REPORT_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
54
+ /**
55
+ * Scopes whose documents carry the denormalized `day_index` weekday field
56
+ * (derived from `scope_field` by the materializer, `DAY_INDEX_ENUM`). All
57
+ * other scopes must leave it `null` — weekday analysis reads date/hour slices
58
+ * (`LOCAL_HOUR` / `LOCAL_DATE`) instead of an all-time accumulator document.
59
+ */
60
+ export declare const MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX: MATERIALIZED_REPORT_SCOPE_ENUM[];
61
+ /**
62
+ * Filter dimensions that can be encoded into the metric keys of a materialized
63
+ * report document (`sale_type_metrics`). The declaration order defines the key
64
+ * grammar: `<DIM_1>:<DIM_2>:...` built from raw enum/live string values
65
+ * (e.g. `PLACED:POS_WALK-IN`). Changing the dimensions or their order requires
66
+ * a `schema_version` bump and re-materialization of historical documents.
67
+ */
68
+ export declare enum MATERIALIZED_REPORT_KEY_FILTER_ENUM {
69
+ ORDER_STATUS = "ORDER_STATUS",
70
+ PLATFORM = "PLATFORM"
71
+ }
72
+ export declare const ALL_MATERIALIZED_REPORT_KEY_FILTERS: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
73
+ /** Ordered key filters of the tenant sales overview report (`PLACED:POS_WALK-IN`). */
74
+ export declare const SALES_OVERVIEW_KEY_FILTERS: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
75
+ /**
76
+ * Payment-type label used by the frontend report formatter for the derived
77
+ * credit-settlement line in a collection day's payments breakdown (a
78
+ * `PAY_LATER` bill collected on a later day). NOT stored in materialized docs —
79
+ * the formatter composes the line from the `CREDIT_BILLS` ledger's `received`
80
+ * bucket. The line is excluded from method buckets (CASH/CARD/…) and never
81
+ * feeds gross: gross stays sales-only, so cross-day gross sums stay equal to
82
+ * total sales.
83
+ */
84
+ export declare const MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = "CREDIT_SETTLEMENT";
85
+ /**
86
+ * Materialized report kinds — the discriminator stored on
87
+ * `materialized_tenant_reports_iterations` rows. A single shared history collection records
88
+ * the structural iterations of EVERY materialized report, so each row must
89
+ * declare which report collection its `report_id` belongs to. Add one member
90
+ * per new report collection (Summary / X / Z / Riders / Items / Void Items …)
91
+ * as it lands.
92
+ */
93
+ export declare enum MATERIALIZED_REPORT_TYPE_ENUM {
94
+ TENANT_SALES_OVERVIEW = "TENANT_SALES_OVERVIEW"
95
+ }
96
+ export declare const ALL_MATERIALIZED_REPORT_TYPES: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_SALES_OVERVIEW[];
@@ -0,0 +1,108 @@
1
+ "use strict";
2
+ /**
3
+ * Constants for the `materialized_*` report collections (see
4
+ * `MATERIALIZED_REPORTS.md`).
5
+ *
6
+ * NOTE: during the current development phase the materialized-report files
7
+ * stay self-contained — this file is NOT (yet) re-exported from
8
+ * `src/constants/index.ts`; the report schema/type files import it via
9
+ * relative paths. Wiring re-exports into the barrels is a separate,
10
+ * explicitly-enabled step.
11
+ */
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;
14
+ /**
15
+ * Time-scope of a materialized report document. Every document covers exactly
16
+ * one tenant × one scope context × one scope value (`scope_field`), and the
17
+ * same scope set is shared by every materialized report collection.
18
+ *
19
+ * `scope_field` formats (all strings), derived from the existing toolkit time
20
+ * helpers (`getLocalDocumentFields`, `getIsoWeekOfYear`, `getCalendarWeekStart`)
21
+ * for the order's business day (`order.localDate`) — hours use the PUNCH hour
22
+ * for sales and the SETTLEMENT hour for credit-bill collections:
23
+ * - `LOCAL_HOUR`: 'YYYY-MM-DD HH' — e.g. '2026-09-15 18' (one hour of one day)
24
+ * - `LOCAL_DATE`: 'YYYY-MM-DD' — e.g. '2026-09-15'
25
+ * - `LOCAL_WEEK`: 'YYYY-MM-DD' — week start (Sun–Sat, the calendar UI's
26
+ * convention: `getCalendarWeekStart(date, 0)`)
27
+ * - `LOCAL_WEEK_OF_YEAR`: 'YYYY-Wnn' — ISO week (`getIsoWeekOfYear`); `YYYY` is the
28
+ * ISO week-year for boundary weeks
29
+ * - `LOCAL_MONTH`: 'YYYY-MM' — e.g. '2026-09'
30
+ * - `LOCAL_QUARTER`: 'YYYY-Qn' — e.g. '2026-Q3'
31
+ * - `LOCAL_SEMESTER`: 'YYYY-Sn' — e.g. '2026-S2'
32
+ * - `LOCAL_YEAR`: 'YYYY' — e.g. '2026'
33
+ *
34
+ * `DAY_INDEX` is intentionally NOT a scope: a weekday accumulator has no time
35
+ * anchor — it cannot honor date-range filters and would grow forever. Instead,
36
+ * `LOCAL_HOUR` and `LOCAL_DATE` documents carry a denormalized `day_index`
37
+ * field (`DAY_INDEX_ENUM`) so weekday filtering/grouping is a plain query over
38
+ * the date/hour slices (see `MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX`).
39
+ *
40
+ * The day-end materialization job compiles the tenant's day into the report
41
+ * collections: up to 24 `LOCAL_HOUR` documents plus one document for each
42
+ * other scope (31 per tenant-day; the longer-period documents accumulate until
43
+ * their period ends). Changing scope values or their formats requires a
44
+ * `schema_version` bump and re-materialization of history.
45
+ */
46
+ var MATERIALIZED_REPORT_SCOPE_ENUM;
47
+ (function (MATERIALIZED_REPORT_SCOPE_ENUM) {
48
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_HOUR"] = "localHour";
49
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_DATE"] = "localDate";
50
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_WEEK"] = "localWeek";
51
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_WEEK_OF_YEAR"] = "localWeekOfYear";
52
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_MONTH"] = "localMonth";
53
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_QUARTER"] = "localQuarter";
54
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_SEMESTER"] = "localSemester";
55
+ MATERIALIZED_REPORT_SCOPE_ENUM["LOCAL_YEAR"] = "localYear";
56
+ })(MATERIALIZED_REPORT_SCOPE_ENUM || (exports.MATERIALIZED_REPORT_SCOPE_ENUM = MATERIALIZED_REPORT_SCOPE_ENUM = {}));
57
+ exports.ALL_MATERIALIZED_REPORT_SCOPES = Object.values(MATERIALIZED_REPORT_SCOPE_ENUM);
58
+ /**
59
+ * Scopes whose documents carry the denormalized `day_index` weekday field
60
+ * (derived from `scope_field` by the materializer, `DAY_INDEX_ENUM`). All
61
+ * other scopes must leave it `null` — weekday analysis reads date/hour slices
62
+ * (`LOCAL_HOUR` / `LOCAL_DATE`) instead of an all-time accumulator document.
63
+ */
64
+ exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = [
65
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR,
66
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
67
+ ];
68
+ /**
69
+ * Filter dimensions that can be encoded into the metric keys of a materialized
70
+ * report document (`sale_type_metrics`). The declaration order defines the key
71
+ * grammar: `<DIM_1>:<DIM_2>:...` built from raw enum/live string values
72
+ * (e.g. `PLACED:POS_WALK-IN`). Changing the dimensions or their order requires
73
+ * a `schema_version` bump and re-materialization of historical documents.
74
+ */
75
+ var MATERIALIZED_REPORT_KEY_FILTER_ENUM;
76
+ (function (MATERIALIZED_REPORT_KEY_FILTER_ENUM) {
77
+ MATERIALIZED_REPORT_KEY_FILTER_ENUM["ORDER_STATUS"] = "ORDER_STATUS";
78
+ MATERIALIZED_REPORT_KEY_FILTER_ENUM["PLATFORM"] = "PLATFORM";
79
+ })(MATERIALIZED_REPORT_KEY_FILTER_ENUM || (exports.MATERIALIZED_REPORT_KEY_FILTER_ENUM = MATERIALIZED_REPORT_KEY_FILTER_ENUM = {}));
80
+ exports.ALL_MATERIALIZED_REPORT_KEY_FILTERS = Object.values(MATERIALIZED_REPORT_KEY_FILTER_ENUM);
81
+ /** Ordered key filters of the tenant sales overview report (`PLACED:POS_WALK-IN`). */
82
+ exports.SALES_OVERVIEW_KEY_FILTERS = [
83
+ MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
84
+ MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM,
85
+ ];
86
+ /**
87
+ * Payment-type label used by the frontend report formatter for the derived
88
+ * credit-settlement line in a collection day's payments breakdown (a
89
+ * `PAY_LATER` bill collected on a later day). NOT stored in materialized docs —
90
+ * the formatter composes the line from the `CREDIT_BILLS` ledger's `received`
91
+ * bucket. The line is excluded from method buckets (CASH/CARD/…) and never
92
+ * feeds gross: gross stays sales-only, so cross-day gross sums stay equal to
93
+ * total sales.
94
+ */
95
+ exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = 'CREDIT_SETTLEMENT';
96
+ /**
97
+ * Materialized report kinds — the discriminator stored on
98
+ * `materialized_tenant_reports_iterations` rows. A single shared history collection records
99
+ * the structural iterations of EVERY materialized report, so each row must
100
+ * declare which report collection its `report_id` belongs to. Add one member
101
+ * per new report collection (Summary / X / Z / Riders / Items / Void Items …)
102
+ * as it lands.
103
+ */
104
+ var MATERIALIZED_REPORT_TYPE_ENUM;
105
+ (function (MATERIALIZED_REPORT_TYPE_ENUM) {
106
+ MATERIALIZED_REPORT_TYPE_ENUM["TENANT_SALES_OVERVIEW"] = "TENANT_SALES_OVERVIEW";
107
+ })(MATERIALIZED_REPORT_TYPE_ENUM || (exports.MATERIALIZED_REPORT_TYPE_ENUM = MATERIALIZED_REPORT_TYPE_ENUM = {}));
108
+ exports.ALL_MATERIALIZED_REPORT_TYPES = Object.values(MATERIALIZED_REPORT_TYPE_ENUM);