@managesome/eposmatic-toolkit 0.4.52 → 0.4.53

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 (107) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +106 -2
  2. package/esm/constants/enums/delivery.js +13 -0
  3. package/esm/helpers/materialized-reports/index.js +5 -0
  4. package/esm/helpers/materialized-reports/materialized-delivery-accumulator-helpers.js +8 -62
  5. package/esm/helpers/materialized-reports/materialized-delivery-classification-helpers.js +95 -73
  6. package/esm/helpers/materialized-reports/materialized-delivery-close-day-helpers.js +118 -146
  7. package/esm/helpers/materialized-reports/materialized-delivery-compile-helpers.js +304 -71
  8. package/esm/helpers/materialized-reports/materialized-delivery-entry-pages.js +307 -0
  9. package/esm/helpers/materialized-reports/materialized-delivery-index-migration.js +103 -0
  10. package/esm/helpers/materialized-reports/materialized-delivery-rows.js +109 -0
  11. package/esm/helpers/materialized-reports/materialized-delivery-wipe-targets.js +32 -0
  12. package/esm/helpers/materialized-reports/materialized-document-size.js +65 -0
  13. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +31 -16
  14. package/esm/helpers/materialized-reports/materialized-integer-contract.js +10 -1
  15. package/esm/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +3 -91
  16. package/esm/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.js +597 -0
  17. package/esm/helpers/materialized-reports/scope-helpers.js +98 -0
  18. package/esm/helpers/materialized-reports/tenant-delivery-formatter.js +70 -20
  19. package/esm/schemas/models/applied_order_discounts.js +103 -0
  20. package/esm/schemas/models/index.js +12 -10
  21. package/esm/schemas/models/materialized_tenant_delivery_entries.js +33 -12
  22. package/esm/schemas/models/materialized_tenant_delivery_geo_cells.js +83 -0
  23. package/esm/schemas/models/materialized_tenant_delivery_geo_scopes.js +35 -0
  24. package/esm/schemas/models/materialized_tenant_delivery_reports.js +10 -1
  25. package/esm/schemas/types/applied_order_discounts.js +1 -0
  26. package/esm/schemas/types/index.js +14 -12
  27. package/esm/schemas/types/materialized_tenant_delivery_geo_cells.js +1 -0
  28. package/esm/schemas/types/materialized_tenant_delivery_geo_scopes.js +1 -0
  29. package/lib/constants/MATERIALIZED_REPORTS.d.ts +95 -1
  30. package/lib/constants/MATERIALIZED_REPORTS.js +108 -4
  31. package/lib/constants/enums/delivery.d.ts +9 -0
  32. package/lib/constants/enums/delivery.js +14 -1
  33. package/lib/helpers/materialized-reports/index.d.ts +5 -0
  34. package/lib/helpers/materialized-reports/index.js +5 -0
  35. package/lib/helpers/materialized-reports/materialized-delivery-accumulator-helpers.js +8 -62
  36. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.d.ts +36 -9
  37. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.js +94 -72
  38. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.d.ts +23 -26
  39. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.js +121 -150
  40. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.d.ts +44 -5
  41. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.js +306 -69
  42. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.d.ts +128 -0
  43. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.js +322 -0
  44. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.d.ts +48 -0
  45. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.js +108 -0
  46. package/lib/helpers/materialized-reports/materialized-delivery-rows.d.ts +15 -0
  47. package/lib/helpers/materialized-reports/materialized-delivery-rows.js +115 -0
  48. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.d.ts +17 -0
  49. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.js +35 -0
  50. package/lib/helpers/materialized-reports/materialized-document-size.d.ts +47 -0
  51. package/lib/helpers/materialized-reports/materialized-document-size.js +73 -0
  52. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +28 -13
  53. package/lib/helpers/materialized-reports/materialized-integer-contract.js +10 -1
  54. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +2 -90
  55. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.d.ts +186 -0
  56. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.js +620 -0
  57. package/lib/helpers/materialized-reports/scope-helpers.d.ts +8 -0
  58. package/lib/helpers/materialized-reports/scope-helpers.js +99 -0
  59. package/lib/helpers/materialized-reports/tenant-delivery-formatter.d.ts +41 -0
  60. package/lib/helpers/materialized-reports/tenant-delivery-formatter.js +70 -20
  61. package/lib/helpers/order/payment-collection.d.ts +25 -0
  62. package/lib/helpers/order/payment-collection.js +51 -0
  63. package/lib/schemas/models/applied_order_discounts.d.ts +80 -0
  64. package/lib/schemas/models/applied_order_discounts.js +106 -0
  65. package/lib/schemas/models/index.d.ts +12 -10
  66. package/lib/schemas/models/index.js +12 -10
  67. package/lib/schemas/models/materialized_tenant_delivery_entries.d.ts +31 -9
  68. package/lib/schemas/models/materialized_tenant_delivery_entries.js +32 -11
  69. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.d.ts +129 -0
  70. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.js +86 -0
  71. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.d.ts +71 -0
  72. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.js +38 -0
  73. package/lib/schemas/models/materialized_tenant_delivery_reports.d.ts +10 -1
  74. package/lib/schemas/models/materialized_tenant_delivery_reports.js +10 -1
  75. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +15 -15
  76. package/lib/schemas/types/applied_order_discounts.d.ts +22 -0
  77. package/lib/schemas/types/applied_order_discounts.js +2 -0
  78. package/lib/schemas/types/index.d.ts +14 -12
  79. package/lib/schemas/types/index.js +14 -12
  80. package/lib/schemas/types/materialized_tenant_delivery_entries.d.ts +36 -4
  81. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.d.ts +178 -0
  82. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.js +2 -0
  83. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.d.ts +21 -0
  84. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.js +2 -0
  85. package/lib/schemas/types/materialized_tenant_delivery_reports.d.ts +49 -7
  86. package/lib/tests/materialized-reports/analytics-growth-helpers.test.d.ts +1 -0
  87. package/lib/tests/materialized-reports/analytics-overview-helpers.test.d.ts +1 -0
  88. package/lib/tests/materialized-reports/analytics-performance-helpers.test.d.ts +1 -0
  89. package/lib/tests/materialized-reports/materialized-delivery-accumulation.test.js +56 -19
  90. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.d.ts +1 -0
  91. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.js +91 -0
  92. package/lib/tests/materialized-reports/materialized-delivery-compile.test.js +271 -15
  93. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.d.ts +1 -0
  94. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.js +128 -0
  95. package/lib/tests/materialized-reports/materialized-delivery-fold.test.js +42 -5
  96. package/lib/tests/materialized-reports/materialized-delivery-formatter.test.js +13 -1
  97. package/lib/tests/materialized-reports/materialized-delivery-geo.test.d.ts +1 -0
  98. package/lib/tests/materialized-reports/materialized-delivery-geo.test.js +446 -0
  99. package/lib/tests/materialized-reports/materialized-delivery-plan.test.js +117 -25
  100. package/lib/tests/materialized-reports/materialized-delivery-practical.test.d.ts +1 -0
  101. package/lib/tests/materialized-reports/materialized-delivery-practical.test.js +344 -0
  102. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +14 -0
  103. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +1 -1
  104. package/lib/tests/offer-item-resolution.test.js +1 -4
  105. package/lib/tests/payment-collection-timestamps.test.d.ts +1 -0
  106. package/lib/tests/payment-collection-timestamps.test.js +71 -0
  107. package/package.json +4 -2
@@ -313,7 +313,30 @@ export declare const MATERIALIZED_CASH_SOURCE_LIMIT = 12;
313
313
  */
314
314
  export declare const MATERIALIZED_DELIVERY_REPORT_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
315
315
  /**
316
- * Ordered key filters of the delivery report - `<PLATFORM>:<CITY>` (decision (b4)).
316
+ * Scopes the delivery ENTRY documents (and their flat drill-down projection) are
317
+ * materialized for. The WRITER materializes at most `localMonth` for rows, and every
318
+ * period scope is PAGE-PARTITIONED by source day.
319
+ *
320
+ * An entry document is ONE PAGE (one source day), never a whole period: a month is
321
+ * covered by its 28-31 pages. Counters remain year-capable
322
+ * (`MATERIALIZED_DELIVERY_REPORT_SCOPES`). The details READ has NO month cap: it
323
+ * resolves a broad selection to the `localMonth` scopes it touches and filters rows
324
+ * to the exact selected days.
325
+ */
326
+ export declare const MATERIALIZED_DELIVERY_ENTRY_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
327
+ /**
328
+ * Page key of the DAY-scoped entry document - the day scope is already one day, so it
329
+ * needs no per-source-day partition. Every PERIOD entry scope (week / ISO week / month)
330
+ * is partitioned by the SOURCE local date (`page = <source localDate>`), exactly like
331
+ * `materialized_tenant_discount_entries`.
332
+ *
333
+ * This is what bounds an entry document: one page is one day's rows, never a month's.
334
+ */
335
+ export declare const MATERIALIZED_DELIVERY_ENTRY_PAGE_ALL = "all";
336
+ /**
337
+ * Ordered key filters of the delivery report - `ORDER_STATUS:PLATFORM:CITY`, all joined
338
+ * from the ORDER. Delivery documents carry none of these dimensions, so the report joins
339
+ * by `order_id` and keys on the order's own values.
317
340
  *
318
341
  * Rider is deliberately NOT a key dimension: rider ids are high-cardinality, so rider
319
342
  * analysis is a bounded `riders` map INSIDE each document rather than a partition of
@@ -336,6 +359,77 @@ export declare const MATERIALIZED_DELIVERY_DISTANCE_BUCKETS: {
336
359
  export declare const MATERIALIZED_DELIVERY_RIDER_LIMIT = 50;
337
360
  /** Cap of the per-document area leaderboard (bounded, display-only). */
338
361
  export declare const MATERIALIZED_DELIVERY_AREA_LIMIT = 50;
362
+ /**
363
+ * Token of the ONE overflow row every bounded leaderboard keeps after its top-N.
364
+ *
365
+ * A bounded map would otherwise silently DROP the tail, and a report that drops rows
366
+ * without saying so is indistinguishable from one that never saw them. The overflow
367
+ * row carries the summed counts/money of everything below the cap, so the page can
368
+ * still reconcile against the totals. Reserved: a real rider id or city named
369
+ * `__OTHER__` would collide (ids are ObjectIds / names are human text; documented).
370
+ *
371
+ * Ordering of the TOP-N is deterministic: `count DESC, key ASC` - a non-deterministic
372
+ * tie-break would make two closes of the same day produce different documents.
373
+ */
374
+ export declare const MATERIALIZED_DELIVERY_OTHER_TOKEN = "__OTHER__";
375
+ /**
376
+ * The delivery DEMAND HEAT MAP lives in its OWN collection, never inside the report
377
+ * document: a tenant-day can produce thousands of cells, and the report document is a
378
+ * counters-only document with a hard BSON budget.
379
+ *
380
+ * One document per `tenant_id + scope_context + scope_field + h3_cell`. Only DAY and
381
+ * MONTH scopes are materialized (a heat map is read at those grains); day cells are
382
+ * kept 90 days and month cells 24 months, pruned by the close-day writer.
383
+ */
384
+ export declare const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION = 1;
385
+ /** Small per-scope cap metadata; deliberately NOT stored on every cell. */
386
+ export declare const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME = "materialized_tenant_delivery_geo_scopes";
387
+ export declare const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION = 1;
388
+ /**
389
+ * Bounded by_key map per cell (ORDER_STATUS:PLATFORM:CITY).
390
+ *
391
+ * The CITY is part of the key, so one cell can hold orders from several cities and a
392
+ * city filter can still select the EXACT population inside it. That multiplies the key
393
+ * count by the number of cities in a cell, so the bound is generous: a cell normally
394
+ * holds one or two cities, and the cell's own BSON budget (2 MiB) is the real limit.
395
+ */
396
+ export declare const MATERIALIZED_DELIVERY_GEO_MAX_KEYS = 256;
397
+ /** H3 resolution of a heat cell. */
398
+ export declare const MATERIALIZED_DELIVERY_GEO_RESOLUTION = 8;
399
+ /** Scopes the heat map is materialized for - day + month ONLY. */
400
+ export declare const MATERIALIZED_DELIVERY_GEO_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
401
+ /** Cells with fewer orders than this are not returned by the heat endpoint. */
402
+ export declare const MATERIALIZED_DELIVERY_GEO_MIN_ORDERS = 3;
403
+ /**
404
+ * Hard cap of stored cells per tenant × scope × scope_field. Cells are ranked
405
+ * `orders DESC, h3_cell ASC`; the tail is dropped. Totals never come from the cells -
406
+ * the heat response reads them from the report counters - so a capped map can never
407
+ * misstate the business total.
408
+ */
409
+ export declare const MATERIALIZED_DELIVERY_GEO_MAX_CELLS = 2000;
410
+ /** Day cells are retained 90 days; month cells 24 months. */
411
+ export declare const MATERIALIZED_DELIVERY_GEO_DAY_RETENTION_DAYS = 90;
412
+ export declare const MATERIALIZED_DELIVERY_GEO_MONTH_RETENTION_MONTHS = 24;
413
+ /**
414
+ * Sentinel cell for orders whose coordinates are missing, invalid or (0, 0).
415
+ * It is an AGGREGATE, not a location: the document carries NO `location`, so it can
416
+ * never be mistaken for a point on the map.
417
+ */
418
+ export declare const MATERIALIZED_DELIVERY_GEO_UNKNOWN_CELL = "__UNKNOWN__";
419
+ /**
420
+ * Per-collection BSON budgets (bytes) for the DELIVERY materialization.
421
+ *
422
+ * MongoDB's hard limit is 16 MiB per document. The report and page budgets are the
423
+ * owner-approved practical ceiling (15 MiB), leaving 1 MiB of headroom; a geo cell is
424
+ * a single H3 aggregate and stays at 2 MiB. There is no arbitrary 1 MiB report target.
425
+ *
426
+ * A writer that exceeds its budget fails at COMPILE time with the collection, source day
427
+ * and scope in the message - never midway through the close transaction with a
428
+ * server-side "object too large" error.
429
+ */
430
+ export declare const MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES: number;
431
+ export declare const MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES: number;
432
+ export declare const MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES: number;
339
433
  /**
340
434
  * Scopes materialized by `materialized_tenant_prep_time_reports` — the SUMMARY
341
435
  * range (and the writer's COUNTER scopes).
@@ -10,8 +10,8 @@
10
10
  * explicitly-enabled step.
11
11
  */
12
12
  Object.defineProperty(exports, "__esModule", { value: true });
13
- exports.MATERIALIZED_PREP_TIME_MAX_MINUTES = exports.ALL_MATERIALIZED_PREP_TIME_BUCKET_LABELS = exports.MATERIALIZED_PREP_TIME_BUCKETS = exports.ALL_MATERIALIZED_PREP_TIME_ANCHORS = exports.MATERIALIZED_PREP_TIME_ANCHOR_ENUM = exports.PREP_TIME_KEY_FILTERS = exports.MATERIALIZED_PREP_TIME_ITEM_MAX_READ_DAYS = exports.MATERIALIZED_PREP_TIME_ITEM_SCOPES = exports.MATERIALIZED_PREP_TIME_REPORT_SCOPES = exports.MATERIALIZED_DELIVERY_AREA_LIMIT = exports.MATERIALIZED_DELIVERY_RIDER_LIMIT = exports.MATERIALIZED_DELIVERY_DISTANCE_BUCKETS = exports.DELIVERY_KEY_FILTERS = exports.MATERIALIZED_DELIVERY_REPORT_SCOPES = exports.MATERIALIZED_CASH_SOURCE_LIMIT = exports.CASH_KEY_FILTERS = exports.MATERIALIZED_CASH_REPORT_SCOPES = exports.ALL_MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPES = exports.MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM = exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = exports.MATERIALIZED_DISCOUNT_SOURCE_KEY_PREFIX = exports.MATERIALIZED_DISCOUNT_SOURCE_KEY = exports.ALL_MATERIALIZED_DISCOUNT_RATE_KINDS = exports.MATERIALIZED_DISCOUNT_RATE_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SOURCE_CLASSES = exports.MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM = exports.MATERIALIZED_DISCOUNT_PRICE_OVERRIDE_PREFIX = exports.MATERIALIZED_DISCOUNT_MANUAL_PREFIX = exports.MATERIALIZED_DISCOUNT_SPECIAL_DISCOUNT_ID = exports.MATERIALIZED_DISCOUNT_SOURCE_LIMIT = exports.ALL_MATERIALIZED_DISCOUNT_LEVELS = exports.MATERIALIZED_DISCOUNT_LEVEL_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_ENTRY_KINDS = exports.MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SUB_KINDS = exports.MATERIALIZED_DISCOUNT_SUB_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SLOTS = exports.MATERIALIZED_DISCOUNT_SLOT_ENUM = exports.DISCOUNTS_KEY_FILTERS = exports.MATERIALIZED_DISCOUNT_REPORT_SCOPES = exports.MATERIALIZED_DISCOUNT_ENTRY_PAGE_ALL = exports.SALES_OVERVIEW_KEY_FILTERS = exports.ALL_MATERIALIZED_REPORT_KEY_FILTERS = exports.MATERIALIZED_REPORT_KEY_FILTER_ENUM = exports.MATERIALIZED_CREDIT_BILLS_SCOPES = exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = exports.ALL_MATERIALIZED_REPORT_WINDOW_KINDS = exports.MATERIALIZED_REPORT_WINDOW_KIND_ENUM = exports.ALL_MATERIALIZED_REPORT_SCOPES = exports.MATERIALIZED_REPORT_SCOPE_ENUM = void 0;
14
- exports.ALL_PAYMENTS_COMPARISON_METRICS = exports.PAYMENTS_COMPARISON_METRIC_ENUM = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_SCHEMA_VERSION = exports.PAYMENTS_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_PAYMENTS_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_SCHEMA_VERSION = exports.HOURLY_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_HOURLY_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_SALES_COMPARISON_METRICS = exports.SALES_COMPARISON_METRIC_ENUM = exports.ALL_SALES_COMPARISON_BASELINES = exports.SALES_COMPARISON_BASELINE_ENUM = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_SCHEMA_VERSION = exports.SALES_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_SALES_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_MATERIALIZED_REPORT_TYPES = exports.MATERIALIZED_REPORT_TYPE_ENUM = exports.ALL_MATERIALIZED_PREP_TIME_TARGETS = exports.MATERIALIZED_PREP_TIME_TARGET_ENUM = exports.MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA = exports.MATERIALIZED_PREP_TIME_TOP_BUCKET = void 0;
13
+ exports.MATERIALIZED_DELIVERY_GEO_SCOPES = exports.MATERIALIZED_DELIVERY_GEO_RESOLUTION = exports.MATERIALIZED_DELIVERY_GEO_MAX_KEYS = exports.MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION = exports.MATERIALIZED_DELIVERY_OTHER_TOKEN = exports.MATERIALIZED_DELIVERY_AREA_LIMIT = exports.MATERIALIZED_DELIVERY_RIDER_LIMIT = exports.MATERIALIZED_DELIVERY_DISTANCE_BUCKETS = exports.DELIVERY_KEY_FILTERS = exports.MATERIALIZED_DELIVERY_ENTRY_PAGE_ALL = exports.MATERIALIZED_DELIVERY_ENTRY_SCOPES = exports.MATERIALIZED_DELIVERY_REPORT_SCOPES = exports.MATERIALIZED_CASH_SOURCE_LIMIT = exports.CASH_KEY_FILTERS = exports.MATERIALIZED_CASH_REPORT_SCOPES = exports.ALL_MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPES = exports.MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM = exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = exports.MATERIALIZED_DISCOUNT_SOURCE_KEY_PREFIX = exports.MATERIALIZED_DISCOUNT_SOURCE_KEY = exports.ALL_MATERIALIZED_DISCOUNT_RATE_KINDS = exports.MATERIALIZED_DISCOUNT_RATE_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SOURCE_CLASSES = exports.MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM = exports.MATERIALIZED_DISCOUNT_PRICE_OVERRIDE_PREFIX = exports.MATERIALIZED_DISCOUNT_MANUAL_PREFIX = exports.MATERIALIZED_DISCOUNT_SPECIAL_DISCOUNT_ID = exports.MATERIALIZED_DISCOUNT_SOURCE_LIMIT = exports.ALL_MATERIALIZED_DISCOUNT_LEVELS = exports.MATERIALIZED_DISCOUNT_LEVEL_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_ENTRY_KINDS = exports.MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SUB_KINDS = exports.MATERIALIZED_DISCOUNT_SUB_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SLOTS = exports.MATERIALIZED_DISCOUNT_SLOT_ENUM = exports.DISCOUNTS_KEY_FILTERS = exports.MATERIALIZED_DISCOUNT_REPORT_SCOPES = exports.MATERIALIZED_DISCOUNT_ENTRY_PAGE_ALL = exports.SALES_OVERVIEW_KEY_FILTERS = exports.ALL_MATERIALIZED_REPORT_KEY_FILTERS = exports.MATERIALIZED_REPORT_KEY_FILTER_ENUM = exports.MATERIALIZED_CREDIT_BILLS_SCOPES = exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = exports.ALL_MATERIALIZED_REPORT_WINDOW_KINDS = exports.MATERIALIZED_REPORT_WINDOW_KIND_ENUM = exports.ALL_MATERIALIZED_REPORT_SCOPES = exports.MATERIALIZED_REPORT_SCOPE_ENUM = void 0;
14
+ exports.ALL_PAYMENTS_COMPARISON_METRICS = exports.PAYMENTS_COMPARISON_METRIC_ENUM = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_SCHEMA_VERSION = exports.PAYMENTS_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_PAYMENTS_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_SCHEMA_VERSION = exports.HOURLY_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_HOURLY_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_SALES_COMPARISON_METRICS = exports.SALES_COMPARISON_METRIC_ENUM = exports.ALL_SALES_COMPARISON_BASELINES = exports.SALES_COMPARISON_BASELINE_ENUM = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_SCHEMA_VERSION = exports.SALES_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_SALES_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_MATERIALIZED_REPORT_TYPES = exports.MATERIALIZED_REPORT_TYPE_ENUM = exports.ALL_MATERIALIZED_PREP_TIME_TARGETS = exports.MATERIALIZED_PREP_TIME_TARGET_ENUM = exports.MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA = exports.MATERIALIZED_PREP_TIME_TOP_BUCKET = exports.MATERIALIZED_PREP_TIME_MAX_MINUTES = exports.ALL_MATERIALIZED_PREP_TIME_BUCKET_LABELS = exports.MATERIALIZED_PREP_TIME_BUCKETS = exports.ALL_MATERIALIZED_PREP_TIME_ANCHORS = exports.MATERIALIZED_PREP_TIME_ANCHOR_ENUM = exports.PREP_TIME_KEY_FILTERS = exports.MATERIALIZED_PREP_TIME_ITEM_MAX_READ_DAYS = exports.MATERIALIZED_PREP_TIME_ITEM_SCOPES = exports.MATERIALIZED_PREP_TIME_REPORT_SCOPES = exports.MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES = exports.MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES = exports.MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES = exports.MATERIALIZED_DELIVERY_GEO_UNKNOWN_CELL = exports.MATERIALIZED_DELIVERY_GEO_MONTH_RETENTION_MONTHS = exports.MATERIALIZED_DELIVERY_GEO_DAY_RETENTION_DAYS = exports.MATERIALIZED_DELIVERY_GEO_MAX_CELLS = exports.MATERIALIZED_DELIVERY_GEO_MIN_ORDERS = void 0;
15
15
  /**
16
16
  * Time-scope of a materialized report document. Every document covers exactly
17
17
  * one tenant × one scope context × one scope value (`scope_field`), and the
@@ -106,7 +106,7 @@ var MATERIALIZED_REPORT_KEY_FILTER_ENUM;
106
106
  // additive: the envelope merely declares which dimensions a key encodes.
107
107
  MATERIALIZED_REPORT_KEY_FILTER_ENUM["DRAWER_ID"] = "DRAWER_ID";
108
108
  MATERIALIZED_REPORT_KEY_FILTER_ENUM["REF_TYPE"] = "REF_TYPE";
109
- // Delivery (M4) encodes <PLATFORM>:<CITY>, both joined from the ORDER - a delivery
109
+ // Delivery (M4) encodes <ORDER_STATUS>:<PLATFORM>:<CITY>, all joined from the ORDER - a delivery
110
110
  // document carries neither, so the report joins by order_id and keys on the
111
111
  // order's dimensions. CITY is a new dimension here.
112
112
  MATERIALIZED_REPORT_KEY_FILTER_ENUM["CITY"] = "CITY";
@@ -388,13 +388,42 @@ exports.MATERIALIZED_DELIVERY_REPORT_SCOPES = [
388
388
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
389
389
  ];
390
390
  /**
391
- * Ordered key filters of the delivery report - `<PLATFORM>:<CITY>` (decision (b4)).
391
+ * Scopes the delivery ENTRY documents (and their flat drill-down projection) are
392
+ * materialized for. The WRITER materializes at most `localMonth` for rows, and every
393
+ * period scope is PAGE-PARTITIONED by source day.
394
+ *
395
+ * An entry document is ONE PAGE (one source day), never a whole period: a month is
396
+ * covered by its 28-31 pages. Counters remain year-capable
397
+ * (`MATERIALIZED_DELIVERY_REPORT_SCOPES`). The details READ has NO month cap: it
398
+ * resolves a broad selection to the `localMonth` scopes it touches and filters rows
399
+ * to the exact selected days.
400
+ */
401
+ exports.MATERIALIZED_DELIVERY_ENTRY_SCOPES = [
402
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
403
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK,
404
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR,
405
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
406
+ ];
407
+ /**
408
+ * Page key of the DAY-scoped entry document - the day scope is already one day, so it
409
+ * needs no per-source-day partition. Every PERIOD entry scope (week / ISO week / month)
410
+ * is partitioned by the SOURCE local date (`page = <source localDate>`), exactly like
411
+ * `materialized_tenant_discount_entries`.
412
+ *
413
+ * This is what bounds an entry document: one page is one day's rows, never a month's.
414
+ */
415
+ exports.MATERIALIZED_DELIVERY_ENTRY_PAGE_ALL = 'all';
416
+ /**
417
+ * Ordered key filters of the delivery report - `ORDER_STATUS:PLATFORM:CITY`, all joined
418
+ * from the ORDER. Delivery documents carry none of these dimensions, so the report joins
419
+ * by `order_id` and keys on the order's own values.
392
420
  *
393
421
  * Rider is deliberately NOT a key dimension: rider ids are high-cardinality, so rider
394
422
  * analysis is a bounded `riders` map INSIDE each document rather than a partition of
395
423
  * the key space.
396
424
  */
397
425
  exports.DELIVERY_KEY_FILTERS = [
426
+ MATERIALIZED_REPORT_KEY_FILTER_ENUM.ORDER_STATUS,
398
427
  MATERIALIZED_REPORT_KEY_FILTER_ENUM.PLATFORM,
399
428
  MATERIALIZED_REPORT_KEY_FILTER_ENUM.CITY,
400
429
  ];
@@ -417,6 +446,81 @@ exports.MATERIALIZED_DELIVERY_DISTANCE_BUCKETS = [
417
446
  exports.MATERIALIZED_DELIVERY_RIDER_LIMIT = 50;
418
447
  /** Cap of the per-document area leaderboard (bounded, display-only). */
419
448
  exports.MATERIALIZED_DELIVERY_AREA_LIMIT = 50;
449
+ /**
450
+ * Token of the ONE overflow row every bounded leaderboard keeps after its top-N.
451
+ *
452
+ * A bounded map would otherwise silently DROP the tail, and a report that drops rows
453
+ * without saying so is indistinguishable from one that never saw them. The overflow
454
+ * row carries the summed counts/money of everything below the cap, so the page can
455
+ * still reconcile against the totals. Reserved: a real rider id or city named
456
+ * `__OTHER__` would collide (ids are ObjectIds / names are human text; documented).
457
+ *
458
+ * Ordering of the TOP-N is deterministic: `count DESC, key ASC` - a non-deterministic
459
+ * tie-break would make two closes of the same day produce different documents.
460
+ */
461
+ exports.MATERIALIZED_DELIVERY_OTHER_TOKEN = '__OTHER__';
462
+ /* ---------------- Delivery geo heat map (M4.1) ---------------- */
463
+ /**
464
+ * The delivery DEMAND HEAT MAP lives in its OWN collection, never inside the report
465
+ * document: a tenant-day can produce thousands of cells, and the report document is a
466
+ * counters-only document with a hard BSON budget.
467
+ *
468
+ * One document per `tenant_id + scope_context + scope_field + h3_cell`. Only DAY and
469
+ * MONTH scopes are materialized (a heat map is read at those grains); day cells are
470
+ * kept 90 days and month cells 24 months, pruned by the close-day writer.
471
+ */
472
+ exports.MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION = 1;
473
+ /** Small per-scope cap metadata; deliberately NOT stored on every cell. */
474
+ exports.MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_NAME = 'materialized_tenant_delivery_geo_scopes';
475
+ exports.MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION = 1;
476
+ /**
477
+ * Bounded by_key map per cell (ORDER_STATUS:PLATFORM:CITY).
478
+ *
479
+ * The CITY is part of the key, so one cell can hold orders from several cities and a
480
+ * city filter can still select the EXACT population inside it. That multiplies the key
481
+ * count by the number of cities in a cell, so the bound is generous: a cell normally
482
+ * holds one or two cities, and the cell's own BSON budget (2 MiB) is the real limit.
483
+ */
484
+ exports.MATERIALIZED_DELIVERY_GEO_MAX_KEYS = 256;
485
+ /** H3 resolution of a heat cell. */
486
+ exports.MATERIALIZED_DELIVERY_GEO_RESOLUTION = 8;
487
+ /** Scopes the heat map is materialized for - day + month ONLY. */
488
+ exports.MATERIALIZED_DELIVERY_GEO_SCOPES = [
489
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
490
+ MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
491
+ ];
492
+ /** Cells with fewer orders than this are not returned by the heat endpoint. */
493
+ exports.MATERIALIZED_DELIVERY_GEO_MIN_ORDERS = 3;
494
+ /**
495
+ * Hard cap of stored cells per tenant × scope × scope_field. Cells are ranked
496
+ * `orders DESC, h3_cell ASC`; the tail is dropped. Totals never come from the cells -
497
+ * the heat response reads them from the report counters - so a capped map can never
498
+ * misstate the business total.
499
+ */
500
+ exports.MATERIALIZED_DELIVERY_GEO_MAX_CELLS = 2000;
501
+ /** Day cells are retained 90 days; month cells 24 months. */
502
+ exports.MATERIALIZED_DELIVERY_GEO_DAY_RETENTION_DAYS = 90;
503
+ exports.MATERIALIZED_DELIVERY_GEO_MONTH_RETENTION_MONTHS = 24;
504
+ /**
505
+ * Sentinel cell for orders whose coordinates are missing, invalid or (0, 0).
506
+ * It is an AGGREGATE, not a location: the document carries NO `location`, so it can
507
+ * never be mistaken for a point on the map.
508
+ */
509
+ exports.MATERIALIZED_DELIVERY_GEO_UNKNOWN_CELL = '__UNKNOWN__';
510
+ /**
511
+ * Per-collection BSON budgets (bytes) for the DELIVERY materialization.
512
+ *
513
+ * MongoDB's hard limit is 16 MiB per document. The report and page budgets are the
514
+ * owner-approved practical ceiling (15 MiB), leaving 1 MiB of headroom; a geo cell is
515
+ * a single H3 aggregate and stays at 2 MiB. There is no arbitrary 1 MiB report target.
516
+ *
517
+ * A writer that exceeds its budget fails at COMPILE time with the collection, source day
518
+ * and scope in the message - never midway through the close transaction with a
519
+ * server-side "object too large" error.
520
+ */
521
+ exports.MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES = 15 * 1024 * 1024;
522
+ exports.MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES = 15 * 1024 * 1024;
523
+ exports.MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES = 2 * 1024 * 1024;
420
524
  /* ======================================================================== */
421
525
  /* Prep time report (M2) */
422
526
  /* ======================================================================== */
@@ -31,3 +31,12 @@ export declare enum DELIVERY_STATUS_ENUM {
31
31
  CANCELLED = "CANCELLED"
32
32
  }
33
33
  export declare const ALL_DELIVERY_STATUS: DELIVERY_STATUS_ENUM[];
34
+ /**
35
+ * OPEN delivery statuses: not yet delivered and not cancelled.
36
+ *
37
+ * This is the ONE definition the statement's "In progress" view, the volume
38
+ * chart's "Open" bucket and the delivery summary use. Do not hard-code a
39
+ * subset in a reader: a PENDING/ASSIGNED record is still open work even though
40
+ * its stored status is not literally `IN_PROGRESS`.
41
+ */
42
+ export declare const DELIVERY_OPEN_STATUSES: readonly DELIVERY_STATUS_ENUM[];
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  // Auto-split from constants/ENUMS.ts — see ENUMS.ts barrel for exports.
3
3
  Object.defineProperty(exports, "__esModule", { value: true });
4
- exports.ALL_DELIVERY_STATUS = exports.DELIVERY_STATUS_ENUM = exports.ALL_RIDER_EARNINGS_STATUS = exports.RIDER_EARNINGS_STATUS_ENUM = exports.ALL_RIDER_FEE_TYPES = exports.RIDER_FEE_TYPE_ENUM = exports.ALL_DELIVERY_AREAS_SEARCH_TYPES = exports.DELIVERY_AREAS_SEARCH_TYPE_ENUM = exports.ALL_RESERVATION_STATUS_TYPES = exports.RESERVATION_STATUS_ENUM = void 0;
4
+ exports.DELIVERY_OPEN_STATUSES = exports.ALL_DELIVERY_STATUS = exports.DELIVERY_STATUS_ENUM = exports.ALL_RIDER_EARNINGS_STATUS = exports.RIDER_EARNINGS_STATUS_ENUM = exports.ALL_RIDER_FEE_TYPES = exports.RIDER_FEE_TYPE_ENUM = exports.ALL_DELIVERY_AREAS_SEARCH_TYPES = exports.DELIVERY_AREAS_SEARCH_TYPE_ENUM = exports.ALL_RESERVATION_STATUS_TYPES = exports.RESERVATION_STATUS_ENUM = void 0;
5
5
  var RESERVATION_STATUS_ENUM;
6
6
  (function (RESERVATION_STATUS_ENUM) {
7
7
  RESERVATION_STATUS_ENUM["PENDING"] = "PENDING";
@@ -43,4 +43,17 @@ var DELIVERY_STATUS_ENUM;
43
43
  DELIVERY_STATUS_ENUM["CANCELLED"] = "CANCELLED";
44
44
  })(DELIVERY_STATUS_ENUM || (exports.DELIVERY_STATUS_ENUM = DELIVERY_STATUS_ENUM = {}));
45
45
  exports.ALL_DELIVERY_STATUS = Object.values(DELIVERY_STATUS_ENUM);
46
+ /**
47
+ * OPEN delivery statuses: not yet delivered and not cancelled.
48
+ *
49
+ * This is the ONE definition the statement's "In progress" view, the volume
50
+ * chart's "Open" bucket and the delivery summary use. Do not hard-code a
51
+ * subset in a reader: a PENDING/ASSIGNED record is still open work even though
52
+ * its stored status is not literally `IN_PROGRESS`.
53
+ */
54
+ exports.DELIVERY_OPEN_STATUSES = [
55
+ DELIVERY_STATUS_ENUM.PENDING,
56
+ DELIVERY_STATUS_ENUM.ASSIGNED,
57
+ DELIVERY_STATUS_ENUM.IN_PROGRESS,
58
+ ];
46
59
  // ======================>> <<====================== //
@@ -16,9 +16,14 @@ export * from './materialized-payments-comparison-close-day-helpers';
16
16
  export * from './materialized-payments-comparison-compile-helpers';
17
17
  export * from './materialized-cash-accumulator-helpers';
18
18
  export * from './materialized-delivery-accumulator-helpers';
19
+ export * from './materialized-delivery-rows';
20
+ export * from './materialized-delivery-entry-pages';
21
+ export * from './materialized-document-size';
22
+ export * from './materialized-tenant-delivery-geo-helpers';
19
23
  export * from './materialized-delivery-compile-helpers';
20
24
  export * from './materialized-delivery-classification-helpers';
21
25
  export * from './materialized-delivery-close-day-helpers';
26
+ export * from './materialized-delivery-index-migration';
22
27
  export * from './materialized-day-input-signature';
23
28
  export * from './materialized-cash-classification-helpers';
24
29
  export * from './materialized-cash-close-day-helpers';
@@ -32,9 +32,14 @@ __exportStar(require("./materialized-payments-comparison-close-day-helpers"), ex
32
32
  __exportStar(require("./materialized-payments-comparison-compile-helpers"), exports);
33
33
  __exportStar(require("./materialized-cash-accumulator-helpers"), exports);
34
34
  __exportStar(require("./materialized-delivery-accumulator-helpers"), exports);
35
+ __exportStar(require("./materialized-delivery-rows"), exports);
36
+ __exportStar(require("./materialized-delivery-entry-pages"), exports);
37
+ __exportStar(require("./materialized-document-size"), exports);
38
+ __exportStar(require("./materialized-tenant-delivery-geo-helpers"), exports);
35
39
  __exportStar(require("./materialized-delivery-compile-helpers"), exports);
36
40
  __exportStar(require("./materialized-delivery-classification-helpers"), exports);
37
41
  __exportStar(require("./materialized-delivery-close-day-helpers"), exports);
42
+ __exportStar(require("./materialized-delivery-index-migration"), exports);
38
43
  __exportStar(require("./materialized-day-input-signature"), exports);
39
44
  __exportStar(require("./materialized-cash-classification-helpers"), exports);
40
45
  __exportStar(require("./materialized-cash-close-day-helpers"), exports);
@@ -2,6 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.mergeMaterializedDeliveryCounters = mergeMaterializedDeliveryCounters;
4
4
  const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
5
+ const materialized_delivery_rows_1 = require("./materialized-delivery-rows");
5
6
  /**
6
7
  * M4 delivery - folding counters across days into a PERIOD document.
7
8
  *
@@ -24,47 +25,6 @@ const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
24
25
  * exactly one bucket per document.
25
26
  */
26
27
  const num = (value) => Number(value) || 0;
27
- const earlierOf = (current, candidate) => {
28
- const time = candidate == null ? NaN : new Date(candidate).getTime();
29
- if (Number.isNaN(time))
30
- return current;
31
- if (current == null || time < new Date(current).getTime())
32
- return new Date(time);
33
- return current;
34
- };
35
- const laterOf = (current, candidate) => {
36
- const time = candidate == null ? NaN : new Date(candidate).getTime();
37
- if (Number.isNaN(time))
38
- return current;
39
- if (current == null || time > new Date(current).getTime())
40
- return new Date(time);
41
- return current;
42
- };
43
- /** Merges one rider row into another, MIN/MAX on the tenure bounds. */
44
- function mergeRiderRow(target, source) {
45
- target.count += num(source?.count);
46
- target.completed_count += num(source?.completed_count);
47
- target.cancelled_count += num(source?.cancelled_count);
48
- target.in_progress_count += num(source?.in_progress_count);
49
- target.rider_revenue_amount += num(source?.rider_revenue_amount);
50
- target.distance_sum_meters += num(source?.distance_sum_meters);
51
- target.rider_name ?? (target.rider_name = source?.rider_name ?? null);
52
- // MIN / MAX - never a sum, and never just the newest document value.
53
- target.first_delivery_at = earlierOf(target.first_delivery_at, source?.first_delivery_at);
54
- target.last_delivery_at = laterOf(target.last_delivery_at, source?.last_delivery_at);
55
- }
56
- /** Merges one area row into another, summing the hour heat map. */
57
- function mergeAreaRow(target, source) {
58
- target.count += num(source?.count);
59
- target.completed_count += num(source?.completed_count);
60
- target.cancelled_count += num(source?.cancelled_count);
61
- target.rider_revenue_amount += num(source?.rider_revenue_amount);
62
- target.distance_sum_meters += num(source?.distance_sum_meters);
63
- target.by_hour ?? (target.by_hour = {});
64
- for (const [hour, value] of Object.entries(source?.by_hour ?? {})) {
65
- target.by_hour[hour] = num(target.by_hour[hour]) + num(value);
66
- }
67
- }
68
28
  /**
69
29
  * Merges `source` into `target`, IN PLACE. Null-safe: a source block missing a sub-object
70
30
  * is treated as zeroes rather than throwing, so one malformed historical document cannot
@@ -122,6 +82,9 @@ function mergeMaterializedDeliveryCounters(target, source) {
122
82
  const tt = target.timing;
123
83
  const st = source.timing;
124
84
  tt.graded_count += num(st.graded_count);
85
+ tt.dispatch_lag_count += num(st.dispatch_lag_count);
86
+ tt.complete_count += num(st.complete_count);
87
+ tt.total_count += num(st.total_count);
125
88
  tt.dispatch_lag_sum_minutes += num(st.dispatch_lag_sum_minutes);
126
89
  tt.complete_sum_minutes += num(st.complete_sum_minutes);
127
90
  tt.total_sum_minutes += num(st.total_sum_minutes);
@@ -144,30 +107,13 @@ function mergeMaterializedDeliveryCounters(target, source) {
144
107
  }
145
108
  for (const [riderId, row] of Object.entries(source.riders ?? {})) {
146
109
  target.riders ?? (target.riders = {});
147
- (_a = target.riders)[riderId] ?? (_a[riderId] = {
148
- rider_name: null,
149
- count: 0,
150
- completed_count: 0,
151
- cancelled_count: 0,
152
- in_progress_count: 0,
153
- rider_revenue_amount: 0,
154
- distance_sum_meters: 0,
155
- first_delivery_at: null,
156
- last_delivery_at: null,
157
- });
158
- mergeRiderRow(target.riders[riderId], row);
110
+ (_a = target.riders)[riderId] ?? (_a[riderId] = (0, materialized_delivery_rows_1.emptyMaterializedDeliveryRiderRow)());
111
+ (0, materialized_delivery_rows_1.mergeMaterializedDeliveryRiderRow)(target.riders[riderId], row);
159
112
  }
160
113
  for (const [city, row] of Object.entries(source.areas ?? {})) {
161
114
  target.areas ?? (target.areas = {});
162
- (_b = target.areas)[city] ?? (_b[city] = {
163
- count: 0,
164
- completed_count: 0,
165
- cancelled_count: 0,
166
- rider_revenue_amount: 0,
167
- distance_sum_meters: 0,
168
- by_hour: {},
169
- });
170
- mergeAreaRow(target.areas[city], row);
115
+ (_b = target.areas)[city] ?? (_b[city] = (0, materialized_delivery_rows_1.emptyMaterializedDeliveryAreaRow)());
116
+ (0, materialized_delivery_rows_1.mergeMaterializedDeliveryAreaRow)(target.areas[city], row);
171
117
  }
172
118
  return target;
173
119
  }
@@ -1,7 +1,7 @@
1
1
  import { DELIVERY_STATUS_ENUM } from '../../constants/enums/delivery';
2
2
  import { IDelivery } from '../../schemas/types/deliveries';
3
- import { IOrderDeliveryDetails } from '../../schemas/types/orders';
4
3
  import { IMaterializedDeliveryCounters } from '../../schemas/types/materialized_tenant_delivery_reports';
4
+ import { IOrderDeliveryDetails } from '../../schemas/types/orders';
5
5
  /**
6
6
  * M4 delivery - key grammar, the order join, and the accumulators.
7
7
  *
@@ -18,7 +18,7 @@ import { IMaterializedDeliveryCounters } from '../../schemas/types/materialized_
18
18
  * ## The join
19
19
  *
20
20
  * A delivery document carries neither the platform nor the city, so the key
21
- * `<PLATFORM>:<CITY>` and every order-derived money figure come from joining by
21
+ * `<ORDER_STATUS>:<PLATFORM>:<CITY>` and every order-derived money figure come from joining by
22
22
  * `order_id`. An order with no platform/city details falls into an explicit UNKNOWN
23
23
  * bucket rather than being dropped silently - a missing dimension must still show up in
24
24
  * the totals.
@@ -34,10 +34,11 @@ import { IMaterializedDeliveryCounters } from '../../schemas/types/materialized_
34
34
  /** The key token used when a dimension is missing, so nothing is silently dropped. */
35
35
  export declare const DELIVERY_UNKNOWN_TOKEN = "UNKNOWN";
36
36
  export declare const MATERIALIZED_DELIVERY_KEY_SEPARATOR = ":";
37
- /** Builds `<PLATFORM>:<CITY>`, substituting UNKNOWN for missing dimensions. */
38
- export declare function buildMaterializedDeliveryKey(platform: unknown, city: unknown): string;
37
+ /** Builds `<ORDER_STATUS>:<PLATFORM>:<CITY>`, substituting UNKNOWN for missing dimensions. */
38
+ export declare function buildMaterializedDeliveryKey(orderStatus: unknown, platform: unknown, city: unknown): string;
39
39
  /** Splits a key back into its parts, or null when it is malformed. */
40
40
  export declare function parseMaterializedDeliveryKey(key: unknown): {
41
+ order_status: string;
41
42
  platform: string;
42
43
  city: string;
43
44
  } | null;
@@ -59,27 +60,45 @@ export interface IDeliveryOrderSource {
59
60
  updatedAt?: Date | string | null;
60
61
  order_number?: number | null;
61
62
  platform?: string | null;
63
+ order_status?: string | null;
62
64
  createdAt?: Date | string | null;
65
+ /** Tenant-local hour of the ORDER - the only hour the delivery report may use. */
66
+ localHour?: number | null;
67
+ /** Tenant-local minute inside that hour; absent means :00. */
68
+ localMinute?: number | null;
69
+ localDate?: string | null;
63
70
  net_sale_amount?: number | null;
64
71
  amount_earned?: number | null;
65
72
  amount_collected?: number | null;
66
- amount_refunded?: number | null;
67
73
  total_discount_applied?: number | null;
68
74
  tip_amount?: number | null;
69
75
  gst_amount?: number | null;
70
76
  tax_amount?: number | null;
77
+ /**
78
+ * Refund money lives ONLY on the payment rows - `IOrder` declares no order-level
79
+ * `amount_refunded`. Reading an undeclared field would silently report every refund
80
+ * as zero, so the accumulator sums this declared source.
81
+ */
82
+ payments?: {
83
+ amount_refunded?: number | null;
84
+ }[] | null;
71
85
  delivery_details?: (Partial<IOrderDeliveryDetails> & {
72
86
  delivery_charge?: number | null;
73
87
  delivery_charge_amount?: number | null;
74
88
  }) | null;
75
89
  }
76
- /** Raw delivery fields this classifier reads (all optional at the boundary). */
90
+ /**
91
+ * Raw delivery fields this classifier reads (all optional at the boundary).
92
+ *
93
+ * `localHour` is DELIBERATELY absent: the delivery write path does not carry one, and
94
+ * the report must not invent a tenant-local hour from a server clock. Order demand is
95
+ * bucketed by the JOINED order's `localHour`.
96
+ */
77
97
  export type TDeliverySource = Partial<Omit<IDelivery, 'status' | '_id' | 'order_id' | 'rider_earnings'>> & {
78
98
  _id?: string;
79
99
  order_id?: string;
80
100
  status?: DELIVERY_STATUS_ENUM | string;
81
101
  rider_earnings?: Partial<NonNullable<IDelivery['rider_earnings']>> | null;
82
- localHour?: number | null;
83
102
  };
84
103
  export interface IDeliveryAccumulator {
85
104
  counters: IMaterializedDeliveryCounters;
@@ -97,7 +116,7 @@ export declare function isDeliveryOrder(order: IDeliveryOrderSource): boolean;
97
116
  * Order-side money is counted HERE rather than on the delivery, because a cancelled
98
117
  * delivery must not lose the order figures the operator recognises.
99
118
  */
100
- export declare function addDeliveryOrder(acc: IDeliveryAccumulator, order: IDeliveryOrderSource): void;
119
+ export declare function addDeliveryOrder(acc: IDeliveryAccumulator, order: IDeliveryOrderSource, key?: string): void;
101
120
  /**
102
121
  * Consumes ONE delivery document - the APP-SIDE half of the join.
103
122
  *
@@ -107,10 +126,18 @@ export declare function addDeliveryOrder(acc: IDeliveryAccumulator, order: IDeli
107
126
  */
108
127
  export declare function addDelivery(acc: IDeliveryAccumulator, delivery: TDeliverySource, order: IDeliveryOrderSource | null, key: string): void;
109
128
  /**
110
- * Computes the DERIVED adoption figures and prunes the bounded maps.
129
+ * Computes the DERIVED adoption figures of one key.
111
130
  *
112
131
  * Call ONCE per key, after both stages have been consumed. `off_app_count` is a set
113
132
  * difference, so an order reassigned to a second rider is NOT counted as off-app even
114
133
  * though there are more deliveries than orders.
134
+ *
135
+ * The per-key ORDER SETS are also what fill the area row's order-side adoption counters:
136
+ * a key maps to exactly one RESOLVED area, so `delivery_order_count` /
137
+ * `delivered_via_app_count` of the key ARE that area's figures for this document.
138
+ *
139
+ * The bounded maps are NOT pruned here: the rider cap applies to the whole DOCUMENT
140
+ * (`pruneDocumentDeliveryRiders`) and the city cap is applied when the key is resolved
141
+ * (`buildDeliveryCityResolver`).
115
142
  */
116
143
  export declare function finalizeDeliveryAccumulator(acc: IDeliveryAccumulator): IMaterializedDeliveryCounters;