@managesome/eposmatic-toolkit 0.4.44 → 0.4.46

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 (23) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +19 -9
  2. package/esm/helpers/materialized-reports/materialized-prep-time-classification-helpers.js +122 -31
  3. package/esm/helpers/materialized-reports/materialized-prep-time-compile-helpers.js +9 -7
  4. package/esm/helpers/materialized-reports/tenant-prep-time-formatter.js +5 -7
  5. package/esm/schemas/models/materialized_tenant_prep_time_entries.js +1 -1
  6. package/lib/constants/MATERIALIZED_REPORTS.d.ts +19 -9
  7. package/lib/constants/MATERIALIZED_REPORTS.js +19 -9
  8. package/lib/helpers/materialized-reports/materialized-prep-time-classification-helpers.d.ts +36 -3
  9. package/lib/helpers/materialized-reports/materialized-prep-time-classification-helpers.js +122 -31
  10. package/lib/helpers/materialized-reports/materialized-prep-time-compile-helpers.d.ts +9 -3
  11. package/lib/helpers/materialized-reports/materialized-prep-time-compile-helpers.js +9 -7
  12. package/lib/helpers/materialized-reports/tenant-prep-time-formatter.d.ts +1 -1
  13. package/lib/helpers/materialized-reports/tenant-prep-time-formatter.js +5 -7
  14. package/lib/schemas/models/materialized_tenant_prep_time_entries.js +1 -1
  15. package/lib/schemas/types/materialized_tenant_prep_time_entries.d.ts +4 -1
  16. package/lib/schemas/types/materialized_tenant_prep_time_reports.d.ts +9 -7
  17. package/lib/tests/materialized-reports/materialized-prep-time-classification.test.js +178 -23
  18. package/lib/tests/materialized-reports/materialized-prep-time-close-day.test.js +1 -2
  19. package/lib/tests/materialized-reports/materialized-prep-time-compile.test.js +35 -5
  20. package/lib/tests/materialized-reports/materialized-prep-time-constants.test.js +2 -1
  21. package/lib/tests/materialized-reports/materialized-prep-time-plan.test.js +1 -2
  22. package/lib/tests/materialized-reports/tenant-prep-time-formatter.test.js +2 -5
  23. package/package.json +1 -1
@@ -518,19 +518,29 @@ export const MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA = 0;
518
518
  /**
519
519
  * WHERE an item's on-time target came from (decision e2).
520
520
  *
521
- * Promise-only grading would leave 63-97% of items ungraded (measured: only
522
- * 2.7% / 36.2% of orders carry an explicit estimate), so an item with no promise
523
- * is graded against the TENANT DEFAULT - the documented
524
- * `getDeliveryExpectedTime` fallback chain. The baseline is labelled per row so
525
- * a reader can always tell the two apart.
521
+ * The M2 target hierarchy is anchored to the PUNCH instant (`order.createdAt`):
522
+ *
523
+ * DINE-IN: dinein_details.prep_minutes (MINUTES; 0 = immediate)
524
+ * -> tenant.default_prep_minutes (MINUTES; > 0)
525
+ * -> tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0)
526
+ * -> NONE
527
+ * OTHER: tenant.default_prep_minutes (MINUTES; > 0)
528
+ * -> tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0)
529
+ * -> NONE
530
+ *
531
+ * Explicit `estimated_takeaway_time` / `estimated_delivery_time` are NOT part
532
+ * of this hierarchy. There is no legacy target source; all materialized data is
533
+ * new and pre-launch. The source is labelled per row.
526
534
  */
527
535
  export var MATERIALIZED_PREP_TIME_TARGET_ENUM;
528
536
  (function (MATERIALIZED_PREP_TIME_TARGET_ENUM) {
529
- /** The order carried an explicit estimate. */
530
- MATERIALIZED_PREP_TIME_TARGET_ENUM["PROMISE"] = "PROMISE";
531
- /** The order was ASAP and is graded against the tenant default. */
537
+ /** Dine-in target from `dinein_details.prep_minutes` (MINUTES). */
538
+ MATERIALIZED_PREP_TIME_TARGET_ENUM["DINE_IN_PREP"] = "DINE_IN_PREP";
539
+ /** Tenant `default_prep_minutes` (MINUTES), anchored to the punch instant. */
532
540
  MATERIALIZED_PREP_TIME_TARGET_ENUM["TENANT_DEFAULT"] = "TENANT_DEFAULT";
533
- /** Neither exists - the row cannot be graded. */
541
+ /** Tenant `takeaway_time` (MILLISECONDS -> whole minutes), from the punch instant. */
542
+ MATERIALIZED_PREP_TIME_TARGET_ENUM["TAKEAWAY_TIME"] = "TAKEAWAY_TIME";
543
+ /** No source in the hierarchy - the row cannot be graded. */
534
544
  MATERIALIZED_PREP_TIME_TARGET_ENUM["NONE"] = "NONE";
535
545
  })(MATERIALIZED_PREP_TIME_TARGET_ENUM || (MATERIALIZED_PREP_TIME_TARGET_ENUM = {}));
536
546
  export const ALL_MATERIALIZED_PREP_TIME_TARGETS = Object.values(MATERIALIZED_PREP_TIME_TARGET_ENUM);
@@ -18,6 +18,66 @@ const toMinutes = (value) => {
18
18
  }
19
19
  return null;
20
20
  };
21
+ /**
22
+ * Finite numeric value or null. Used by the TARGET resolver, where a source
23
+ * value is a setting/field value (not a stored duration), so it must not be
24
+ * rounded before the arithmetic.
25
+ */
26
+ const toFiniteNumber = (value) => {
27
+ if (typeof value === 'number')
28
+ return Number.isFinite(value) ? value : null;
29
+ if (typeof value === 'string' && value.trim() !== '') {
30
+ const parsed = Number(value);
31
+ return Number.isFinite(parsed) ? parsed : null;
32
+ }
33
+ return null;
34
+ };
35
+ /**
36
+ * A TARGET duration in MINUTES, or null when the value is absent / invalid.
37
+ *
38
+ * prep_minutes and default_prep_minutes are ALREADY minutes, so they are used
39
+ * as-is. A negative / non-finite value is absent and falls through the
40
+ * hierarchy. prep_minutes === 0 is an explicit immediate target (0 minutes),
41
+ * while a tenant default of 0 means "not configured".
42
+ */
43
+ const toTargetMinutes = (value, allowZero) => {
44
+ const minutes = toFiniteNumber(value);
45
+ if (minutes == null || minutes < 0)
46
+ return null;
47
+ if (!allowZero && minutes <= 0)
48
+ return null;
49
+ return minutes;
50
+ };
51
+ /**
52
+ * Tenant takeaway_time is MILLISECONDS. Convert it to WHOLE minutes
53
+ * (Math.round), then use those minutes as the target duration. A value that
54
+ * rounds to 0 is treated as NO target.
55
+ *
56
+ * This conversion is load-bearing: adding the raw milliseconds to createdAt
57
+ * would make a 30-minute setting a 30-SECOND target.
58
+ */
59
+ const toTakeawayMinutes = (value) => {
60
+ const milliseconds = toFiniteNumber(value);
61
+ if (milliseconds == null || milliseconds <= 0)
62
+ return null;
63
+ const minutes = Math.round(milliseconds / 60000);
64
+ return minutes > 0 ? minutes : null;
65
+ };
66
+ /**
67
+ * Dine-in is identified by the order's PLATFORM / ORDER SOURCE, never by the
68
+ * mere presence of dinein_details (a non-dine-in order may still carry the
69
+ * detail block, and a dine-in order may omit prep_minutes). Real values are
70
+ * POS_DINE-IN / WEB_DINE-IN / APP_DINE-IN; the check is deliberately
71
+ * case-insensitive and substring-based so a new source prefix cannot silently
72
+ * lose the dine-in target.
73
+ */
74
+ const isDineInOrder = (order) => {
75
+ for (const source of [order?.platform, order?.order_from]) {
76
+ if (typeof source === 'string' && source.toUpperCase().includes('DINE'))
77
+ return true;
78
+ }
79
+ return false;
80
+ };
21
81
  /**
22
82
  * Histogram bucket label of a duration. Total by construction: the top bucket is
23
83
  * open-ended, so every finite duration lands in exactly one bucket.
@@ -61,8 +121,7 @@ export function freshMaterializedPrepTimeCounters() {
61
121
  order_count: 0,
62
122
  },
63
123
  duration: { min: 0, max: 0, sum: 0, count: 0, instant_count: 0, buckets },
64
- promise: {
65
- promise_set_count: 0,
124
+ target: {
66
125
  default_baseline_count: 0,
67
126
  on_time_count: 0,
68
127
  late_count: 0,
@@ -72,28 +131,62 @@ export function freshMaterializedPrepTimeCounters() {
72
131
  late_items: { count: 0, worst_delta: 0 },
73
132
  };
74
133
  }
75
- /** The on-time target of one order, and where it came from (decision e2). */
76
- export function resolveMaterializedPrepTimeTarget(order, tenantDefaultMinutes) {
77
- // An explicit estimate is an ABSOLUTE timestamp on the order's detail block.
78
- const promised = order?.takeaway_details?.estimated_takeaway_time ?? order?.delivery_details?.estimated_delivery_time ?? null;
79
- if (typeof promised === 'string' && promised.trim() !== '') {
80
- const at = new Date(promised);
81
- if (!Number.isNaN(at.getTime())) {
82
- return { target_at: at, target_source: MATERIALIZED_PREP_TIME_TARGET_ENUM.PROMISE };
134
+ /**
135
+ * The on-time target of one order, and where it came from (decision e2).
136
+ *
137
+ * The target is used ONLY for grading:
138
+ * ready_at = prep_started_at + ready_minutes
139
+ * delta = ready_at - target_at
140
+ *
141
+ * The anchor is the PUNCH instant (order.createdAt), never start_time. Explicit
142
+ * estimated_takeaway_time / estimated_delivery_time are deliberately NOT part of
143
+ * this hierarchy.
144
+ *
145
+ * DINE-IN:
146
+ * 1. dinein_details.prep_minutes (MINUTES; 0 = explicit immediate target)
147
+ * 2. tenant.default_prep_minutes (MINUTES; > 0)
148
+ * 3. tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0 after rounding)
149
+ * 4. NONE
150
+ *
151
+ * NON-DINE-IN:
152
+ * 1. tenant.default_prep_minutes (MINUTES; > 0)
153
+ * 2. tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0 after rounding)
154
+ * 3. NONE
155
+ *
156
+ * Every invalid / non-finite / negative value is absent and falls through.
157
+ */
158
+ export function resolveMaterializedPrepTimeTarget(order, tenantDefaultMinutes, tenantTakeawayTimeMs) {
159
+ const createdMs = order?.createdAt != null ? new Date(order.createdAt).getTime() : NaN;
160
+ if (Number.isNaN(createdMs)) {
161
+ return { target_at: null, target_source: MATERIALIZED_PREP_TIME_TARGET_ENUM.NONE };
162
+ }
163
+ if (isDineInOrder(order)) {
164
+ // prep_minutes is already MINUTES. 0 is a VALID immediate target when the
165
+ // field is present, so only a negative / invalid value falls through.
166
+ const prepMinutes = toTargetMinutes(order.dinein_details?.prep_minutes, true);
167
+ if (prepMinutes != null) {
168
+ return {
169
+ target_at: new Date(createdMs + prepMinutes * 60000),
170
+ target_source: MATERIALIZED_PREP_TIME_TARGET_ENUM.DINE_IN_PREP,
171
+ };
83
172
  }
84
173
  }
85
- // Otherwise the tenant default, measured from the punch instant. Absent in the
86
- // dev fixtures (0 orders carry one), so it arrives from tenant config and is
87
- // usually null - those items are honestly counted as NONE, never graded against
88
- // an invented baseline.
89
- const fallbackMinutes = toMinutes(tenantDefaultMinutes);
90
- const createdMs = order?.createdAt != null ? new Date(order.createdAt).getTime() : NaN;
91
- if (fallbackMinutes != null && fallbackMinutes > 0 && !Number.isNaN(createdMs)) {
174
+ // default_prep_minutes is MINUTES; 0 means "not configured" for targets.
175
+ const defaultMinutes = toTargetMinutes(tenantDefaultMinutes, false);
176
+ if (defaultMinutes != null) {
92
177
  return {
93
- target_at: new Date(createdMs + fallbackMinutes * 60000),
178
+ target_at: new Date(createdMs + defaultMinutes * 60000),
94
179
  target_source: MATERIALIZED_PREP_TIME_TARGET_ENUM.TENANT_DEFAULT,
95
180
  };
96
181
  }
182
+ // takeaway_time is MILLISECONDS and MUST be converted to whole minutes first.
183
+ const takeawayMinutes = toTakeawayMinutes(tenantTakeawayTimeMs);
184
+ if (takeawayMinutes != null) {
185
+ return {
186
+ target_at: new Date(createdMs + takeawayMinutes * 60000),
187
+ target_source: MATERIALIZED_PREP_TIME_TARGET_ENUM.TAKEAWAY_TIME,
188
+ };
189
+ }
97
190
  return { target_at: null, target_source: MATERIALIZED_PREP_TIME_TARGET_ENUM.NONE };
98
191
  }
99
192
  /**
@@ -118,7 +211,7 @@ export const buildMaterializedPrepTimeEntryKey = (itemId, lineId) => {
118
211
  * item counts toward coverage; only MEASURED items reach the duration statistics,
119
212
  * and only MEASURED items with a target are graded on time.
120
213
  */
121
- export function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes = null, }) {
214
+ export function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes = null, tenantTakeawayTimeMs = null, }) {
122
215
  const counters = freshMaterializedPrepTimeCounters();
123
216
  const entries = [];
124
217
  if (order == null)
@@ -132,7 +225,7 @@ export function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes =
132
225
  const staffName = order.staff_details?.name != null ? String(order.staff_details.name) : null;
133
226
  const createdMs = order.createdAt != null ? new Date(order.createdAt).getTime() : NaN;
134
227
  const createdAt = Number.isNaN(createdMs) ? new Date(0) : new Date(createdMs);
135
- const { target_at, target_source } = resolveMaterializedPrepTimeTarget(order, tenantDefaultMinutes);
228
+ const { target_at, target_source } = resolveMaterializedPrepTimeTarget(order, tenantDefaultMinutes, tenantTakeawayTimeMs);
136
229
  let tracked = 0;
137
230
  for (const category of order.categories ?? []) {
138
231
  for (const item of category?.items ?? []) {
@@ -176,12 +269,12 @@ export function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes =
176
269
  }
177
270
  if (target_at != null) {
178
271
  deltaMinutes = Math.round((readyAt.getTime() - target_at.getTime()) / 60000);
179
- counters.promise.delta_sum += deltaMinutes;
272
+ counters.target.delta_sum += deltaMinutes;
180
273
  if (deltaMinutes <= MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA) {
181
- counters.promise.on_time_count += 1;
274
+ counters.target.on_time_count += 1;
182
275
  }
183
276
  else {
184
- counters.promise.late_count += 1;
277
+ counters.target.late_count += 1;
185
278
  counters.late_items.count += 1;
186
279
  if (deltaMinutes > counters.late_items.worst_delta) {
187
280
  counters.late_items.worst_delta = deltaMinutes;
@@ -193,16 +286,13 @@ export function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes =
193
286
  counters.coverage.fallback_anchor_count += 1;
194
287
  }
195
288
  }
289
+ // Every target is DINE_IN_PREP / TENANT_DEFAULT / TAKEAWAY_TIME; a row
290
+ // with no target is NONE.
196
291
  if (target_at != null) {
197
- if (target_source === MATERIALIZED_PREP_TIME_TARGET_ENUM.PROMISE) {
198
- counters.promise.promise_set_count += 1;
199
- }
200
- else {
201
- counters.promise.default_baseline_count += 1;
202
- }
292
+ counters.target.default_baseline_count += 1;
203
293
  }
204
294
  else {
205
- counters.promise.no_target_count += 1;
295
+ counters.target.no_target_count += 1;
206
296
  }
207
297
  // CATALOGUE item id: the grouping identity the Items tab reads. The
208
298
  // order-line id is a DIFFERENT identity and is preserved as line_id, so
@@ -223,7 +313,8 @@ export function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes =
223
313
  ready_at: readyAt,
224
314
  is_ready: isReady,
225
315
  target_at,
226
- target_source: target_at != null ? target_source : null,
316
+ // NONE is the explicit "no target" source; never null on a new row.
317
+ target_source,
227
318
  delta_minutes: deltaMinutes,
228
319
  staff_id: staffId,
229
320
  staff_name: staffName,
@@ -34,13 +34,14 @@ export function mergeMaterializedPrepTimeCounters(target, source) {
34
34
  : Math.min(target.duration.min, source.duration.min);
35
35
  target.duration.max = Math.max(target.duration.max, source.duration.max);
36
36
  }
37
- // ---- promise (all additive; delta_sum is SIGNED) ----
38
- target.promise.promise_set_count += source.promise.promise_set_count;
39
- target.promise.default_baseline_count += source.promise.default_baseline_count;
40
- target.promise.on_time_count += source.promise.on_time_count;
41
- target.promise.late_count += source.promise.late_count;
42
- target.promise.delta_sum += source.promise.delta_sum;
43
- target.promise.no_target_count += source.promise.no_target_count;
37
+ // ---- target / on-time (all additive; delta_sum is SIGNED) ----
38
+ // Target-grading counters; every target is DINE_IN_PREP /
39
+ // TENANT_DEFAULT / TAKEAWAY_TIME.
40
+ target.target.default_baseline_count += source.target.default_baseline_count;
41
+ target.target.on_time_count += source.target.on_time_count;
42
+ target.target.late_count += source.target.late_count;
43
+ target.target.delta_sum += source.target.delta_sum;
44
+ target.target.no_target_count += source.target.no_target_count;
44
45
  // ---- late items ----
45
46
  target.late_items.count += source.late_items.count;
46
47
  target.late_items.worst_delta = Math.max(target.late_items.worst_delta, source.late_items.worst_delta);
@@ -119,6 +120,7 @@ export function compileTenantPrepTimeReports(input) {
119
120
  order,
120
121
  context,
121
122
  tenantDefaultMinutes: input.tenantDefaultMinutes ?? null,
123
+ tenantTakeawayTimeMs: input.tenantTakeawayTimeMs ?? null,
122
124
  });
123
125
  // COVERAGE IS THE HEADLINE, so an order that served items but was never
124
126
  // observed MUST still contribute its denominator. Skipping it would let the
@@ -54,7 +54,6 @@ const emptySummary = () => ({
54
54
  instant_percent: null,
55
55
  on_time_count: 0,
56
56
  late_count: 0,
57
- promise_baseline_count: 0,
58
57
  default_baseline_count: 0,
59
58
  unmeasurable_count: 0,
60
59
  });
@@ -68,7 +67,7 @@ const buildBuckets = (counters) => {
68
67
  const buildSummary = (counters) => {
69
68
  const coverage = counters.coverage;
70
69
  const duration = counters.duration;
71
- const promise = counters.promise;
70
+ const target = counters.target;
72
71
  const buckets = buildBuckets(counters);
73
72
  return {
74
73
  items: coverage.item_count,
@@ -82,11 +81,10 @@ const buildSummary = (counters) => {
82
81
  median_bucket: percentileBucket(buckets, 0.5),
83
82
  p90_bucket: percentileBucket(buckets, 0.9),
84
83
  instant_percent: duration.count > 0 ? toPercent(duration.instant_count, duration.count) : null,
85
- on_time_count: promise.on_time_count,
86
- late_count: promise.late_count,
87
- promise_baseline_count: promise.promise_set_count,
88
- default_baseline_count: promise.default_baseline_count,
89
- unmeasurable_count: promise.no_target_count,
84
+ on_time_count: target.on_time_count,
85
+ late_count: target.late_count,
86
+ default_baseline_count: target.default_baseline_count,
87
+ unmeasurable_count: target.no_target_count,
90
88
  };
91
89
  };
92
90
  const emptyPage = (tenantIds) => {
@@ -37,7 +37,7 @@ const PrepTimeEntrySchema = new Schema({
37
37
  // Reconstructed (= prep_started_at + ready_minutes), MEASURED rows only.
38
38
  ready_at: { type: Schema.Types.Date, default: null },
39
39
  is_ready: { type: Boolean, required: true, default: false },
40
- // ---- promise ----
40
+ // ---- target / on-time grading ----
41
41
  target_at: { type: Schema.Types.Date, default: null },
42
42
  target_source: {
43
43
  type: String,
@@ -417,18 +417,28 @@ export declare const MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA = 0;
417
417
  /**
418
418
  * WHERE an item's on-time target came from (decision e2).
419
419
  *
420
- * Promise-only grading would leave 63-97% of items ungraded (measured: only
421
- * 2.7% / 36.2% of orders carry an explicit estimate), so an item with no promise
422
- * is graded against the TENANT DEFAULT - the documented
423
- * `getDeliveryExpectedTime` fallback chain. The baseline is labelled per row so
424
- * a reader can always tell the two apart.
420
+ * The M2 target hierarchy is anchored to the PUNCH instant (`order.createdAt`):
421
+ *
422
+ * DINE-IN: dinein_details.prep_minutes (MINUTES; 0 = immediate)
423
+ * -> tenant.default_prep_minutes (MINUTES; > 0)
424
+ * -> tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0)
425
+ * -> NONE
426
+ * OTHER: tenant.default_prep_minutes (MINUTES; > 0)
427
+ * -> tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0)
428
+ * -> NONE
429
+ *
430
+ * Explicit `estimated_takeaway_time` / `estimated_delivery_time` are NOT part
431
+ * of this hierarchy. There is no legacy target source; all materialized data is
432
+ * new and pre-launch. The source is labelled per row.
425
433
  */
426
434
  export declare enum MATERIALIZED_PREP_TIME_TARGET_ENUM {
427
- /** The order carried an explicit estimate. */
428
- PROMISE = "PROMISE",
429
- /** The order was ASAP and is graded against the tenant default. */
435
+ /** Dine-in target from `dinein_details.prep_minutes` (MINUTES). */
436
+ DINE_IN_PREP = "DINE_IN_PREP",
437
+ /** Tenant `default_prep_minutes` (MINUTES), anchored to the punch instant. */
430
438
  TENANT_DEFAULT = "TENANT_DEFAULT",
431
- /** Neither exists - the row cannot be graded. */
439
+ /** Tenant `takeaway_time` (MILLISECONDS -> whole minutes), from the punch instant. */
440
+ TAKEAWAY_TIME = "TAKEAWAY_TIME",
441
+ /** No source in the hierarchy - the row cannot be graded. */
432
442
  NONE = "NONE"
433
443
  }
434
444
  export declare const ALL_MATERIALIZED_PREP_TIME_TARGETS: MATERIALIZED_PREP_TIME_TARGET_ENUM[];
@@ -522,19 +522,29 @@ exports.MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA = 0;
522
522
  /**
523
523
  * WHERE an item's on-time target came from (decision e2).
524
524
  *
525
- * Promise-only grading would leave 63-97% of items ungraded (measured: only
526
- * 2.7% / 36.2% of orders carry an explicit estimate), so an item with no promise
527
- * is graded against the TENANT DEFAULT - the documented
528
- * `getDeliveryExpectedTime` fallback chain. The baseline is labelled per row so
529
- * a reader can always tell the two apart.
525
+ * The M2 target hierarchy is anchored to the PUNCH instant (`order.createdAt`):
526
+ *
527
+ * DINE-IN: dinein_details.prep_minutes (MINUTES; 0 = immediate)
528
+ * -> tenant.default_prep_minutes (MINUTES; > 0)
529
+ * -> tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0)
530
+ * -> NONE
531
+ * OTHER: tenant.default_prep_minutes (MINUTES; > 0)
532
+ * -> tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0)
533
+ * -> NONE
534
+ *
535
+ * Explicit `estimated_takeaway_time` / `estimated_delivery_time` are NOT part
536
+ * of this hierarchy. There is no legacy target source; all materialized data is
537
+ * new and pre-launch. The source is labelled per row.
530
538
  */
531
539
  var MATERIALIZED_PREP_TIME_TARGET_ENUM;
532
540
  (function (MATERIALIZED_PREP_TIME_TARGET_ENUM) {
533
- /** The order carried an explicit estimate. */
534
- MATERIALIZED_PREP_TIME_TARGET_ENUM["PROMISE"] = "PROMISE";
535
- /** The order was ASAP and is graded against the tenant default. */
541
+ /** Dine-in target from `dinein_details.prep_minutes` (MINUTES). */
542
+ MATERIALIZED_PREP_TIME_TARGET_ENUM["DINE_IN_PREP"] = "DINE_IN_PREP";
543
+ /** Tenant `default_prep_minutes` (MINUTES), anchored to the punch instant. */
536
544
  MATERIALIZED_PREP_TIME_TARGET_ENUM["TENANT_DEFAULT"] = "TENANT_DEFAULT";
537
- /** Neither exists - the row cannot be graded. */
545
+ /** Tenant `takeaway_time` (MILLISECONDS -> whole minutes), from the punch instant. */
546
+ MATERIALIZED_PREP_TIME_TARGET_ENUM["TAKEAWAY_TIME"] = "TAKEAWAY_TIME";
547
+ /** No source in the hierarchy - the row cannot be graded. */
538
548
  MATERIALIZED_PREP_TIME_TARGET_ENUM["NONE"] = "NONE";
539
549
  })(MATERIALIZED_PREP_TIME_TARGET_ENUM || (exports.MATERIALIZED_PREP_TIME_TARGET_ENUM = MATERIALIZED_PREP_TIME_TARGET_ENUM = {}));
540
550
  exports.ALL_MATERIALIZED_PREP_TIME_TARGETS = Object.values(MATERIALIZED_PREP_TIME_TARGET_ENUM);
@@ -43,12 +43,21 @@ export interface IPrepTimeOrderSource {
43
43
  prep_started_at?: Date | string | null;
44
44
  }[];
45
45
  }[];
46
+ /**
47
+ * Explicit estimates are present on the SOURCE order but are deliberately NOT
48
+ * part of the M2 target hierarchy (they are an order estimate, not the prep-time
49
+ * baseline). Kept in the shape so callers can pass a full order object.
50
+ */
46
51
  delivery_details?: {
47
52
  estimated_delivery_time?: Date | string | null;
48
53
  } | null;
49
54
  takeaway_details?: {
50
55
  estimated_takeaway_time?: Date | string | null;
51
56
  } | null;
57
+ /** Dine-in prep target in MINUTES. */
58
+ dinein_details?: {
59
+ prep_minutes?: number | string | null;
60
+ } | null;
52
61
  }
53
62
  export interface IPrepTimeOrderContext {
54
63
  local_date: string;
@@ -72,8 +81,31 @@ export declare function classifyMaterializedPrepTimeAnchor(item: {
72
81
  }): MATERIALIZED_PREP_TIME_ANCHOR_ENUM;
73
82
  /** A zeroed counter block. */
74
83
  export declare function freshMaterializedPrepTimeCounters(): IMaterializedPrepTimeCounters;
75
- /** The on-time target of one order, and where it came from (decision e2). */
76
- export declare function resolveMaterializedPrepTimeTarget(order: Pick<IPrepTimeOrderSource, 'createdAt' | 'delivery_details' | 'takeaway_details'>, tenantDefaultMinutes?: number | null): {
84
+ /**
85
+ * The on-time target of one order, and where it came from (decision e2).
86
+ *
87
+ * The target is used ONLY for grading:
88
+ * ready_at = prep_started_at + ready_minutes
89
+ * delta = ready_at - target_at
90
+ *
91
+ * The anchor is the PUNCH instant (order.createdAt), never start_time. Explicit
92
+ * estimated_takeaway_time / estimated_delivery_time are deliberately NOT part of
93
+ * this hierarchy.
94
+ *
95
+ * DINE-IN:
96
+ * 1. dinein_details.prep_minutes (MINUTES; 0 = explicit immediate target)
97
+ * 2. tenant.default_prep_minutes (MINUTES; > 0)
98
+ * 3. tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0 after rounding)
99
+ * 4. NONE
100
+ *
101
+ * NON-DINE-IN:
102
+ * 1. tenant.default_prep_minutes (MINUTES; > 0)
103
+ * 2. tenant.takeaway_time (MILLISECONDS -> whole minutes; > 0 after rounding)
104
+ * 3. NONE
105
+ *
106
+ * Every invalid / non-finite / negative value is absent and falls through.
107
+ */
108
+ export declare function resolveMaterializedPrepTimeTarget(order: Pick<IPrepTimeOrderSource, 'createdAt' | 'platform' | 'order_from' | 'dinein_details'>, tenantDefaultMinutes?: number | null, tenantTakeawayTimeMs?: number | null): {
77
109
  target_at: Date | null;
78
110
  target_source: MATERIALIZED_PREP_TIME_TARGET_ENUM;
79
111
  };
@@ -99,8 +131,9 @@ export interface IAccumulateOrderPrepTimeResult {
99
131
  * item counts toward coverage; only MEASURED items reach the duration statistics,
100
132
  * and only MEASURED items with a target are graded on time.
101
133
  */
102
- export declare function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes, }: {
134
+ export declare function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes, tenantTakeawayTimeMs, }: {
103
135
  order: IPrepTimeOrderSource;
104
136
  context: IPrepTimeOrderContext;
105
137
  tenantDefaultMinutes?: number | null;
138
+ tenantTakeawayTimeMs?: number | null;
106
139
  }): IAccumulateOrderPrepTimeResult;