@managesome/eposmatic-toolkit 0.4.53 → 0.4.55

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 (82) hide show
  1. package/esm/helpers/materialized-reports/index.js +1 -0
  2. package/esm/helpers/materialized-reports/materialized-delivery-wipe-targets.js +18 -0
  3. package/esm/helpers/materialized-reports/report-platform/definition.js +508 -0
  4. package/esm/helpers/materialized-reports/report-platform/index.js +4 -0
  5. package/esm/helpers/materialized-reports/report-platform/lifecycle/budget.js +27 -0
  6. package/esm/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +12 -0
  7. package/esm/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +121 -0
  8. package/esm/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +14 -0
  9. package/esm/helpers/materialized-reports/report-platform/lifecycle/index.js +8 -0
  10. package/esm/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +10 -0
  11. package/esm/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +42 -0
  12. package/esm/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +28 -0
  13. package/esm/helpers/materialized-reports/report-platform/lifecycle/top-n.js +24 -0
  14. package/esm/helpers/materialized-reports/report-platform/registry.js +23 -0
  15. package/esm/helpers/materialized-reports/report-platform/validate-report-registry.js +214 -0
  16. package/esm/schemas/models/index.js +1 -0
  17. package/esm/schemas/models/tenant_dialer_events.js +133 -0
  18. package/esm/schemas/types/index.js +1 -0
  19. package/esm/schemas/types/tenant_dialer_events.js +1 -0
  20. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  21. package/lib/helpers/materialized-reports/index.js +1 -0
  22. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.d.ts +1 -0
  23. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.js +19 -0
  24. package/lib/helpers/materialized-reports/report-platform/definition.d.ts +133 -0
  25. package/lib/helpers/materialized-reports/report-platform/definition.js +511 -0
  26. package/lib/helpers/materialized-reports/report-platform/index.d.ts +4 -0
  27. package/lib/helpers/materialized-reports/report-platform/index.js +20 -0
  28. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.d.ts +8 -0
  29. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.js +31 -0
  30. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.d.ts +8 -0
  31. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +16 -0
  32. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.d.ts +40 -0
  33. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +130 -0
  34. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.d.ts +22 -0
  35. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +17 -0
  36. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.d.ts +8 -0
  37. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.js +24 -0
  38. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.d.ts +13 -0
  39. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +13 -0
  40. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.d.ts +20 -0
  41. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +47 -0
  42. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.d.ts +13 -0
  43. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +31 -0
  44. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.d.ts +16 -0
  45. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.js +29 -0
  46. package/lib/helpers/materialized-reports/report-platform/registry.d.ts +13 -0
  47. package/lib/helpers/materialized-reports/report-platform/registry.js +31 -0
  48. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.d.ts +20 -0
  49. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.js +218 -0
  50. package/lib/schemas/models/index.d.ts +1 -0
  51. package/lib/schemas/models/index.js +1 -0
  52. package/lib/schemas/models/tenant-activity-logs.d.ts +3 -3
  53. package/lib/schemas/models/tenant_dialer_events.d.ts +130 -0
  54. package/lib/schemas/models/tenant_dialer_events.js +136 -0
  55. package/lib/schemas/models/warehouse-activity-logs.d.ts +3 -3
  56. package/lib/schemas/types/index.d.ts +1 -0
  57. package/lib/schemas/types/index.js +1 -0
  58. package/lib/schemas/types/tenant_dialer_events.d.ts +35 -0
  59. package/lib/schemas/types/tenant_dialer_events.js +2 -0
  60. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.d.ts +1 -0
  61. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.js +229 -0
  62. package/lib/tests/materialized-reports/characterization/discount.characterization.test.d.ts +1 -0
  63. package/lib/tests/materialized-reports/characterization/discount.characterization.test.js +99 -0
  64. package/lib/tests/materialized-reports/characterization/fixtures.d.ts +30 -0
  65. package/lib/tests/materialized-reports/characterization/fixtures.js +402 -0
  66. package/lib/tests/materialized-reports/characterization/golden.d.ts +18 -0
  67. package/lib/tests/materialized-reports/characterization/golden.js +127 -0
  68. package/lib/tests/materialized-reports/characterization/overview.characterization.test.d.ts +1 -0
  69. package/lib/tests/materialized-reports/characterization/overview.characterization.test.js +69 -0
  70. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.d.ts +1 -0
  71. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.js +102 -0
  72. package/lib/tests/materialized-reports/materialized-wipe-tooling.test.d.ts +1 -0
  73. package/lib/tests/materialized-reports/materialized-wipe-tooling.test.js +37 -0
  74. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.d.ts +1 -0
  75. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.js +177 -0
  76. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.d.ts +1 -0
  77. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.js +214 -0
  78. package/lib/tests/materialized-reports/report-platform/registry-validation.test.d.ts +1 -0
  79. package/lib/tests/materialized-reports/report-platform/registry-validation.test.js +103 -0
  80. package/lib/tests/tenant-dialer-events-schema.test.d.ts +1 -0
  81. package/lib/tests/tenant-dialer-events-schema.test.js +191 -0
  82. package/package.json +4 -2
@@ -53,3 +53,4 @@ export * from './tenant-delivery-formatter';
53
53
  export * from './tenant-prep-time-formatter';
54
54
  export * from './tenant-sales-overview-formatter';
55
55
  export * from './tenant-sales-overview-helpers';
56
+ export * from './report-platform';
@@ -30,3 +30,21 @@ export function buildDeliveryMaterializationWipeTargets(tenantId) {
30
30
  { name: MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME, filter: iterationFilter },
31
31
  ];
32
32
  }
33
+ /**
34
+ * Phase 5 safety gate: a wipe target may only name a materialized collection
35
+ * and may only filter on tenant/report identity. This is the last line of
36
+ * defence before an operator command talks to MongoDB.
37
+ */
38
+ const ALLOWED_WIPE_FILTER_KEYS = new Set(['tenant_id', 'report_type', 'snapshot.tenant_id']);
39
+ export function assertMaterializedWipeTargets(targets) {
40
+ for (const target of targets) {
41
+ if (!target.name.startsWith('materialized_')) {
42
+ throw new Error(`Refusing wipe: ${target.name} is not a materialized_* collection`);
43
+ }
44
+ for (const key of Object.keys(target.filter)) {
45
+ if (!ALLOWED_WIPE_FILTER_KEYS.has(key)) {
46
+ throw new Error(`Refusing wipe: ${target.name} filters on forbidden key ${key}`);
47
+ }
48
+ }
49
+ }
50
+ }
@@ -0,0 +1,508 @@
1
+ import { MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_ENTRY_SCOPES, MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_SCOPES, MATERIALIZED_DISCOUNT_REPORT_SCOPES, MATERIALIZED_PREP_TIME_ITEM_SCOPES, MATERIALIZED_PREP_TIME_REPORT_SCOPES, MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_TYPE_ENUM, ALL_MATERIALIZED_REPORT_SCOPES, } from '../../../constants/MATERIALIZED_REPORTS';
2
+ import { REPORT_KEY_ENUM } from '../../reporting-contract/report-contract';
3
+ /**
4
+ * PHASE 2 — DECLARATIVE REPORT DEFINITIONS.
5
+ *
6
+ * This module is METADATA ONLY. It must not import Mongoose, Express, database
7
+ * code, workers-service or operations-service. Metric compilation, document
8
+ * schemas and formatters stay report-specific.
9
+ *
10
+ * Schema versions are declared as literals here so this module stays free of
11
+ * schema/model imports. The conformance suite compares every literal with the
12
+ * exported model constant; drift fails the build.
13
+ */
14
+ export var REPORT_DEFINITION_STATUS;
15
+ (function (REPORT_DEFINITION_STATUS) {
16
+ REPORT_DEFINITION_STATUS["PRODUCTION"] = "PRODUCTION";
17
+ REPORT_DEFINITION_STATUS["READ_ONLY"] = "READ_ONLY";
18
+ REPORT_DEFINITION_STATUS["PLANNED"] = "PLANNED";
19
+ })(REPORT_DEFINITION_STATUS || (REPORT_DEFINITION_STATUS = {}));
20
+ export var REPORT_ENTRY_STORAGE;
21
+ (function (REPORT_ENTRY_STORAGE) {
22
+ /** No itemized collection. */
23
+ REPORT_ENTRY_STORAGE["NONE"] = "NONE";
24
+ /** One entry document per (tenant, scope, field); Prep Time today. */
25
+ REPORT_ENTRY_STORAGE["ONE_PER_SCOPE"] = "ONE_PER_SCOPE";
26
+ /** One entry document per source day; Discounts and Delivery today. */
27
+ REPORT_ENTRY_STORAGE["PAGE_PER_SOURCE_DAY"] = "PAGE_PER_SOURCE_DAY";
28
+ })(REPORT_ENTRY_STORAGE || (REPORT_ENTRY_STORAGE = {}));
29
+ export var REPORT_ENTRY_SPLIT;
30
+ (function (REPORT_ENTRY_SPLIT) {
31
+ REPORT_ENTRY_SPLIT["NONE"] = "NONE";
32
+ /** Deterministic `page#0`, `page#1`, ... when one page exceeds its budget. */
33
+ REPORT_ENTRY_SPLIT["DETERMINISTIC_SUBPAGES"] = "DETERMINISTIC_SUBPAGES";
34
+ })(REPORT_ENTRY_SPLIT || (REPORT_ENTRY_SPLIT = {}));
35
+ export var REPORT_WRITE_GUARD;
36
+ (function (REPORT_WRITE_GUARD) {
37
+ REPORT_WRITE_GUARD["NONE"] = "NONE";
38
+ REPORT_WRITE_GUARD["WATERMARK"] = "WATERMARK";
39
+ REPORT_WRITE_GUARD["WATERMARK_AND_DIGEST"] = "WATERMARK_AND_DIGEST";
40
+ })(REPORT_WRITE_GUARD || (REPORT_WRITE_GUARD = {}));
41
+ export var REPORT_LIVE_SOURCE;
42
+ (function (REPORT_LIVE_SOURCE) {
43
+ REPORT_LIVE_SOURCE["RAW"] = "RAW";
44
+ REPORT_LIVE_SOURCE["RAW_PLUS_MATERIALIZED"] = "RAW_PLUS_MATERIALIZED";
45
+ })(REPORT_LIVE_SOURCE || (REPORT_LIVE_SOURCE = {}));
46
+ export var REPORT_HISTORICAL_LENS;
47
+ (function (REPORT_HISTORICAL_LENS) {
48
+ REPORT_HISTORICAL_LENS["DOCUMENT_FOLD"] = "DOCUMENT_FOLD";
49
+ REPORT_HISTORICAL_LENS["COUNTER_ROWS"] = "COUNTER_ROWS";
50
+ })(REPORT_HISTORICAL_LENS || (REPORT_HISTORICAL_LENS = {}));
51
+ export var REPORT_CURSOR_KIND;
52
+ (function (REPORT_CURSOR_KIND) {
53
+ REPORT_CURSOR_KIND["NONE"] = "NONE";
54
+ REPORT_CURSOR_KIND["KEYSET_STRUCTURED"] = "KEYSET_STRUCTURED";
55
+ REPORT_CURSOR_KIND["SIGNED_QUERY"] = "SIGNED_QUERY";
56
+ })(REPORT_CURSOR_KIND || (REPORT_CURSOR_KIND = {}));
57
+ export var REPORT_PROJECTION;
58
+ (function (REPORT_PROJECTION) {
59
+ REPORT_PROJECTION["FLAT_DRILLDOWN"] = "FLAT_DRILLDOWN";
60
+ REPORT_PROJECTION["DISCOUNT_SOURCES"] = "DISCOUNT_SOURCES";
61
+ REPORT_PROJECTION["DELIVERY_GEO"] = "DELIVERY_GEO";
62
+ })(REPORT_PROJECTION || (REPORT_PROJECTION = {}));
63
+ export var REPORT_RETENTION_UNIT;
64
+ (function (REPORT_RETENTION_UNIT) {
65
+ REPORT_RETENTION_UNIT["DAY"] = "DAY";
66
+ REPORT_RETENTION_UNIT["MONTH"] = "MONTH";
67
+ })(REPORT_RETENTION_UNIT || (REPORT_RETENTION_UNIT = {}));
68
+ const DOCUMENT_BUDGET = 15 * 1024 * 1024;
69
+ const GEO_SCOPE_BUDGET = 2 * 1024 * 1024;
70
+ const FLAT_ROWS = {
71
+ name: 'materialized_report_drilldown_rows',
72
+ schemaVersion: 1,
73
+ budgetBytes: DOCUMENT_BUDGET,
74
+ enforced: false,
75
+ validatorFile: null,
76
+ validatorDebt: 'No schema validator exists for the flat drill-down rows yet.',
77
+ indexOwner: 'toolkit:MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS',
78
+ migrationId: null,
79
+ };
80
+ const FLAT_SCOPES = {
81
+ name: 'materialized_report_drilldown_scopes',
82
+ schemaVersion: 1,
83
+ budgetBytes: DOCUMENT_BUDGET,
84
+ enforced: false,
85
+ validatorFile: null,
86
+ validatorDebt: 'No schema validator exists for the flat drill-down scopes yet.',
87
+ indexOwner: 'toolkit:MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS',
88
+ migrationId: null,
89
+ };
90
+ const CLIENT_KEY_FILTERS = [
91
+ {
92
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
93
+ kind: 'KEY_COMPONENT',
94
+ mode: 'CLIENT',
95
+ appliesTo: 'BOTH',
96
+ },
97
+ {
98
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM,
99
+ kind: 'KEY_COMPONENT',
100
+ mode: 'CLIENT',
101
+ appliesTo: 'BOTH',
102
+ },
103
+ { id: 'DAY_INDEX', kind: 'ROW', mode: 'CLIENT', appliesTo: 'SUMMARY' },
104
+ ];
105
+ const OVERVIEW_DEFINITION = {
106
+ key: REPORT_KEY_ENUM.OVERVIEW,
107
+ segment: 'overview',
108
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_SALES_OVERVIEW,
109
+ capabilities: { live: true, historical: true, details: false },
110
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
111
+ report: {
112
+ name: 'materialized_tenant_sales_overview_reports',
113
+ schemaVersion: 1,
114
+ budgetBytes: DOCUMENT_BUDGET,
115
+ enforced: false,
116
+ validatorFile: 'materialized_tenant_sales_overview_reports.bson',
117
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS',
118
+ migrationId: null,
119
+ },
120
+ sideCollections: [
121
+ {
122
+ name: 'materialized_tenant_credit_bills',
123
+ schemaVersion: 1,
124
+ budgetBytes: DOCUMENT_BUDGET,
125
+ enforced: false,
126
+ validatorFile: 'materialized_tenant_credit_bills.bson',
127
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_CREDIT_BILLS_INDEX_OPTIONS',
128
+ migrationId: null,
129
+ },
130
+ ],
131
+ reportScopes: [...ALL_MATERIALIZED_REPORT_SCOPES],
132
+ entryScopes: [],
133
+ entryStorage: REPORT_ENTRY_STORAGE.NONE,
134
+ entrySplit: REPORT_ENTRY_SPLIT.NONE,
135
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
136
+ maxEntryScope: null,
137
+ projections: [],
138
+ budgets: {
139
+ materialized_tenant_sales_overview_reports: DOCUMENT_BUDGET,
140
+ materialized_tenant_credit_bills: DOCUMENT_BUDGET,
141
+ },
142
+ retention: [],
143
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK_AND_DIGEST,
144
+ liveSource: REPORT_LIVE_SOURCE.RAW_PLUS_MATERIALIZED,
145
+ historicalLens: REPORT_HISTORICAL_LENS.DOCUMENT_FOLD,
146
+ completeness: { summary: 'ALL_SCOPES', details: 'NONE' },
147
+ filters: CLIENT_KEY_FILTERS,
148
+ cursor: REPORT_CURSOR_KIND.NONE,
149
+ adapters: {
150
+ writer: 'materializeOverviewReport',
151
+ live: 'getLiveTenantSalesOverviewReports',
152
+ historical: 'getMaterializedTenantSalesOverviewReports',
153
+ },
154
+ owner: 'reporting-platform',
155
+ notes: [
156
+ 'Map-only counters: no sales_overview_counter_rows.',
157
+ 'LIVE is raw + stored credit ledger and resolves the running day server-side.',
158
+ 'Writes the credit ledger and may patch prior issue-day counters.',
159
+ ],
160
+ };
161
+ const DISCOUNTS_DEFINITION = {
162
+ key: REPORT_KEY_ENUM.DISCOUNTS,
163
+ segment: 'discounts',
164
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DISCOUNT_REPORTS,
165
+ capabilities: { live: true, historical: true, details: true },
166
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
167
+ report: {
168
+ name: 'materialized_tenant_discount_reports',
169
+ schemaVersion: 1,
170
+ budgetBytes: DOCUMENT_BUDGET,
171
+ enforced: false,
172
+ validatorFile: 'materialized_tenant_discount_reports.bson',
173
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS',
174
+ migrationId: 'discount-entry-page-index',
175
+ },
176
+ entries: {
177
+ name: 'materialized_tenant_discount_entries',
178
+ schemaVersion: 1,
179
+ budgetBytes: DOCUMENT_BUDGET,
180
+ enforced: false,
181
+ validatorFile: 'materialized_tenant_discount_entries.bson',
182
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS',
183
+ migrationId: 'discount-entry-page-index',
184
+ },
185
+ sideCollections: [
186
+ {
187
+ name: 'materialized_tenant_discount_sources',
188
+ schemaVersion: 1,
189
+ budgetBytes: DOCUMENT_BUDGET,
190
+ enforced: false,
191
+ validatorFile: null,
192
+ validatorDebt: 'No schema validator exists for the discount source projection yet.',
193
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS',
194
+ migrationId: null,
195
+ },
196
+ FLAT_ROWS,
197
+ FLAT_SCOPES,
198
+ ],
199
+ reportScopes: [...MATERIALIZED_DISCOUNT_REPORT_SCOPES],
200
+ entryScopes: [...MATERIALIZED_DISCOUNT_REPORT_SCOPES],
201
+ entryStorage: REPORT_ENTRY_STORAGE.PAGE_PER_SOURCE_DAY,
202
+ entrySplit: REPORT_ENTRY_SPLIT.NONE,
203
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
204
+ maxEntryScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
205
+ projections: [REPORT_PROJECTION.DISCOUNT_SOURCES, REPORT_PROJECTION.FLAT_DRILLDOWN],
206
+ budgets: {
207
+ materialized_tenant_discount_reports: DOCUMENT_BUDGET,
208
+ materialized_tenant_discount_entries: DOCUMENT_BUDGET,
209
+ materialized_tenant_discount_sources: DOCUMENT_BUDGET,
210
+ materialized_report_drilldown_rows: DOCUMENT_BUDGET,
211
+ materialized_report_drilldown_scopes: DOCUMENT_BUDGET,
212
+ },
213
+ retention: [],
214
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK_AND_DIGEST,
215
+ liveSource: REPORT_LIVE_SOURCE.RAW,
216
+ historicalLens: REPORT_HISTORICAL_LENS.COUNTER_ROWS,
217
+ completeness: { summary: 'NONE', details: 'FLAT_PROJECTION' },
218
+ filters: [
219
+ ...CLIENT_KEY_FILTERS,
220
+ {
221
+ id: 'DETAILS_VIEW',
222
+ kind: 'REQUEST',
223
+ mode: 'SERVER',
224
+ appliesTo: 'DETAILS',
225
+ },
226
+ {
227
+ id: 'SOURCE_KEY_LEVEL',
228
+ kind: 'REQUEST',
229
+ mode: 'SERVER',
230
+ appliesTo: 'DETAILS',
231
+ },
232
+ ],
233
+ cursor: REPORT_CURSOR_KIND.KEYSET_STRUCTURED,
234
+ adapters: {
235
+ writer: 'materializeDiscountReport',
236
+ live: 'getLiveTenantDiscountReports',
237
+ historical: 'getMaterializedTenantDiscountReports',
238
+ details: 'getMaterializedDiscountDetailsPage',
239
+ },
240
+ owner: 'reporting-platform',
241
+ notes: [
242
+ 'Month-capped scope set; a wider selection is refused, never narrowed.',
243
+ 'Page-partitioned entries; no #N splitter and no budget assertion today.',
244
+ 'Derived source projection has no independent iteration history.',
245
+ ],
246
+ };
247
+ const PREP_TIME_DEFINITION = {
248
+ key: REPORT_KEY_ENUM.PREP_TIME,
249
+ segment: 'prep-time',
250
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_PREP_TIME_REPORTS,
251
+ capabilities: { live: true, historical: true, details: true },
252
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
253
+ report: {
254
+ name: 'materialized_tenant_prep_time_reports',
255
+ schemaVersion: 1,
256
+ budgetBytes: DOCUMENT_BUDGET,
257
+ enforced: false,
258
+ validatorFile: 'materialized_tenant_prep_time_reports.bson',
259
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_PREP_TIME_REPORTS_INDEX_OPTIONS',
260
+ migrationId: null,
261
+ },
262
+ entries: {
263
+ name: 'materialized_tenant_prep_time_entries',
264
+ schemaVersion: 1,
265
+ budgetBytes: DOCUMENT_BUDGET,
266
+ enforced: false,
267
+ validatorFile: 'materialized_tenant_prep_time_entries.bson',
268
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_PREP_TIME_ENTRIES_INDEX_OPTIONS',
269
+ migrationId: null,
270
+ },
271
+ sideCollections: [FLAT_ROWS, FLAT_SCOPES],
272
+ reportScopes: [...MATERIALIZED_PREP_TIME_REPORT_SCOPES],
273
+ entryScopes: [...MATERIALIZED_PREP_TIME_ITEM_SCOPES],
274
+ entryStorage: REPORT_ENTRY_STORAGE.ONE_PER_SCOPE,
275
+ entrySplit: REPORT_ENTRY_SPLIT.NONE,
276
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
277
+ maxEntryScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
278
+ projections: [REPORT_PROJECTION.FLAT_DRILLDOWN],
279
+ budgets: {
280
+ materialized_tenant_prep_time_reports: DOCUMENT_BUDGET,
281
+ materialized_tenant_prep_time_entries: DOCUMENT_BUDGET,
282
+ materialized_report_drilldown_rows: DOCUMENT_BUDGET,
283
+ materialized_report_drilldown_scopes: DOCUMENT_BUDGET,
284
+ },
285
+ retention: [],
286
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK,
287
+ liveSource: REPORT_LIVE_SOURCE.RAW,
288
+ historicalLens: REPORT_HISTORICAL_LENS.COUNTER_ROWS,
289
+ completeness: { summary: 'NONE', details: 'FLAT_PROJECTION' },
290
+ filters: [
291
+ ...CLIENT_KEY_FILTERS,
292
+ { id: 'DETAILS_VIEW', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
293
+ { id: 'LATE_ONLY', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
294
+ { id: 'ITEM_ID', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
295
+ {
296
+ id: 'EXCLUDE_CANCELLED',
297
+ kind: 'REQUEST',
298
+ mode: 'SERVER',
299
+ appliesTo: 'DETAILS',
300
+ },
301
+ ],
302
+ cursor: REPORT_CURSOR_KIND.SIGNED_QUERY,
303
+ adapters: {
304
+ writer: 'materializePrepTimeReport',
305
+ live: 'getLiveTenantPrepTimeReports',
306
+ historical: 'getMaterializedTenantPrepTimeReports',
307
+ details: 'getMaterializedPrepTimeDetailsPage',
308
+ },
309
+ owner: 'reporting-platform',
310
+ notes: [
311
+ 'Coverage-first counters: MEASURED/UNMEASURED anchor split and target provenance.',
312
+ 'No hour scope; entries are one document per scope, not pages.',
313
+ 'Item reads are capped at 31 effective days at the route.',
314
+ ],
315
+ };
316
+ const DELIVERY_DEFINITION = {
317
+ key: REPORT_KEY_ENUM.DELIVERY,
318
+ segment: 'delivery',
319
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DELIVERY_REPORTS,
320
+ capabilities: { live: true, historical: true, details: true },
321
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
322
+ report: {
323
+ name: 'materialized_tenant_delivery_reports',
324
+ schemaVersion: 2,
325
+ budgetBytes: MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES,
326
+ enforced: true,
327
+ validatorFile: 'materialized_tenant_delivery_reports.bson',
328
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_REPORTS_INDEX_OPTIONS',
329
+ migrationId: 'delivery-page-index-2026-10-27',
330
+ },
331
+ entries: {
332
+ name: 'materialized_tenant_delivery_entries',
333
+ schemaVersion: 3,
334
+ budgetBytes: MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES,
335
+ enforced: true,
336
+ validatorFile: 'materialized_tenant_delivery_entries.bson',
337
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_ENTRIES_INDEX_OPTIONS',
338
+ migrationId: 'delivery-page-index-2026-10-27',
339
+ },
340
+ sideCollections: [
341
+ {
342
+ name: 'materialized_tenant_delivery_geo_cells',
343
+ schemaVersion: 1,
344
+ budgetBytes: MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES,
345
+ enforced: true,
346
+ validatorFile: 'materialized_tenant_delivery_geo_cells.bson',
347
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_INDEX_OPTIONS',
348
+ migrationId: 'delivery-page-index-2026-10-27',
349
+ },
350
+ {
351
+ name: 'materialized_tenant_delivery_geo_scopes',
352
+ schemaVersion: 1,
353
+ budgetBytes: GEO_SCOPE_BUDGET,
354
+ enforced: false,
355
+ validatorFile: 'materialized_tenant_delivery_geo_scopes.bson',
356
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_INDEX_OPTIONS',
357
+ migrationId: 'delivery-page-index-2026-10-27',
358
+ },
359
+ FLAT_ROWS,
360
+ FLAT_SCOPES,
361
+ ],
362
+ reportScopes: [...MATERIALIZED_DELIVERY_REPORT_SCOPES],
363
+ entryScopes: [...MATERIALIZED_DELIVERY_ENTRY_SCOPES],
364
+ entryStorage: REPORT_ENTRY_STORAGE.PAGE_PER_SOURCE_DAY,
365
+ entrySplit: REPORT_ENTRY_SPLIT.DETERMINISTIC_SUBPAGES,
366
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
367
+ maxEntryScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
368
+ projections: [REPORT_PROJECTION.FLAT_DRILLDOWN, REPORT_PROJECTION.DELIVERY_GEO],
369
+ budgets: {
370
+ materialized_tenant_delivery_reports: MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES,
371
+ materialized_tenant_delivery_entries: MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES,
372
+ materialized_tenant_delivery_geo_cells: MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES,
373
+ materialized_tenant_delivery_geo_scopes: GEO_SCOPE_BUDGET,
374
+ materialized_report_drilldown_rows: DOCUMENT_BUDGET,
375
+ materialized_report_drilldown_scopes: DOCUMENT_BUDGET,
376
+ },
377
+ retention: [
378
+ {
379
+ collection: 'materialized_tenant_delivery_geo_cells',
380
+ unit: REPORT_RETENTION_UNIT.DAY,
381
+ amount: 90,
382
+ },
383
+ {
384
+ collection: 'materialized_tenant_delivery_geo_cells',
385
+ unit: REPORT_RETENTION_UNIT.MONTH,
386
+ amount: 24,
387
+ },
388
+ ],
389
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK,
390
+ liveSource: REPORT_LIVE_SOURCE.RAW,
391
+ historicalLens: REPORT_HISTORICAL_LENS.COUNTER_ROWS,
392
+ completeness: { summary: 'NONE', details: 'FLAT_PROJECTION' },
393
+ filters: [
394
+ {
395
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
396
+ kind: 'KEY_COMPONENT',
397
+ mode: 'SERVER',
398
+ appliesTo: 'BOTH',
399
+ },
400
+ {
401
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM,
402
+ kind: 'KEY_COMPONENT',
403
+ mode: 'SERVER',
404
+ appliesTo: 'BOTH',
405
+ },
406
+ {
407
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.CITY,
408
+ kind: 'KEY_COMPONENT',
409
+ mode: 'SERVER',
410
+ appliesTo: 'BOTH',
411
+ },
412
+ { id: 'RIDER_ID', kind: 'ROW', mode: 'SERVER', appliesTo: 'BOTH' },
413
+ { id: 'DETAILS_VIEW', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
414
+ ],
415
+ cursor: REPORT_CURSOR_KIND.KEYSET_STRUCTURED,
416
+ adapters: {
417
+ writer: 'materializeDeliveryReport',
418
+ live: 'getLiveTenantDeliveryReports',
419
+ historical: 'getMaterializedTenantDeliveryReports',
420
+ details: 'getMaterializedDeliveryDetailsPage',
421
+ },
422
+ owner: 'reporting-platform',
423
+ notes: [
424
+ 'Separate H3 geo collection and cap metadata; live geo is computed in memory.',
425
+ 'Cross-day completion re-materializes the prior ORDER day within the same transaction.',
426
+ 'Page entries split deterministically into #N sub-pages.',
427
+ 'Historical totals do not pin schema_version today (baseline debt).',
428
+ ],
429
+ };
430
+ export const REPORT_DEFINITIONS = {
431
+ [OVERVIEW_DEFINITION.key]: OVERVIEW_DEFINITION,
432
+ [DISCOUNTS_DEFINITION.key]: DISCOUNTS_DEFINITION,
433
+ [PREP_TIME_DEFINITION.key]: PREP_TIME_DEFINITION,
434
+ [DELIVERY_DEFINITION.key]: DELIVERY_DEFINITION,
435
+ };
436
+ export const PRODUCTION_REPORT_DEFINITIONS = [
437
+ OVERVIEW_DEFINITION,
438
+ DISCOUNTS_DEFINITION,
439
+ PREP_TIME_DEFINITION,
440
+ DELIVERY_DEFINITION,
441
+ ];
442
+ export const REPORT_REGISTRY_EXEMPTIONS = {
443
+ [REPORT_KEY_ENUM.CASH_IN_OUT]: {
444
+ key: REPORT_KEY_ENUM.CASH_IN_OUT,
445
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
446
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
447
+ },
448
+ [REPORT_KEY_ENUM.SALES_COMPARISON]: {
449
+ key: REPORT_KEY_ENUM.SALES_COMPARISON,
450
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
451
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
452
+ },
453
+ [REPORT_KEY_ENUM.HOURLY_COMPARISON]: {
454
+ key: REPORT_KEY_ENUM.HOURLY_COMPARISON,
455
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
456
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
457
+ },
458
+ [REPORT_KEY_ENUM.PAYMENTS_COMPARISON]: {
459
+ key: REPORT_KEY_ENUM.PAYMENTS_COMPARISON,
460
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
461
+ reason: 'Read adapters exist but there is no production END_TENANT_DAY writer.',
462
+ },
463
+ [REPORT_KEY_ENUM.CREDIT_BILLS]: {
464
+ key: REPORT_KEY_ENUM.CREDIT_BILLS,
465
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
466
+ reason: 'Historical-only ledger; no live read adapter.',
467
+ },
468
+ [REPORT_KEY_ENUM.ITERATIONS]: {
469
+ key: REPORT_KEY_ENUM.ITERATIONS,
470
+ status: REPORT_DEFINITION_STATUS.READ_ONLY,
471
+ reason: 'Shared history read, not a report family.',
472
+ },
473
+ [REPORT_KEY_ENUM.SUMMARY]: {
474
+ key: REPORT_KEY_ENUM.SUMMARY,
475
+ status: REPORT_DEFINITION_STATUS.PLANNED,
476
+ reason: 'No implementation.',
477
+ },
478
+ [REPORT_KEY_ENUM.X_REPORT]: {
479
+ key: REPORT_KEY_ENUM.X_REPORT,
480
+ status: REPORT_DEFINITION_STATUS.PLANNED,
481
+ reason: 'No implementation.',
482
+ },
483
+ [REPORT_KEY_ENUM.Z_REPORT]: {
484
+ key: REPORT_KEY_ENUM.Z_REPORT,
485
+ status: REPORT_DEFINITION_STATUS.PLANNED,
486
+ reason: 'No implementation.',
487
+ },
488
+ [REPORT_KEY_ENUM.ITEMS]: {
489
+ key: REPORT_KEY_ENUM.ITEMS,
490
+ status: REPORT_DEFINITION_STATUS.PLANNED,
491
+ reason: 'No implementation.',
492
+ },
493
+ [REPORT_KEY_ENUM.ITEMS_COMPARISON]: {
494
+ key: REPORT_KEY_ENUM.ITEMS_COMPARISON,
495
+ status: REPORT_DEFINITION_STATUS.PLANNED,
496
+ reason: 'No implementation.',
497
+ },
498
+ [REPORT_KEY_ENUM.VOID_ITEMS]: {
499
+ key: REPORT_KEY_ENUM.VOID_ITEMS,
500
+ status: REPORT_DEFINITION_STATUS.PLANNED,
501
+ reason: 'No implementation.',
502
+ },
503
+ [REPORT_KEY_ENUM.REVIEWS_RATINGS]: {
504
+ key: REPORT_KEY_ENUM.REVIEWS_RATINGS,
505
+ status: REPORT_DEFINITION_STATUS.PLANNED,
506
+ reason: 'No implementation.',
507
+ },
508
+ };
@@ -0,0 +1,4 @@
1
+ export * from './definition';
2
+ export * from './registry';
3
+ export * from './validate-report-registry';
4
+ export * from './lifecycle';
@@ -0,0 +1,27 @@
1
+ import { assertMaterializedDocumentSize } from '../../materialized-document-size';
2
+ export function getReportCollectionBudget(definition, kind, collectionName) {
3
+ if (kind === 'report')
4
+ return definition.budgets[definition.report.name] ?? null;
5
+ if (kind === 'entries') {
6
+ if (definition.entries == null)
7
+ return null;
8
+ return definition.budgets[definition.entries.name] ?? null;
9
+ }
10
+ if (collectionName == null)
11
+ return null;
12
+ if (!definition.sideCollections.some((collection) => collection.name === collectionName)) {
13
+ return null;
14
+ }
15
+ return definition.budgets[collectionName] ?? null;
16
+ }
17
+ export function assertReportDocumentBudget(definition, kind, document, options = {}) {
18
+ const budget = getReportCollectionBudget(definition, kind, options.collectionName);
19
+ if (budget == null) {
20
+ throw new Error(`assertReportDocumentBudget: ${definition.key} has no budget for ${kind}${options.collectionName == null ? '' : `:${options.collectionName}`}`);
21
+ }
22
+ assertMaterializedDocumentSize(document, {
23
+ collection: options.collectionName ?? (kind === 'report' ? definition.report.name : definition.entries?.name),
24
+ label: options.label ?? definition.key,
25
+ maxBytes: budget,
26
+ });
27
+ }
@@ -0,0 +1,12 @@
1
+ export const EMPTY_REPORT_CAP_METADATA = {
2
+ cappedCellCount: 0,
3
+ cappedOrderCount: 0,
4
+ exact: true,
5
+ };
6
+ export function mergeReportCapMetadata(left, right) {
7
+ return {
8
+ cappedCellCount: Number(left?.cappedCellCount ?? 0) + Number(right?.cappedCellCount ?? 0),
9
+ cappedOrderCount: Number(left?.cappedOrderCount ?? 0) + Number(right?.cappedOrderCount ?? 0),
10
+ exact: (left?.exact ?? true) && (right?.exact ?? true),
11
+ };
12
+ }