@managesome/eposmatic-toolkit 0.3.11 → 0.4.1

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 (71) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +105 -0
  2. package/esm/constants/index.js +1 -0
  3. package/esm/helpers/index.js +1 -0
  4. package/esm/helpers/materialized-reports/index.js +5 -0
  5. package/esm/helpers/materialized-reports/key-helpers.js +59 -0
  6. package/esm/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +60 -0
  7. package/esm/helpers/materialized-reports/scope-helpers.js +107 -0
  8. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +251 -0
  9. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +860 -0
  10. package/esm/schemas/models/index.js +2 -0
  11. package/esm/schemas/models/materialized_tenant_reports_iterations.js +82 -0
  12. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +399 -0
  13. package/esm/schemas/types/index.js +2 -0
  14. package/esm/schemas/types/materialized_tenant_reports_iterations.js +1 -0
  15. package/esm/schemas/types/materialized_tenant_sales_overview_reports.js +1 -0
  16. package/lib/constants/MATERIALIZED_REPORTS.d.ts +96 -0
  17. package/lib/constants/MATERIALIZED_REPORTS.js +108 -0
  18. package/lib/constants/index.d.ts +1 -0
  19. package/lib/constants/index.js +1 -0
  20. package/lib/helpers/index.d.ts +1 -0
  21. package/lib/helpers/index.js +1 -0
  22. package/lib/helpers/materialized-reports/index.d.ts +5 -0
  23. package/lib/helpers/materialized-reports/index.js +21 -0
  24. package/lib/helpers/materialized-reports/key-helpers.d.ts +35 -0
  25. package/lib/helpers/materialized-reports/key-helpers.js +64 -0
  26. package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.d.ts +66 -0
  27. package/lib/helpers/materialized-reports/materialized-tenant-reports-iterations-helpers.js +63 -0
  28. package/lib/helpers/materialized-reports/scope-helpers.d.ts +57 -0
  29. package/lib/helpers/materialized-reports/scope-helpers.js +114 -0
  30. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +125 -0
  31. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +256 -0
  32. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +223 -0
  33. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +875 -0
  34. package/lib/schemas/models/index.d.ts +2 -0
  35. package/lib/schemas/models/index.js +2 -0
  36. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +80 -0
  37. package/lib/schemas/models/materialized_tenant_reports_iterations.js +85 -0
  38. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +569 -0
  39. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +402 -0
  40. package/lib/schemas/models/orders.d.ts +24 -24
  41. package/lib/schemas/models/tenant_active_jobs.d.ts +3 -3
  42. package/lib/schemas/models/tenant_calendar.d.ts +3 -3
  43. package/lib/schemas/models/tenant_cash_drawer_sessions.d.ts +24 -24
  44. package/lib/schemas/models/tenant_cash_in_out.d.ts +24 -24
  45. package/lib/schemas/models/tenant_day_sessions.d.ts +24 -24
  46. package/lib/schemas/models/tenant_instore_shift_sessions.d.ts +24 -24
  47. package/lib/schemas/types/index.d.ts +2 -0
  48. package/lib/schemas/types/index.js +2 -0
  49. package/lib/schemas/types/materialized_tenant_reports_iterations.d.ts +62 -0
  50. package/lib/schemas/types/materialized_tenant_reports_iterations.js +2 -0
  51. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +242 -0
  52. package/lib/schemas/types/materialized_tenant_sales_overview_reports.js +3 -0
  53. package/lib/tests/materialized-reports/fixtures.d.ts +81 -0
  54. package/lib/tests/materialized-reports/fixtures.js +87 -0
  55. package/lib/tests/materialized-reports/fixtures.test.d.ts +1 -0
  56. package/lib/tests/materialized-reports/fixtures.test.js +123 -0
  57. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.d.ts +1 -0
  58. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-helpers.test.js +75 -0
  59. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.d.ts +1 -0
  60. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +73 -0
  61. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.d.ts +1 -0
  62. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +207 -0
  63. package/lib/tests/materialized-reports/sales-overview-baseline.test.d.ts +1 -0
  64. package/lib/tests/materialized-reports/sales-overview-baseline.test.js +326 -0
  65. package/lib/tests/materialized-reports/sales-overview-reference.d.ts +63 -0
  66. package/lib/tests/materialized-reports/sales-overview-reference.js +131 -0
  67. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.d.ts +1 -0
  68. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +335 -0
  69. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.d.ts +1 -0
  70. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +885 -0
  71. package/package.json +5 -2
@@ -7,6 +7,14 @@ export declare const TenantCashInOutSchema: Schema<any, import("mongoose").Model
7
7
  createdAt: NativeDate;
8
8
  updatedAt: NativeDate;
9
9
  } & {
10
+ localHour: number;
11
+ localDate: string;
12
+ localWeek: number;
13
+ localWeekOfYear: number;
14
+ localMonth: number;
15
+ localQuarter: number;
16
+ localSemester: number;
17
+ localYear: number;
10
18
  _id: import("mongoose").Types.ObjectId;
11
19
  type: import("../../constants").CASH_IN_OUT_TYPE_ENUM;
12
20
  tenant_id: string;
@@ -18,18 +26,10 @@ export declare const TenantCashInOutSchema: Schema<any, import("mongoose").Model
18
26
  ref_type: import("../../constants").CASH_IN_OUT_REF_ENUM;
19
27
  ref_id: import("mongoose").Types.ObjectId;
20
28
  amount: number;
21
- localYear: number;
22
- localMonth: number;
23
29
  localDay: number;
24
30
  day_index: import("../../constants").DAY_INDEX_ENUM;
25
31
  localSecond: number;
26
32
  localMinute: number;
27
- localHour: number;
28
- localWeek: number;
29
- localWeekOfYear: number;
30
- localQuarter: number;
31
- localSemester: number;
32
- localDate: string;
33
33
  localTime: string;
34
34
  localDayOfYear: number;
35
35
  day_id: import("mongoose").Types.ObjectId;
@@ -42,6 +42,14 @@ export declare const TenantCashInOutSchema: Schema<any, import("mongoose").Model
42
42
  createdAt: NativeDate;
43
43
  updatedAt: NativeDate;
44
44
  } & {
45
+ localHour: number;
46
+ localDate: string;
47
+ localWeek: number;
48
+ localWeekOfYear: number;
49
+ localMonth: number;
50
+ localQuarter: number;
51
+ localSemester: number;
52
+ localYear: number;
45
53
  _id: import("mongoose").Types.ObjectId;
46
54
  type: import("../../constants").CASH_IN_OUT_TYPE_ENUM;
47
55
  tenant_id: string;
@@ -53,18 +61,10 @@ export declare const TenantCashInOutSchema: Schema<any, import("mongoose").Model
53
61
  ref_type: import("../../constants").CASH_IN_OUT_REF_ENUM;
54
62
  ref_id: import("mongoose").Types.ObjectId;
55
63
  amount: number;
56
- localYear: number;
57
- localMonth: number;
58
64
  localDay: number;
59
65
  day_index: import("../../constants").DAY_INDEX_ENUM;
60
66
  localSecond: number;
61
67
  localMinute: number;
62
- localHour: number;
63
- localWeek: number;
64
- localWeekOfYear: number;
65
- localQuarter: number;
66
- localSemester: number;
67
- localDate: string;
68
68
  localTime: string;
69
69
  localDayOfYear: number;
70
70
  day_id: import("mongoose").Types.ObjectId;
@@ -77,6 +77,14 @@ export declare const TenantCashInOutSchema: Schema<any, import("mongoose").Model
77
77
  createdAt: NativeDate;
78
78
  updatedAt: NativeDate;
79
79
  } & {
80
+ localHour: number;
81
+ localDate: string;
82
+ localWeek: number;
83
+ localWeekOfYear: number;
84
+ localMonth: number;
85
+ localQuarter: number;
86
+ localSemester: number;
87
+ localYear: number;
80
88
  _id: import("mongoose").Types.ObjectId;
81
89
  type: import("../../constants").CASH_IN_OUT_TYPE_ENUM;
82
90
  tenant_id: string;
@@ -88,18 +96,10 @@ export declare const TenantCashInOutSchema: Schema<any, import("mongoose").Model
88
96
  ref_type: import("../../constants").CASH_IN_OUT_REF_ENUM;
89
97
  ref_id: import("mongoose").Types.ObjectId;
90
98
  amount: number;
91
- localYear: number;
92
- localMonth: number;
93
99
  localDay: number;
94
100
  day_index: import("../../constants").DAY_INDEX_ENUM;
95
101
  localSecond: number;
96
102
  localMinute: number;
97
- localHour: number;
98
- localWeek: number;
99
- localWeekOfYear: number;
100
- localQuarter: number;
101
- localSemester: number;
102
- localDate: string;
103
103
  localTime: string;
104
104
  localDayOfYear: number;
105
105
  day_id: import("mongoose").Types.ObjectId;
@@ -7,23 +7,23 @@ export declare const TenantDaySessionSchema: Schema<any, import("mongoose").Mode
7
7
  createdAt: NativeDate;
8
8
  updatedAt: NativeDate;
9
9
  } & {
10
+ localHour: number;
11
+ localDate: string;
12
+ localWeek: number;
13
+ localWeekOfYear: number;
14
+ localMonth: number;
15
+ localQuarter: number;
16
+ localSemester: number;
17
+ localYear: number;
10
18
  _id: import("mongoose").Types.ObjectId;
11
19
  tenant_id: string;
12
20
  createdAt: NativeDate;
13
21
  updatedAt: NativeDate;
14
22
  status: import("../../constants").POS_DAY_STATUS_ENUM;
15
- localYear: number;
16
- localMonth: number;
17
23
  localDay: number;
18
24
  day_index: import("../../constants").DAY_INDEX_ENUM;
19
25
  localSecond: number;
20
26
  localMinute: number;
21
- localHour: number;
22
- localWeek: number;
23
- localWeekOfYear: number;
24
- localQuarter: number;
25
- localSemester: number;
26
- localDate: string;
27
27
  localTime: string;
28
28
  localDayOfYear: number;
29
29
  opening: {
@@ -119,23 +119,23 @@ export declare const TenantDaySessionSchema: Schema<any, import("mongoose").Mode
119
119
  createdAt: NativeDate;
120
120
  updatedAt: NativeDate;
121
121
  } & {
122
+ localHour: number;
123
+ localDate: string;
124
+ localWeek: number;
125
+ localWeekOfYear: number;
126
+ localMonth: number;
127
+ localQuarter: number;
128
+ localSemester: number;
129
+ localYear: number;
122
130
  _id: import("mongoose").Types.ObjectId;
123
131
  tenant_id: string;
124
132
  createdAt: NativeDate;
125
133
  updatedAt: NativeDate;
126
134
  status: import("../../constants").POS_DAY_STATUS_ENUM;
127
- localYear: number;
128
- localMonth: number;
129
135
  localDay: number;
130
136
  day_index: import("../../constants").DAY_INDEX_ENUM;
131
137
  localSecond: number;
132
138
  localMinute: number;
133
- localHour: number;
134
- localWeek: number;
135
- localWeekOfYear: number;
136
- localQuarter: number;
137
- localSemester: number;
138
- localDate: string;
139
139
  localTime: string;
140
140
  localDayOfYear: number;
141
141
  opening: {
@@ -231,23 +231,23 @@ export declare const TenantDaySessionSchema: Schema<any, import("mongoose").Mode
231
231
  createdAt: NativeDate;
232
232
  updatedAt: NativeDate;
233
233
  } & {
234
+ localHour: number;
235
+ localDate: string;
236
+ localWeek: number;
237
+ localWeekOfYear: number;
238
+ localMonth: number;
239
+ localQuarter: number;
240
+ localSemester: number;
241
+ localYear: number;
234
242
  _id: import("mongoose").Types.ObjectId;
235
243
  tenant_id: string;
236
244
  createdAt: NativeDate;
237
245
  updatedAt: NativeDate;
238
246
  status: import("../../constants").POS_DAY_STATUS_ENUM;
239
- localYear: number;
240
- localMonth: number;
241
247
  localDay: number;
242
248
  day_index: import("../../constants").DAY_INDEX_ENUM;
243
249
  localSecond: number;
244
250
  localMinute: number;
245
- localHour: number;
246
- localWeek: number;
247
- localWeekOfYear: number;
248
- localQuarter: number;
249
- localSemester: number;
250
- localDate: string;
251
251
  localTime: string;
252
252
  localDayOfYear: number;
253
253
  opening: {
@@ -7,23 +7,23 @@ export declare const TenantInstoreShiftSessionSchema: Schema<any, import("mongoo
7
7
  createdAt: NativeDate;
8
8
  updatedAt: NativeDate;
9
9
  } & {
10
+ localHour: number;
11
+ localDate: string;
12
+ localWeek: number;
13
+ localWeekOfYear: number;
14
+ localMonth: number;
15
+ localQuarter: number;
16
+ localSemester: number;
17
+ localYear: number;
10
18
  _id: import("mongoose").Types.ObjectId;
11
19
  tenant_id: string;
12
20
  createdAt: NativeDate;
13
21
  updatedAt: NativeDate;
14
22
  status: import("../../constants").POS_SHIFT_STATUS_ENUM;
15
- localYear: number;
16
- localMonth: number;
17
23
  localDay: number;
18
24
  day_index: import("../../constants").DAY_INDEX_ENUM;
19
25
  localSecond: number;
20
26
  localMinute: number;
21
- localHour: number;
22
- localWeek: number;
23
- localWeekOfYear: number;
24
- localQuarter: number;
25
- localSemester: number;
26
- localDate: string;
27
27
  localTime: string;
28
28
  localDayOfYear: number;
29
29
  day_id: import("mongoose").Types.ObjectId;
@@ -130,23 +130,23 @@ export declare const TenantInstoreShiftSessionSchema: Schema<any, import("mongoo
130
130
  createdAt: NativeDate;
131
131
  updatedAt: NativeDate;
132
132
  } & {
133
+ localHour: number;
134
+ localDate: string;
135
+ localWeek: number;
136
+ localWeekOfYear: number;
137
+ localMonth: number;
138
+ localQuarter: number;
139
+ localSemester: number;
140
+ localYear: number;
133
141
  _id: import("mongoose").Types.ObjectId;
134
142
  tenant_id: string;
135
143
  createdAt: NativeDate;
136
144
  updatedAt: NativeDate;
137
145
  status: import("../../constants").POS_SHIFT_STATUS_ENUM;
138
- localYear: number;
139
- localMonth: number;
140
146
  localDay: number;
141
147
  day_index: import("../../constants").DAY_INDEX_ENUM;
142
148
  localSecond: number;
143
149
  localMinute: number;
144
- localHour: number;
145
- localWeek: number;
146
- localWeekOfYear: number;
147
- localQuarter: number;
148
- localSemester: number;
149
- localDate: string;
150
150
  localTime: string;
151
151
  localDayOfYear: number;
152
152
  day_id: import("mongoose").Types.ObjectId;
@@ -253,23 +253,23 @@ export declare const TenantInstoreShiftSessionSchema: Schema<any, import("mongoo
253
253
  createdAt: NativeDate;
254
254
  updatedAt: NativeDate;
255
255
  } & {
256
+ localHour: number;
257
+ localDate: string;
258
+ localWeek: number;
259
+ localWeekOfYear: number;
260
+ localMonth: number;
261
+ localQuarter: number;
262
+ localSemester: number;
263
+ localYear: number;
256
264
  _id: import("mongoose").Types.ObjectId;
257
265
  tenant_id: string;
258
266
  createdAt: NativeDate;
259
267
  updatedAt: NativeDate;
260
268
  status: import("../../constants").POS_SHIFT_STATUS_ENUM;
261
- localYear: number;
262
- localMonth: number;
263
269
  localDay: number;
264
270
  day_index: import("../../constants").DAY_INDEX_ENUM;
265
271
  localSecond: number;
266
272
  localMinute: number;
267
- localHour: number;
268
- localWeek: number;
269
- localWeekOfYear: number;
270
- localQuarter: number;
271
- localSemester: number;
272
- localDate: string;
273
273
  localTime: string;
274
274
  localDayOfYear: number;
275
275
  day_id: import("mongoose").Types.ObjectId;
@@ -31,6 +31,8 @@ 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_tenant_reports_iterations';
35
+ export * from './materialized_tenant_sales_overview_reports';
34
36
  export * from './menus';
35
37
  export * from './messaging_devices';
36
38
  export * from './modifier_extras';
@@ -47,6 +47,8 @@ __exportStar(require("./inventory_transactions"), exports);
47
47
  __exportStar(require("./item_transactions"), exports);
48
48
  __exportStar(require("./items"), exports);
49
49
  __exportStar(require("./marketing_fingerprints"), exports);
50
+ __exportStar(require("./materialized_tenant_reports_iterations"), exports);
51
+ __exportStar(require("./materialized_tenant_sales_overview_reports"), exports);
50
52
  __exportStar(require("./menus"), exports);
51
53
  __exportStar(require("./messaging_devices"), exports);
52
54
  __exportStar(require("./modifier_extras"), exports);
@@ -0,0 +1,62 @@
1
+ import { MATERIALIZED_REPORT_TYPE_ENUM } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { IMaterializedTenantSalesOverviewReport } from './materialized_tenant_sales_overview_reports';
3
+ /**
4
+ * Document types 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 row per VERSIONED write of a report document; `snapshot` is the full
9
+ * report document AFTER the write, so `(report_id, iteration)` identifies a
10
+ * stored version of that document:
11
+ * - first materialization → `iteration: 1`;
12
+ * - replacement (day/hour write) / reconcile deltas (`subtract` +
13
+ * `additions`) → the report's bumped `iteration`;
14
+ * - received-payment patches THAT CHANGE THE LEDGER are versioned too — they
15
+ * bump `iteration` and append rows (no-op patches write nothing, keeping
16
+ * replays churn-free);
17
+ * - every row carries the backend-generated `reason` the iteration happened
18
+ * (e.g. `NEW_DAY`, `RECLOSE`, `RECONCILE`, `CREDIT_BILL_COLLECTED`).
19
+ *
20
+ * Rows are append-only: a replay rewrites the SAME `(report_id, iteration)`
21
+ * row (idempotent), and a rollback re-applies an older snapshot as a NEW
22
+ * versioned write (with its own row) — the audit trail is never rewritten.
23
+ */
24
+ /**
25
+ * Every materialized report document shape a history row can snapshot —
26
+ * extend this union as report collections land.
27
+ */
28
+ export type IMaterializedReportSnapshot = IMaterializedTenantSalesOverviewReport;
29
+ /**
30
+ * One persisted iteration row. `snapshot` is untyped in storage (Mixed) since
31
+ * the collection serves every report kind — narrow it via `report_type`.
32
+ */
33
+ export interface IMaterializedTenantReportIteration<TReportSnapshot = IMaterializedReportSnapshot> {
34
+ _id: string;
35
+ /** Which report collection `report_id` belongs to (`MATERIALIZED_REPORT_TYPE_ENUM`). */
36
+ report_type: MATERIALIZED_REPORT_TYPE_ENUM;
37
+ /** `_id` of the materialized report document this row snapshots. */
38
+ report_id: string;
39
+ /**
40
+ * The report's structural iteration this snapshot represents — equals
41
+ * `snapshot.iteration`; denormalized so history reads can sort/filter
42
+ * without digging into the Mixed snapshot (1 = first materialization).
43
+ */
44
+ iteration: number;
45
+ /** Snapshot schema version — lets a rollback pick rows it can interpret. */
46
+ schema_version: number;
47
+ /**
48
+ * Why the iteration happened — backend-generated free string (e.g.
49
+ * `NEW_DAY`, `RECLOSE`, `RECONCILE`, `CREDIT_BILL_COLLECTED`).
50
+ */
51
+ reason: string;
52
+ /** The full report document as written (post-write state). */
53
+ snapshot: TReportSnapshot;
54
+ createdAt: Date;
55
+ updatedAt: Date;
56
+ }
57
+ /**
58
+ * A new history row built by `buildMaterializedTenantReportIteration` — `_id` is assigned
59
+ * by MongoDB on the write (`replaceOne` upserts keyed by
60
+ * `(report_id, iteration)` keep idempotent replays on the same row).
61
+ */
62
+ export type IMaterializedTenantReportIterationInput<TReportSnapshot = IMaterializedReportSnapshot> = Omit<IMaterializedTenantReportIteration<TReportSnapshot>, '_id'>;
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,242 @@
1
+ import { REPORT_SALE_TYPE_ENUM } from '../../constants';
2
+ import { DAY_INDEX_ENUM } from '../../constants/ENUMS';
3
+ import { MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM } from '../../constants/MATERIALIZED_REPORTS';
4
+ /**
5
+ * Document types for `materialized_tenant_sales_overview_reports` — the
6
+ * materialized version of the admin panel Reports > Overview report.
7
+ *
8
+ * See `MATERIALIZED_REPORTS.md` for the full conventions:
9
+ * - one document per (tenant, scope context, scope value) — `scope_context` +
10
+ * `scope_field`; stamped from the order's business day (`order.localDate`;
11
+ * hours: punch hour for sales, settlement hour for credit-bill collections),
12
+ * the time-bias toggle / Punched At is out of scope for this collection;
13
+ * - `sale_type_key_filters` declares the ordered filter dimensions encoded
14
+ * into every `sale_type_metrics` key (e.g. `"PLACED:POS_WALK-IN"`);
15
+ * - amounts are CENTS (same as the live API response);
16
+ * - order metrics carry the money breakdown (discounts by source, gst/tax,
17
+ * tip, delivery charges, provider charges) so Overview/Summary views render
18
+ * without re-reading orders;
19
+ * - `payment_type` is an open string — live stores contain values outside
20
+ * `PAYMENT_TYPE_ENUM` (`CARD_PAYMENT`, `FOODPANDA`, …) and they must pass
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.
30
+ */
31
+ /** Order-level discount sums per source (`order_discount_details`), cents. */
32
+ export interface IMaterializedReportDiscountByType {
33
+ special_discount: number;
34
+ loyalty_discount: number;
35
+ voucher_discount: number;
36
+ }
37
+ /** Order totals of one sale-type block (cents). */
38
+ export interface IMaterializedReportOrderMetric {
39
+ count: number;
40
+ /**
41
+ * Sum of `amount_earned` in cents. Mirrors the live `TOTAL_SALES` /
42
+ * `CANCELLED_ORDERS` facets.
43
+ */
44
+ gross_amount: number;
45
+ /**
46
+ * Sum of `total_discount_applied` (cents) — order-level discounts; the
47
+ * per-source split lives in `discount_by_type`.
48
+ */
49
+ discount_amount: number;
50
+ discount_by_type: IMaterializedReportDiscountByType;
51
+ /** Sum of `gst_amount` (cents) — GST collected on the bucket's orders. */
52
+ gst_amount: number;
53
+ /** Sum of `tax_amount` (cents) — other tax (0 on today's live data). */
54
+ tax_amount: number;
55
+ /** Sum of `tip_amount` (cents). */
56
+ tip_amount: number;
57
+ /** Sum of `tax_invoice_provider_charges` (cents). */
58
+ tax_invoice_provider_charges: number;
59
+ /** Sum of `delivery_details.delivery_cost` (cents). */
60
+ delivery_charges: number;
61
+ }
62
+ /**
63
+ * Payment totals of one sale-type block, grouped by `payment_type` — mirrors
64
+ * the live `TOTAL_PAYMENT_SALES` facet (which unwinds `order.payments` and
65
+ * applies the payment inclusion + gross rules documented in
66
+ * `MATERIALIZED_REPORTS.md` and `sales-overview-reference.ts`).
67
+ */
68
+ export interface IMaterializedReportPaymentMetric {
69
+ /**
70
+ * Open string — NOT validated against `PAYMENT_TYPE_ENUM`. Stores raw
71
+ * values (`CARD_PAYMENT`, `FOODPANDA`, `GOLOOTLO`, …), plus the synthetic
72
+ * `'CREDIT_SETTLEMENT'` line that carries credit-bill collections on the
73
+ * day they are received. The `PAY_LATER` → `UNPAID` remap happens at read
74
+ * time.
75
+ */
76
+ payment_type: string;
77
+ /** Number of payments (not orders) of this type. */
78
+ count: number;
79
+ /**
80
+ * Cents, net of refunds and card charges; may be negative for refunded
81
+ * payments (`-amount_refunded`).
82
+ */
83
+ gross_amount: number;
84
+ amount_due: number;
85
+ amount_paid: number;
86
+ amount_refunded: number;
87
+ /** Sum of `payments.card_details.card_charges` (0 when no card details). */
88
+ card_charges: number;
89
+ }
90
+ /** The three sale-type metric variants of one filter-combination bucket. */
91
+ export interface IMaterializedReportSaleTypeMetric {
92
+ orders: IMaterializedReportOrderMetric;
93
+ payments: IMaterializedReportPaymentMetric[];
94
+ }
95
+ /**
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).
149
+ *
150
+ * Amounts are cents. The ledger never feeds gross — gross stays sales-only so
151
+ * cross-day gross sums stay equal to total sales.
152
+ */
153
+ export interface IMaterializedReportCreditBills {
154
+ issued: {
155
+ count: number;
156
+ 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
+ settled_count: number;
162
+ settled_amount: number;
163
+ bills: IMaterializedReportCreditBill[];
164
+ };
165
+ received: {
166
+ count: number;
167
+ amount: number;
168
+ bills: IMaterializedReportReceivedCreditBill[];
169
+ };
170
+ }
171
+ /**
172
+ * Metrics for one `sale_type_metrics` key — the entry exists only for filter
173
+ * combinations observed that day; absent key = zero.
174
+ */
175
+ export interface IMaterializedReportKeyMetrics {
176
+ /** Non-cancelled orders (live `TOTAL_SALES` sale type: no constraint). */
177
+ [REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: IMaterializedReportSaleTypeMetric;
178
+ /** Orders with `amount_collected > 0`. */
179
+ [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
+ */
185
+ [REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: IMaterializedReportCreditBills;
186
+ }
187
+ export interface IMaterializedTenantSalesOverviewReport {
188
+ _id: string;
189
+ tenant_id: string;
190
+ /** Required for brand-level reads (sum across the brand's tenants). */
191
+ brand_id: string;
192
+ /**
193
+ * Which time-scope this document covers (`localHour` … `localYear`).
194
+ * One document per (tenant, scope context, scope value).
195
+ */
196
+ scope_context: MATERIALIZED_REPORT_SCOPE_ENUM;
197
+ /**
198
+ * The scope value this document summarizes — the field the standardized
199
+ * query filters on. Format depends on `scope_context` (e.g. `'2026-09-15'`
200
+ * for `LOCAL_DATE`, `'2026-09-15 18'` for `LOCAL_HOUR`); see
201
+ * `MATERIALIZED_REPORT_SCOPE_ENUM` / `MATERIALIZED_REPORTS.md`.
202
+ */
203
+ scope_field: string;
204
+ /**
205
+ * Denormalized weekday of `scope_field` — set ONLY on `LOCAL_HOUR` /
206
+ * `LOCAL_DATE` documents (`null` elsewhere; see
207
+ * `MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX`). Enables filter-correct
208
+ * weekday queries (`day_index` + `scope_field` range) and weekday grouping
209
+ * without an all-time accumulator document; derived from the scope value by
210
+ * the materializer (`DAY_INDEX_ENUM`).
211
+ */
212
+ day_index?: DAY_INDEX_ENUM | null;
213
+ /**
214
+ * Ordered filter dimensions encoded into `sale_type_metrics` keys; the
215
+ * order defines the key grammar (`"PLACED:POS_WALK-IN"`).
216
+ */
217
+ sale_type_key_filters: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
218
+ /**
219
+ * One entry per observed filter-combination key. An empty map represents a
220
+ * day with no orders (kept so reconcile/watermark comparisons stay uniform).
221
+ */
222
+ sale_type_metrics: Record<string, IMaterializedReportKeyMetrics> | null;
223
+ /**
224
+ * 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`).
229
+ */
230
+ iteration?: number;
231
+ /** Bump on key-grammar / metric-rule changes; requires re-materialization. */
232
+ schema_version: number;
233
+ /**
234
+ * Max source `orders.updatedAt` folded into this document — staleness
235
+ * detection and watermark-guarded upserts.
236
+ */
237
+ source_watermark: Date;
238
+ /** When the materializer last rebuilt this document. */
239
+ computed_at: Date;
240
+ createdAt: Date;
241
+ updatedAt: Date;
242
+ }
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const constants_1 = require("../../constants");