@managesome/eposmatic-toolkit 0.4.51 → 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 (97) 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/helpers/utils/offer-item-resolution.js +39 -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/index.js +14 -12
  26. package/esm/schemas/types/materialized_tenant_delivery_geo_cells.js +1 -0
  27. package/esm/schemas/types/materialized_tenant_delivery_geo_scopes.js +1 -0
  28. package/lib/constants/MATERIALIZED_REPORTS.d.ts +95 -1
  29. package/lib/constants/MATERIALIZED_REPORTS.js +108 -4
  30. package/lib/constants/enums/delivery.d.ts +9 -0
  31. package/lib/constants/enums/delivery.js +14 -1
  32. package/lib/helpers/materialized-reports/index.d.ts +5 -0
  33. package/lib/helpers/materialized-reports/index.js +5 -0
  34. package/lib/helpers/materialized-reports/materialized-delivery-accumulator-helpers.js +8 -62
  35. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.d.ts +36 -9
  36. package/lib/helpers/materialized-reports/materialized-delivery-classification-helpers.js +94 -72
  37. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.d.ts +23 -26
  38. package/lib/helpers/materialized-reports/materialized-delivery-close-day-helpers.js +121 -150
  39. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.d.ts +44 -5
  40. package/lib/helpers/materialized-reports/materialized-delivery-compile-helpers.js +306 -69
  41. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.d.ts +128 -0
  42. package/lib/helpers/materialized-reports/materialized-delivery-entry-pages.js +322 -0
  43. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.d.ts +48 -0
  44. package/lib/helpers/materialized-reports/materialized-delivery-index-migration.js +108 -0
  45. package/lib/helpers/materialized-reports/materialized-delivery-rows.d.ts +15 -0
  46. package/lib/helpers/materialized-reports/materialized-delivery-rows.js +115 -0
  47. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.d.ts +17 -0
  48. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.js +35 -0
  49. package/lib/helpers/materialized-reports/materialized-document-size.d.ts +47 -0
  50. package/lib/helpers/materialized-reports/materialized-document-size.js +73 -0
  51. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +28 -13
  52. package/lib/helpers/materialized-reports/materialized-integer-contract.js +10 -1
  53. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +2 -90
  54. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.d.ts +186 -0
  55. package/lib/helpers/materialized-reports/materialized-tenant-delivery-geo-helpers.js +620 -0
  56. package/lib/helpers/materialized-reports/scope-helpers.d.ts +8 -0
  57. package/lib/helpers/materialized-reports/scope-helpers.js +99 -0
  58. package/lib/helpers/materialized-reports/tenant-delivery-formatter.d.ts +41 -0
  59. package/lib/helpers/materialized-reports/tenant-delivery-formatter.js +70 -20
  60. package/lib/helpers/utils/offer-item-resolution.d.ts +28 -0
  61. package/lib/helpers/utils/offer-item-resolution.js +41 -0
  62. package/lib/schemas/models/index.d.ts +12 -10
  63. package/lib/schemas/models/index.js +12 -10
  64. package/lib/schemas/models/materialized_tenant_delivery_entries.d.ts +31 -9
  65. package/lib/schemas/models/materialized_tenant_delivery_entries.js +32 -11
  66. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.d.ts +129 -0
  67. package/lib/schemas/models/materialized_tenant_delivery_geo_cells.js +86 -0
  68. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.d.ts +71 -0
  69. package/lib/schemas/models/materialized_tenant_delivery_geo_scopes.js +38 -0
  70. package/lib/schemas/models/materialized_tenant_delivery_reports.d.ts +10 -1
  71. package/lib/schemas/models/materialized_tenant_delivery_reports.js +10 -1
  72. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +15 -15
  73. package/lib/schemas/types/index.d.ts +14 -12
  74. package/lib/schemas/types/index.js +14 -12
  75. package/lib/schemas/types/materialized_tenant_delivery_entries.d.ts +36 -4
  76. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.d.ts +178 -0
  77. package/lib/schemas/types/materialized_tenant_delivery_geo_cells.js +2 -0
  78. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.d.ts +21 -0
  79. package/lib/schemas/types/materialized_tenant_delivery_geo_scopes.js +2 -0
  80. package/lib/schemas/types/materialized_tenant_delivery_reports.d.ts +49 -7
  81. package/lib/tests/materialized-reports/materialized-delivery-accumulation.test.js +56 -19
  82. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.d.ts +1 -0
  83. package/lib/tests/materialized-reports/materialized-delivery-budgets.test.js +91 -0
  84. package/lib/tests/materialized-reports/materialized-delivery-compile.test.js +271 -15
  85. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.d.ts +1 -0
  86. package/lib/tests/materialized-reports/materialized-delivery-final-audit.test.js +128 -0
  87. package/lib/tests/materialized-reports/materialized-delivery-fold.test.js +42 -5
  88. package/lib/tests/materialized-reports/materialized-delivery-formatter.test.js +13 -1
  89. package/lib/tests/materialized-reports/materialized-delivery-geo.test.d.ts +1 -0
  90. package/lib/tests/materialized-reports/materialized-delivery-geo.test.js +446 -0
  91. package/lib/tests/materialized-reports/materialized-delivery-plan.test.js +117 -25
  92. package/lib/tests/materialized-reports/materialized-delivery-practical.test.d.ts +1 -0
  93. package/lib/tests/materialized-reports/materialized-delivery-practical.test.js +344 -0
  94. package/lib/tests/materialized-reports/materialized-integer-contract.test.js +14 -0
  95. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +1 -1
  96. package/lib/tests/offer-item-resolution.test.js +57 -0
  97. package/package.json +4 -2
@@ -132,3 +132,101 @@ export function getMaterializedPeriodDayScopeRange(localDate) {
132
132
  lte: toKey(new Date(Date.UTC(year, 11, 31 + 7))),
133
133
  };
134
134
  }
135
+ /* ------------------------------------------------------------------------ */
136
+ /* Period sibling-day enumeration */
137
+ /* ------------------------------------------------------------------------ */
138
+ const pad2 = (value) => String(value).padStart(2, '0');
139
+ const toLocalDateKey = (date) => `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(date.getUTCDate())}`;
140
+ const addUtcDays = (date, amount) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount));
141
+ const addMonthDays = (year, month, count, days) => {
142
+ if (!Number.isInteger(year) || !Number.isInteger(month) || month < 1 || month > 12)
143
+ return false;
144
+ for (let offset = 0; offset < count; offset += 1) {
145
+ const date = new Date(Date.UTC(year, month - 1 + offset, 1));
146
+ const monthYear = date.getUTCFullYear();
147
+ const monthNumber = date.getUTCMonth() + 1;
148
+ const last = new Date(Date.UTC(monthYear, monthNumber, 0)).getUTCDate();
149
+ for (let day = 1; day <= last; day += 1) {
150
+ days.add(`${monthYear}-${pad2(monthNumber)}-${pad2(day)}`);
151
+ }
152
+ }
153
+ return true;
154
+ };
155
+ const addPeriodDays = (scope, scopeField, days) => {
156
+ switch (scope) {
157
+ case MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK: {
158
+ const parts = parseMaterializedLocalDate(scopeField);
159
+ if (parts == null)
160
+ return false;
161
+ const start = new Date(Date.UTC(parts.year, parts.month - 1, parts.day));
162
+ if (start.getUTCDay() !== 0)
163
+ return false;
164
+ for (let offset = 0; offset < 7; offset += 1)
165
+ days.add(toLocalDateKey(addUtcDays(start, offset)));
166
+ return true;
167
+ }
168
+ case MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR: {
169
+ const match = /^(\d{4})-W(\d{2})$/.exec(scopeField);
170
+ if (match == null)
171
+ return false;
172
+ const weekYear = Number(match[1]);
173
+ const week = Number(match[2]);
174
+ if (!Number.isInteger(week) || week < 1 || week > 53)
175
+ return false;
176
+ const jan4 = new Date(Date.UTC(weekYear, 0, 4));
177
+ const isoWeekday = jan4.getUTCDay() || 7;
178
+ const weekOneMonday = addUtcDays(jan4, 1 - isoWeekday);
179
+ const start = addUtcDays(weekOneMonday, (week - 1) * 7);
180
+ for (let offset = 0; offset < 7; offset += 1)
181
+ days.add(toLocalDateKey(addUtcDays(start, offset)));
182
+ return true;
183
+ }
184
+ case MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH: {
185
+ const match = /^(\d{4})-(\d{2})$/.exec(scopeField);
186
+ if (match == null)
187
+ return false;
188
+ return addMonthDays(Number(match[1]), Number(match[2]), 1, days);
189
+ }
190
+ case MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_QUARTER: {
191
+ const match = /^(\d{4})-Q([1-4])$/.exec(scopeField);
192
+ if (match == null)
193
+ return false;
194
+ return addMonthDays(Number(match[1]), (Number(match[2]) - 1) * 3 + 1, 3, days);
195
+ }
196
+ case MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_SEMESTER: {
197
+ const match = /^(\d{4})-S([12])$/.exec(scopeField);
198
+ if (match == null)
199
+ return false;
200
+ return addMonthDays(Number(match[1]), (Number(match[2]) - 1) * 6 + 1, 6, days);
201
+ }
202
+ case MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR: {
203
+ const match = /^(\d{4})$/.exec(scopeField);
204
+ if (match == null)
205
+ return false;
206
+ return addMonthDays(Number(match[1]), 1, 12, days);
207
+ }
208
+ default:
209
+ return false;
210
+ }
211
+ };
212
+ /**
213
+ * Every `localDate` label whose DAY documents can contribute to the period scopes the
214
+ * given date rolls into. The close-day writer uses it to fetch exactly the sibling DAY
215
+ * documents a period re-fold needs - never a full-period document.
216
+ *
217
+ * Returns `null` (never throws) for a malformed date or scope field.
218
+ */
219
+ export function enumerateMaterializedPeriodDays(localDate, scopes) {
220
+ const periodFields = getMaterializedPeriodScopeFields(localDate);
221
+ if (periodFields == null)
222
+ return null;
223
+ const days = new Set([localDate]);
224
+ for (const scope of scopes) {
225
+ const scopeField = periodFields[scope];
226
+ if (typeof scopeField !== 'string' || scopeField.length === 0)
227
+ return null;
228
+ if (!addPeriodDays(scope, scopeField, days))
229
+ return null;
230
+ }
231
+ return [...days].sort();
232
+ }
@@ -1,7 +1,7 @@
1
+ import { MATERIALIZED_DELIVERY_DISTANCE_BUCKETS, MATERIALIZED_REPORT_SCOPE_ENUM, } from '../../constants/MATERIALIZED_REPORTS';
1
2
  import { convertPriceFromCents } from '../utils/price-conversion';
2
- import { DELIVERY_UNKNOWN_TOKEN, freshDeliveryCounters, parseMaterializedDeliveryKey, } from './materialized-delivery-classification-helpers';
3
3
  import { mergeMaterializedDeliveryCounters } from './materialized-delivery-accumulator-helpers';
4
- import { MATERIALIZED_DELIVERY_DISTANCE_BUCKETS, MATERIALIZED_REPORT_SCOPE_ENUM, } from '../../constants/MATERIALIZED_REPORTS';
4
+ import { DELIVERY_UNKNOWN_TOKEN, freshDeliveryCounters, parseMaterializedDeliveryKey, } from './materialized-delivery-classification-helpers';
5
5
  const toDecimal = (cents) => convertPriceFromCents(cents ?? 0);
6
6
  const km = (meters) => Math.round(((meters ?? 0) / 1000) * 100) / 100;
7
7
  const safeAverage = (total, count) => count > 0 ? Math.round((total / count) * 100) / 100 : null;
@@ -11,6 +11,10 @@ function keyPassesFilters(key, filters) {
11
11
  const parsed = parseMaterializedDeliveryKey(key);
12
12
  if (parsed == null)
13
13
  return true; // never hide a key we cannot parse
14
+ const orderStatuses = filters.order_statuses;
15
+ if (orderStatuses != null && orderStatuses.length > 0 && !orderStatuses.includes(parsed.order_status)) {
16
+ return false;
17
+ }
14
18
  const platforms = filters.platforms;
15
19
  if (platforms != null && platforms.length > 0 && !platforms.includes(parsed.platform))
16
20
  return false;
@@ -95,17 +99,21 @@ function buildPageForTenant(tenantIds, docs, filters) {
95
99
  last_delivery_at: row.last_delivery_at == null ? null : new Date(row.last_delivery_at),
96
100
  });
97
101
  }
98
- riders.sort((a, b) => b.deliveries - a.deliveries);
102
+ // Deterministic: deliveries DESC, rider id ASC (a tie must never depend on key order).
103
+ riders.sort((a, b) => b.deliveries - a.deliveries || (a.rider_id < b.rider_id ? -1 : a.rider_id > b.rider_id ? 1 : 0));
104
+ // DEMAND heat: every delivery ORDER (off-app included), bucketed by the JOINED
105
+ // ORDER's local hour. It is deliberately NOT the delivery-record count - the map must
106
+ // show where delivery demand IS, not only where the rider app was used.
99
107
  const hotAreas = [];
100
108
  for (const [city, row] of Object.entries(total.areas ?? {})) {
101
109
  for (const [hour, count] of Object.entries(row.by_hour ?? {})) {
102
110
  const numeric = Number(count) || 0;
103
111
  if (numeric === 0)
104
112
  continue;
105
- hotAreas.push({ city, hour: Number(hour) || 0, deliveries: numeric });
113
+ hotAreas.push({ city, hour: Number(hour) || 0, orders: numeric, deliveries: numeric });
106
114
  }
107
115
  }
108
- hotAreas.sort((a, b) => b.deliveries - a.deliveries);
116
+ hotAreas.sort((a, b) => b.orders - a.orders || (a.city < b.city ? -1 : a.city > b.city ? 1 : 0) || a.hour - b.hour);
109
117
  const totalDistance = Number(distance.sum_meters) || 0;
110
118
  const distanceCount = Number(distance.count) || 0;
111
119
  return {
@@ -124,14 +132,26 @@ function buildPageForTenant(tenantIds, docs, filters) {
124
132
  with_dropoff_proof: Number(adoption.proof_dropoff_count) || 0,
125
133
  },
126
134
  summary: {
135
+ // The POPULATIONS, side by side and never conflated.
136
+ orders: Number(adoption.delivery_order_count) || 0,
137
+ app_orders: Number(adoption.delivered_via_app_count) || 0,
138
+ off_app_orders: Number(adoption.off_app_count) || 0,
139
+ delivery_records: Number(deliveries.count) || 0,
127
140
  deliveries: Number(deliveries.count) || 0,
128
141
  completed: completedForTiming,
129
142
  cancelled: Number(deliveries.cancelled_count) || 0,
130
- in_progress: Number(deliveries.in_progress_count) || 0,
143
+ // "Open" = PENDING + ASSIGNED + IN_PROGRESS (one definition shared with the
144
+ // statement view and the volume chart's Open bucket). The status-specific counters
145
+ // remain available on the counter block.
146
+ in_progress: (Number(deliveries.pending_count) || 0) +
147
+ (Number(deliveries.assigned_count) || 0) +
148
+ (Number(deliveries.in_progress_count) || 0),
131
149
  rider_revenue: toDecimal(money.rider_revenue_amount),
150
+ rider_payout: toDecimal(money.rider_revenue_amount),
132
151
  net_sale: toDecimal(money.net_sale_amount),
133
152
  collected: toDecimal(money.collected_amount),
134
153
  charges_levied: toDecimal(money.delivery_charge_amount),
154
+ delivery_fees: toDecimal(money.delivery_charge_amount),
135
155
  tips: toDecimal(money.tip_amount),
136
156
  discounts: toDecimal(money.discount_amount),
137
157
  refunds: toDecimal(money.refund_amount),
@@ -139,9 +159,9 @@ function buildPageForTenant(tenantIds, docs, filters) {
139
159
  total_distance_km: km(totalDistance),
140
160
  average_distance_km: safeAverage(km(totalDistance), distanceCount),
141
161
  average_rider_revenue: safeAverage(toDecimal(money.rider_revenue_amount), Number(money.rider_revenue_count) || 0),
142
- average_dispatch_lag_minutes: safeAverage(Number(timing?.dispatch_lag_sum_minutes) || 0, Number(timing?.graded_count) || 0),
143
- average_complete_minutes: safeAverage(Number(timing?.complete_sum_minutes) || 0, Number(timing?.graded_count) || 0),
144
- average_total_minutes: safeAverage(Number(timing?.total_sum_minutes) || 0, Number(timing?.graded_count) || 0),
162
+ average_dispatch_lag_minutes: safeAverage(Number(timing?.dispatch_lag_sum_minutes) || 0, Number(timing?.dispatch_lag_count ?? timing?.graded_count) || 0),
163
+ average_complete_minutes: safeAverage(Number(timing?.complete_sum_minutes) || 0, Number(timing?.complete_count ?? completedForTiming) || 0),
164
+ average_total_minutes: safeAverage(Number(timing?.total_sum_minutes) || 0, Number(timing?.total_count ?? completedForTiming) || 0),
145
165
  average_assignment_minutes: safeAverage(Number(timing?.assignment_sum_minutes) || 0, Number(timing?.assignment_count) || 0),
146
166
  average_pickup_wait_minutes: safeAverage(Number(timing?.pickup_wait_sum_minutes) || 0, Number(timing?.pickup_wait_count) || 0),
147
167
  average_transit_minutes: safeAverage(Number(timing?.transit_sum_minutes) || 0, Number(timing?.transit_count) || 0),
@@ -149,6 +169,9 @@ function buildPageForTenant(tenantIds, docs, filters) {
149
169
  average_status_updates: safeAverage(Number(timing?.status_updates_sum) || 0, Number(timing?.status_updates_count) || 0),
150
170
  cancelled_after_pickup: Number(timing?.cancelled_after_pickup_count) || 0,
151
171
  promise_known: Number(timing?.promise_known_count) || 0,
172
+ eta_coverage_percent: completedForTiming > 0
173
+ ? Math.round(((Number(timing?.promise_known_count) || 0) / completedForTiming) * 1000) / 10
174
+ : null,
152
175
  on_time: Number(timing?.on_time_count) || 0,
153
176
  on_time_percent: Number(timing?.promise_known_count) > 0
154
177
  ? Math.round(((Number(timing?.on_time_count) || 0) / Number(timing?.promise_known_count)) * 1000) / 10
@@ -166,18 +189,45 @@ function buildPageForTenant(tenantIds, docs, filters) {
166
189
  rider_revenue: toDecimal(block.money?.rider_revenue_amount),
167
190
  avg_distance_km: safeAverage(km(Number(block.distance.sum_meters) || 0), Number(block.distance.count) || 0),
168
191
  }))
169
- .sort((a, b) => b.deliveries - a.deliveries),
192
+ .sort((a, b) => b.deliveries - a.deliveries || (a.platform < b.platform ? -1 : a.platform > b.platform ? 1 : 0)),
170
193
  by_area: [...byCity.entries()]
171
- .map(([city, block]) => ({
172
- city,
173
- deliveries: Number(block.deliveries?.count) || 0,
174
- completed: Number(block.deliveries?.completed_count) || 0,
175
- net_sale: toDecimal(block.money?.net_sale_amount),
176
- charges_levied: toDecimal(block.money?.delivery_charge_amount),
177
- rider_revenue: toDecimal(block.money?.rider_revenue_amount),
178
- avg_distance_km: safeAverage(km(Number(block.distance.sum_meters) || 0), Number(block.distance.count) || 0),
179
- }))
180
- .sort((a, b) => b.deliveries - a.deliveries),
194
+ .map(([city, block]) => {
195
+ const rows = Object.values(block.areas ?? {});
196
+ const deliveryOrders = rows.reduce((sum, row) => sum + (Number(row?.delivery_orders) || 0), 0);
197
+ const appOrders = rows.reduce((sum, row) => sum + (Number(row?.app_orders) || 0), 0);
198
+ const offAppOrders = rows.reduce((sum, row) => sum + (Number(row?.off_app_orders) || 0), 0);
199
+ const deliveryRecords = rows.reduce((sum, row) => sum + (Number(row?.delivery_records ?? row?.count) || 0), 0);
200
+ const completed = rows.reduce((sum, row) => sum + (Number(row?.completed_count) || 0), 0);
201
+ const cancelled = rows.reduce((sum, row) => sum + (Number(row?.cancelled_count) || 0), 0);
202
+ const riderPayout = rows.reduce((sum, row) => sum + (Number(row?.rider_revenue_amount) || 0), 0);
203
+ const orderNetSale = rows.reduce((sum, row) => sum + (Number(row?.net_sale_amount) || 0), 0);
204
+ const orderFees = rows.reduce((sum, row) => sum + (Number(row?.delivery_charge_amount) || 0), 0);
205
+ const distanceMeters = rows.reduce((sum, row) => sum + (Number(row?.distance_sum_meters) || 0), 0);
206
+ // Fallback for documents written before area rows carried the order side.
207
+ const netSale = deliveryOrders > 0 ? orderNetSale : Number(block.money?.net_sale_amount) || 0;
208
+ const fees = deliveryOrders > 0 ? orderFees : Number(block.money?.delivery_charge_amount) || 0;
209
+ const payout = rows.length > 0 ? riderPayout : Number(block.money?.rider_revenue_amount) || 0;
210
+ return {
211
+ city,
212
+ delivery_orders: deliveryOrders,
213
+ app_orders: appOrders,
214
+ off_app_orders: offAppOrders,
215
+ delivery_records: deliveryRecords,
216
+ app_coverage_percent: deliveryOrders > 0 ? Math.round((appOrders / deliveryOrders) * 1000) / 10 : null,
217
+ deliveries: deliveryRecords,
218
+ completed,
219
+ cancelled,
220
+ net_sale: toDecimal(netSale),
221
+ delivery_fees: toDecimal(fees),
222
+ charges_levied: toDecimal(fees),
223
+ rider_payout: toDecimal(payout),
224
+ rider_revenue: toDecimal(payout),
225
+ avg_distance_km: safeAverage(km(distanceMeters), deliveryRecords),
226
+ };
227
+ })
228
+ .sort((a, b) => b.delivery_orders - a.delivery_orders ||
229
+ b.deliveries - a.deliveries ||
230
+ (a.city < b.city ? -1 : a.city > b.city ? 1 : 0)),
181
231
  by_rider: riders,
182
232
  distance_buckets: MATERIALIZED_DELIVERY_DISTANCE_BUCKETS.map((bucket) => ({
183
233
  label: bucket.key,
@@ -45,3 +45,42 @@ export function getRewardSelectionQuantity({ offer, stats, isVoucherLinked = fal
45
45
  }
46
46
  return Math.max(1, rewardNumOfItems ?? 1);
47
47
  }
48
+ /**
49
+ * Units of `offerId`'s item reward already claimed on this cart.
50
+ *
51
+ * A claimed unit is a cart line stamped with the offer id in
52
+ * `item_discount_details` - `loyalty_discount_id`, or `voucher_discount_id`
53
+ * for a voucher-pathway claim. Pure: callers pass the categories in.
54
+ */
55
+ export function getClaimedRewardQuantity({ categories, offerId }) {
56
+ let totalQuantity = 0;
57
+ for (let c = 0; c < (categories?.length ?? 0); c++) {
58
+ const items = categories?.[c]?.items ?? [];
59
+ for (let i = 0; i < items.length; i++) {
60
+ const discountDetails = items[i].item_discount_details;
61
+ if (discountDetails == null)
62
+ continue;
63
+ if (discountDetails.loyalty_discount_id !== offerId && discountDetails.voucher_discount_id !== offerId) {
64
+ continue;
65
+ }
66
+ const quantity = Number(items[i].quantity ?? 0);
67
+ if (Number.isFinite(quantity) && quantity > 0) {
68
+ totalQuantity += quantity;
69
+ }
70
+ }
71
+ }
72
+ return totalQuantity;
73
+ }
74
+ /**
75
+ * Units still claimable for `offerId` on this cart.
76
+ *
77
+ * `remaining = allowance - already claimed`, floored at 0. Passing one claim's
78
+ * `num_of_items` as the allowance is what capped repeatable rewards at a single
79
+ * claim; the caller must pass the order's total (the offer stats'
80
+ * `applicable_quantity`), or `num_of_items` only when the claim is one claim's
81
+ * worth (a voucher code).
82
+ */
83
+ export function getRemainingRewardQuantity({ categories, offerId, allowance }) {
84
+ const claimed = getClaimedRewardQuantity({ categories, offerId });
85
+ return Math.max(0, allowance - claimed);
86
+ }
@@ -27,24 +27,26 @@ export * from './item_transactions';
27
27
  export * from './items';
28
28
  export * from './marketing_fingerprints';
29
29
  export * from './materialized_credit_bills';
30
- export * from './materialized_tenant_discount_entries';
31
- export * from './materialized_tenant_discount_reports';
32
- export * from './materialized_tenant_discount_sources';
30
+ export * from './materialized_report_drilldown_rows';
31
+ export * from './materialized_rider_daily_reports';
33
32
  export * from './materialized_tenant_cash_entries';
33
+ export * from './materialized_tenant_cash_reports';
34
34
  export * from './materialized_tenant_delivery_entries';
35
+ export * from './materialized_tenant_delivery_geo_cells';
36
+ export * from './materialized_tenant_delivery_geo_scopes';
35
37
  export * from './materialized_tenant_delivery_reports';
36
- export * from './materialized_rider_daily_reports';
37
- export * from './materialized_tenant_cash_reports';
38
+ export * from './materialized_tenant_discount_entries';
39
+ export * from './materialized_tenant_discount_reports';
40
+ export * from './materialized_tenant_discount_sources';
41
+ export * from './materialized_tenant_hourly_comparison_entries';
42
+ export * from './materialized_tenant_hourly_comparison_reports';
43
+ export * from './materialized_tenant_payments_comparison_entries';
44
+ export * from './materialized_tenant_payments_comparison_reports';
38
45
  export * from './materialized_tenant_prep_time_entries';
39
46
  export * from './materialized_tenant_prep_time_reports';
40
47
  export * from './materialized_tenant_reports_iterations';
41
- export * from './materialized_report_drilldown_rows';
42
48
  export * from './materialized_tenant_sales_comparison_entries';
43
49
  export * from './materialized_tenant_sales_comparison_reports';
44
- export * from './materialized_tenant_hourly_comparison_entries';
45
- export * from './materialized_tenant_hourly_comparison_reports';
46
- export * from './materialized_tenant_payments_comparison_entries';
47
- export * from './materialized_tenant_payments_comparison_reports';
48
50
  export * from './materialized_tenant_sales_overview_reports';
49
51
  export * from './menus';
50
52
  export * from './messaging_devices';
@@ -1,19 +1,32 @@
1
1
  import { Schema } from 'mongoose';
2
2
  import { ALL_DAY_INDEX } from '../../constants/ENUMS';
3
- import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED_DELIVERY_REPORT_SCOPES, } from '../../constants/MATERIALIZED_REPORTS';
3
+ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED_DELIVERY_ENTRY_SCOPES, } from '../../constants/MATERIALIZED_REPORTS';
4
4
  /**
5
5
  * Mongoose schema for `materialized_tenant_delivery_entries` (M4).
6
6
  *
7
- * `delivery_entries` is `Mixed` on purpose: it is a key-addressed map of
8
- * bounded sub-documents (rider / area leaderboards with an hour heat map), which Mongoose
9
- * cannot type precisely without a fixed key set - the keys ARE the data.
7
+ * PAGE-PARTITIONED by source day, exactly like the discounts entries: the day scope uses
8
+ * `page='all'`, and every period entry scope (week / ISO week / month) uses
9
+ * `page=<source localDate>`, so a document is bounded by ONE day's rows. Quarter /
10
+ * semester / year entry documents do not exist.
11
+ *
12
+ * `delivery_entries` is `Mixed` on purpose: it is a key-addressed map of rows whose keys
13
+ * are the report's `ORDER_STATUS:PLATFORM:CITY` grammar, which Mongoose cannot type precisely without
14
+ * a fixed key set - the keys ARE the data.
15
+ */
16
+ /**
17
+ * v3 - PAGE-PARTITIONED entry documents (one page per source day, max scope
18
+ * `localMonth`). v2 was one document per period scope, which made a month an unbounded
19
+ * document. Historical v2 documents are not readable by the page-aware read layer and
20
+ * must be re-materialized (re-close the days); the writer deletes the pages it owns.
10
21
  */
11
- export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_SCHEMA_VERSION = 1;
22
+ export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_SCHEMA_VERSION = 3;
12
23
  export const MaterializedTenantDeliveryEntriesSchema = new Schema({
13
24
  tenant_id: { type: String, required: true },
14
25
  brand_id: { type: String, required: true },
15
- scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_REPORT_SCOPES },
26
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_ENTRY_SCOPES },
16
27
  scope_field: { type: String, required: true },
28
+ /** `'all'` for the day scope; the source `YYYY-MM-DD` for a period scope. */
29
+ page: { type: String, required: true, immutable: true },
17
30
  day_index: { type: String, default: null, enum: [...ALL_DAY_INDEX, null] },
18
31
  sale_type_key_filters: {
19
32
  type: [String],
@@ -42,22 +55,30 @@ export const MaterializedTenantDeliveryEntriesSchema = new Schema({
42
55
  }, { timestamps: true, versionKey: false, minimize: false });
43
56
  export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_NAME = 'materialized_tenant_delivery_entries';
44
57
  /**
45
- * The single UNIQUE compound identity index, like every materialized collection. No
46
- * `brand_id` index - a brand's scopes are resolved before the read.
58
+ * ONE unique index per PAGE: `tenant_id + scope_context + scope_field + page`.
59
+ *
60
+ * The OLD index `{ tenant_id, scope_context, scope_field, day_index }` must NOT survive:
61
+ * period pages all carry `day_index: null`, so it would reject the second page of a
62
+ * month. The OWNER deploy step
63
+ * (`simulations/migrate-delivery-report-indexes.ts --apply`) drops the legacy index by
64
+ * name/key before creating this one. No service calls `ensureMaterializedReportIndexes`
65
+ * automatically; the discounts entry collection has the same migration posture.
66
+ *
67
+ * The same key also serves the multi-page read (tenant + scope prefix, then the pages).
47
68
  */
48
69
  export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_COLLECTION_INDEXES = {
49
70
  _id: { _id: 1 },
50
- tenant_id__scope_context__scope_field__day_index: {
71
+ tenant_id__scope_context__scope_field__page: {
51
72
  tenant_id: 1,
52
73
  scope_context: 1,
53
74
  scope_field: 1,
54
- day_index: 1,
75
+ page: 1,
55
76
  },
56
77
  };
57
78
  export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_INDEX_OPTIONS = [
58
79
  {
59
- key: { tenant_id: 1, scope_context: 1, scope_field: 1, day_index: 1 },
60
- name: 'tenant_id__scope_context__scope_field__day_index',
80
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, page: 1 },
81
+ name: 'tenant_id__scope_context__scope_field__page',
61
82
  unique: true,
62
83
  },
63
84
  ];
@@ -0,0 +1,83 @@
1
+ import { Schema } from 'mongoose';
2
+ import { MATERIALIZED_DELIVERY_GEO_SCOPES, MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION, } from '../../constants/MATERIALIZED_REPORTS';
3
+ /**
4
+ * Mongoose schema for `materialized_tenant_delivery_geo_cells`.
5
+ *
6
+ * `location` is `Mixed` and DELIBERATELY has no default: the unknown bucket must be
7
+ * written WITHOUT the field, because a 2dsphere index cannot extract a geo key from
8
+ * `null`. A missing field is simply not indexed, which is exactly the intent - the
9
+ * unknown aggregate must never be plottable.
10
+ *
11
+ * `city` is nullable: an order whose joined `delivery_details` has no city still
12
+ * counts in the cell (the position is what the heat map plots), it just carries no
13
+ * label.
14
+ */
15
+ export const MaterializedTenantDeliveryGeoCellSchema = new Schema({
16
+ tenant_id: { type: String, required: true },
17
+ brand_id: { type: String, required: true },
18
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_GEO_SCOPES },
19
+ scope_field: { type: String, required: true },
20
+ city: { type: String, default: null },
21
+ h3_cell: { type: String, required: true },
22
+ resolution: { type: Number, required: true, min: 0, max: 15 },
23
+ location: { type: Schema.Types.Mixed, required: false },
24
+ /** Bounded ORDER_STATUS:PLATFORM:CITY counters; sum equals the top-level counters. */
25
+ by_key: { type: Schema.Types.Mixed, required: false, default: null },
26
+ // ---- counters (integer counts; money in CENTS) ----
27
+ orders: { type: Number, required: true, min: 0, default: 0 },
28
+ app_orders: { type: Number, required: true, min: 0, default: 0 },
29
+ delivery_records: { type: Number, required: true, min: 0, default: 0 },
30
+ completed: { type: Number, required: true, min: 0, default: 0 },
31
+ cancelled: { type: Number, required: true, min: 0, default: 0 },
32
+ net_sale_amount: { type: Number, required: true, default: 0 },
33
+ delivery_charge_amount: { type: Number, required: true, default: 0 },
34
+ rider_revenue_amount: { type: Number, required: true, default: 0 },
35
+ schema_version: {
36
+ type: Number,
37
+ required: true,
38
+ immutable: true,
39
+ default: MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_SCHEMA_VERSION,
40
+ },
41
+ computed_at: { type: Schema.Types.Date, required: true },
42
+ createdAt: { type: Schema.Types.Date, required: true, default: () => new Date(), immutable: true },
43
+ updatedAt: { type: Schema.Types.Date, required: true, default: () => new Date() },
44
+ }, { timestamps: true, versionKey: false });
45
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_NAME = 'materialized_tenant_delivery_geo_cells';
46
+ /**
47
+ * The indexes the heat reads/writes assume:
48
+ * 1. the UNIQUE cell identity (one document per tenant/scope/cell);
49
+ * 2. the map's read path - a scope, busiest cells first;
50
+ * 3. the 2dsphere index a future viewport `$geoWithin` read needs.
51
+ *
52
+ * The unknown bucket has no `location`, so it is absent from (3) by design.
53
+ */
54
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_COLLECTION_INDEXES = {
55
+ _id: { _id: 1 },
56
+ tenant_id__scope_context__scope_field__h3_cell: {
57
+ tenant_id: 1,
58
+ scope_context: 1,
59
+ scope_field: 1,
60
+ h3_cell: 1,
61
+ },
62
+ scope_context__scope_field__orders: {
63
+ scope_context: 1,
64
+ scope_field: 1,
65
+ orders: -1,
66
+ },
67
+ location__2dsphere: { location: '2dsphere' },
68
+ };
69
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_CELLS_INDEX_OPTIONS = [
70
+ {
71
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, h3_cell: 1 },
72
+ name: 'tenant_id__scope_context__scope_field__h3_cell',
73
+ unique: true,
74
+ },
75
+ {
76
+ key: { scope_context: 1, scope_field: 1, orders: -1 },
77
+ name: 'scope_context__scope_field__orders',
78
+ },
79
+ {
80
+ key: { location: '2dsphere' },
81
+ name: 'location__2dsphere',
82
+ },
83
+ ];
@@ -0,0 +1,35 @@
1
+ import { Schema } from 'mongoose';
2
+ import { MATERIALIZED_DELIVERY_GEO_SCOPES, MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION, } from '../../constants/MATERIALIZED_REPORTS';
3
+ /** Per-scope cap metadata; never one document per cell. */
4
+ export const MaterializedTenantDeliveryGeoScopeSchema = new Schema({
5
+ tenant_id: { type: String, required: true },
6
+ brand_id: { type: String, required: true },
7
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DELIVERY_GEO_SCOPES },
8
+ scope_field: { type: String, required: true },
9
+ capped_cell_count: { type: Number, required: true, min: 0, default: 0 },
10
+ capped_order_count: { type: Number, required: true, min: 0, default: 0 },
11
+ schema_version: {
12
+ type: Number,
13
+ required: true,
14
+ immutable: true,
15
+ default: MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_SCHEMA_VERSION,
16
+ },
17
+ computed_at: { type: Schema.Types.Date, required: true },
18
+ createdAt: { type: Schema.Types.Date, required: true, default: () => new Date(), immutable: true },
19
+ updatedAt: { type: Schema.Types.Date, required: true, default: () => new Date() },
20
+ }, { timestamps: true, versionKey: false });
21
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_COLLECTION_INDEXES = {
22
+ _id: { _id: 1 },
23
+ tenant_id__scope_context__scope_field: {
24
+ tenant_id: 1,
25
+ scope_context: 1,
26
+ scope_field: 1,
27
+ },
28
+ };
29
+ export const MATERIALIZED_TENANT_DELIVERY_GEO_SCOPES_INDEX_OPTIONS = [
30
+ {
31
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1 },
32
+ name: 'tenant_id__scope_context__scope_field',
33
+ unique: true,
34
+ },
35
+ ];
@@ -8,7 +8,16 @@ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED
8
8
  * bounded sub-documents (rider / area leaderboards with an hour heat map), which Mongoose
9
9
  * cannot type precisely without a fixed key set - the keys ARE the data.
10
10
  */
11
- export const MATERIALIZED_TENANT_DELIVERY_REPORTS_SCHEMA_VERSION = 1;
11
+ /**
12
+ * v2 - the production day-close writer.
13
+ *
14
+ * v1 was the pre-production shape. v2 splits the AREA row into the ORDER-side
15
+ * (`delivery_orders`, net sale, fees) and the APP-side (`delivery_records`, payout)
16
+ * populations, keys the demand heat on the joined ORDER's `localHour`, and fixes the
17
+ * refund source to the payment rows. A v1 document is still readable: the formatter
18
+ * falls back to the old `count` field for the record total.
19
+ */
20
+ export const MATERIALIZED_TENANT_DELIVERY_REPORTS_SCHEMA_VERSION = 2;
12
21
  export const MaterializedTenantDeliveryReportSchema = new Schema({
13
22
  tenant_id: { type: String, required: true },
14
23
  brand_id: { type: String, required: true },
@@ -31,17 +31,26 @@ export * from './item_transactions';
31
31
  export * from './items';
32
32
  export * from './marketing_fingerprints';
33
33
  export * from './materialized_credit_bills';
34
- export * from './materialized_tenant_discount_entries';
35
- export * from './materialized_tenant_discount_reports';
36
- export * from './materialized_tenant_discount_sources';
34
+ export * from './materialized_report_drilldown_rows';
35
+ export * from './materialized_rider_daily_reports';
37
36
  export * from './materialized_tenant_cash_entries';
37
+ export * from './materialized_tenant_cash_reports';
38
38
  export * from './materialized_tenant_delivery_entries';
39
+ export * from './materialized_tenant_delivery_geo_cells';
40
+ export * from './materialized_tenant_delivery_geo_scopes';
39
41
  export * from './materialized_tenant_delivery_reports';
40
- export * from './materialized_rider_daily_reports';
41
- export * from './materialized_tenant_cash_reports';
42
+ export * from './materialized_tenant_discount_entries';
43
+ export * from './materialized_tenant_discount_reports';
44
+ export * from './materialized_tenant_discount_sources';
45
+ export * from './materialized_tenant_hourly_comparison_entries';
46
+ export * from './materialized_tenant_hourly_comparison_reports';
47
+ export * from './materialized_tenant_payments_comparison_entries';
48
+ export * from './materialized_tenant_payments_comparison_reports';
42
49
  export * from './materialized_tenant_prep_time_entries';
43
50
  export * from './materialized_tenant_prep_time_reports';
44
51
  export * from './materialized_tenant_reports_iterations';
52
+ export * from './materialized_tenant_sales_comparison_entries';
53
+ export * from './materialized_tenant_sales_comparison_reports';
45
54
  export * from './materialized_tenant_sales_overview_reports';
46
55
  export * from './menus';
47
56
  export * from './messaging_devices';
@@ -124,10 +133,3 @@ export * from './warehouse_vendors';
124
133
  export * from './warehouse_void_purchase_order_items';
125
134
  export * from './warehouse_void_sale_order_items';
126
135
  export * from './warehouses';
127
- export * from './materialized_tenant_sales_comparison_reports';
128
- export * from './materialized_tenant_sales_comparison_entries';
129
- export * from './materialized_tenant_hourly_comparison_reports';
130
- export * from './materialized_tenant_hourly_comparison_entries';
131
- export * from './materialized_tenant_payments_comparison_reports';
132
- export * from './materialized_tenant_payments_comparison_entries';
133
- export * from './materialized_report_drilldown_rows';