@managesome/eposmatic-toolkit 0.4.32 → 0.4.34

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 (46) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +3 -5
  2. package/esm/constants/enums/offers.js +0 -6
  3. package/esm/helpers/materialized-reports/index.js +1 -0
  4. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +4 -0
  5. package/esm/helpers/materialized-reports/materialized-prep-time-classification-helpers.js +12 -8
  6. package/esm/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +86 -9
  7. package/esm/helpers/materialized-reports/materialized-prep-time-read-helpers.js +613 -0
  8. package/esm/helpers/types/materialized-reports-apis.js +10 -0
  9. package/esm/schemas/models/index.js +0 -1
  10. package/esm/schemas/types/index.js +0 -1
  11. package/lib/constants/MATERIALIZED_REPORTS.d.ts +3 -2
  12. package/lib/constants/MATERIALIZED_REPORTS.js +3 -5
  13. package/lib/constants/enums/offers.d.ts +0 -5
  14. package/lib/constants/enums/offers.js +1 -7
  15. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  16. package/lib/helpers/materialized-reports/index.js +1 -0
  17. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +4 -0
  18. package/lib/helpers/materialized-reports/materialized-prep-time-classification-helpers.js +12 -8
  19. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.d.ts +15 -0
  20. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +86 -8
  21. package/lib/helpers/materialized-reports/materialized-prep-time-read-helpers.d.ts +179 -0
  22. package/lib/helpers/materialized-reports/materialized-prep-time-read-helpers.js +639 -0
  23. package/lib/helpers/types/materialized-reports-apis.d.ts +145 -1
  24. package/lib/helpers/types/materialized-reports-apis.js +11 -0
  25. package/lib/schemas/models/index.d.ts +0 -1
  26. package/lib/schemas/models/index.js +0 -1
  27. package/lib/schemas/models/materialized_tenant_prep_time_entries.d.ts +6 -6
  28. package/lib/schemas/types/index.d.ts +0 -1
  29. package/lib/schemas/types/index.js +0 -1
  30. package/lib/schemas/types/materialized_tenant_prep_time_reports.d.ts +7 -5
  31. package/lib/tests/materialized-reports/materialized-prep-time-classification.test.js +28 -5
  32. package/lib/tests/materialized-reports/materialized-prep-time-close-day.test.js +17 -4
  33. package/lib/tests/materialized-reports/materialized-prep-time-constants.test.js +6 -4
  34. package/lib/tests/materialized-reports/materialized-prep-time-duration-consistency.test.js +135 -0
  35. package/lib/tests/materialized-reports/materialized-prep-time-plan.test.js +71 -3
  36. package/lib/tests/materialized-reports/materialized-prep-time-read-helpers.test.d.ts +1 -0
  37. package/lib/tests/materialized-reports/materialized-prep-time-read-helpers.test.js +620 -0
  38. package/lib/tests/offers-matrix.test.d.ts +1 -0
  39. package/lib/tests/offers-matrix.test.js +401 -0
  40. package/package.json +1 -1
  41. package/esm/schemas/models/rewards_usage.js +0 -61
  42. package/lib/schemas/models/rewards_usage.d.ts +0 -53
  43. package/lib/schemas/models/rewards_usage.js +0 -64
  44. package/lib/schemas/types/rewards_usage.d.ts +0 -13
  45. package/lib/schemas/types/rewards_usage.js +0 -2
  46. /package/{esm/schemas/types/rewards_usage.js → lib/tests/materialized-reports/materialized-prep-time-duration-consistency.test.d.ts} +0 -0
@@ -51,11 +51,6 @@ export declare enum PATHWAY_TO_UNLOCK_TYPE_ENUM {
51
51
  POINTS = "POINTS"
52
52
  }
53
53
  export declare const ALL_PATHWAY_TO_UNLOCK_TYPES: PATHWAY_TO_UNLOCK_TYPE_ENUM[];
54
- export declare enum REWARDS_USAGE_REF_TYPE_ENUM {
55
- VOUCHER = "VOUCHER",
56
- GIFT_CARD = "GIFT_CARD"
57
- }
58
- export declare const ALL_REWARDS_USAGE_REF_TYPES: REWARDS_USAGE_REF_TYPE_ENUM[];
59
54
  export declare enum RATING_TYPE_ENUM {
60
55
  FOOD_QUALITY_RATING = "FOOD_QUALITY_RATING",
61
56
  SERVICE_RATING = "SERVICE_RATING",
@@ -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_DISCOUNT_APPLICABILITY_TYPES = exports.DISCOUNT_APPLICABILITY_ENUM = exports.ALL_DISCOUNT_TYPES = exports.DISCOUNT_TYPE_ENUM = exports.ALL_RATING_TYPES = exports.RATING_TYPE_ENUM = exports.ALL_REWARDS_USAGE_REF_TYPES = exports.REWARDS_USAGE_REF_TYPE_ENUM = exports.ALL_PATHWAY_TO_UNLOCK_TYPES = exports.PATHWAY_TO_UNLOCK_TYPE_ENUM = exports.ALL_MYSTERY_GIFT_POPUP_TYPES = exports.MYSTERY_GIFT_POPUP_TYPE_ENUM = exports.ALL_MYSTERY_GIFT_TYPES = exports.MYSTERY_GIFT_TYPE_ENUM = exports.ALL_GIFT_CARD_REWARD_TYPES = exports.GIFT_CARD_REWARD_TYPE_ENUM = exports.ALL_CUSTOMER_REDEMPTION_TYPES = exports.CUSTOMER_REDEMPTION_TYPE_ENUM = exports.ALL_CUSTOMER_REDEMPTION_SOURCE_TYPES = exports.CUSTOMER_REDEMPTION_SOURCE_ENUM = exports.ALL_OFFER_REWARD_TYPES = exports.OFFER_REWARD_TYPE_ENUM = void 0;
4
+ exports.ALL_DISCOUNT_APPLICABILITY_TYPES = exports.DISCOUNT_APPLICABILITY_ENUM = exports.ALL_DISCOUNT_TYPES = exports.DISCOUNT_TYPE_ENUM = exports.ALL_RATING_TYPES = exports.RATING_TYPE_ENUM = exports.ALL_PATHWAY_TO_UNLOCK_TYPES = exports.PATHWAY_TO_UNLOCK_TYPE_ENUM = exports.ALL_MYSTERY_GIFT_POPUP_TYPES = exports.MYSTERY_GIFT_POPUP_TYPE_ENUM = exports.ALL_MYSTERY_GIFT_TYPES = exports.MYSTERY_GIFT_TYPE_ENUM = exports.ALL_GIFT_CARD_REWARD_TYPES = exports.GIFT_CARD_REWARD_TYPE_ENUM = exports.ALL_CUSTOMER_REDEMPTION_TYPES = exports.CUSTOMER_REDEMPTION_TYPE_ENUM = exports.ALL_CUSTOMER_REDEMPTION_SOURCE_TYPES = exports.CUSTOMER_REDEMPTION_SOURCE_ENUM = exports.ALL_OFFER_REWARD_TYPES = exports.OFFER_REWARD_TYPE_ENUM = void 0;
5
5
  var OFFER_REWARD_TYPE_ENUM;
6
6
  (function (OFFER_REWARD_TYPE_ENUM) {
7
7
  OFFER_REWARD_TYPE_ENUM["DISCOUNT"] = "DISCOUNT";
@@ -68,12 +68,6 @@ var PATHWAY_TO_UNLOCK_TYPE_ENUM;
68
68
  PATHWAY_TO_UNLOCK_TYPE_ENUM["POINTS"] = "POINTS";
69
69
  })(PATHWAY_TO_UNLOCK_TYPE_ENUM || (exports.PATHWAY_TO_UNLOCK_TYPE_ENUM = PATHWAY_TO_UNLOCK_TYPE_ENUM = {}));
70
70
  exports.ALL_PATHWAY_TO_UNLOCK_TYPES = Object.values(PATHWAY_TO_UNLOCK_TYPE_ENUM);
71
- var REWARDS_USAGE_REF_TYPE_ENUM;
72
- (function (REWARDS_USAGE_REF_TYPE_ENUM) {
73
- REWARDS_USAGE_REF_TYPE_ENUM["VOUCHER"] = "VOUCHER";
74
- REWARDS_USAGE_REF_TYPE_ENUM["GIFT_CARD"] = "GIFT_CARD";
75
- })(REWARDS_USAGE_REF_TYPE_ENUM || (exports.REWARDS_USAGE_REF_TYPE_ENUM = REWARDS_USAGE_REF_TYPE_ENUM = {}));
76
- exports.ALL_REWARDS_USAGE_REF_TYPES = Object.values(REWARDS_USAGE_REF_TYPE_ENUM);
77
71
  /* ================><================= */
78
72
  var RATING_TYPE_ENUM;
79
73
  (function (RATING_TYPE_ENUM) {
@@ -26,6 +26,7 @@ export * from './materialized-cash-compile-helpers';
26
26
  export * from './materialized-prep-time-classification-helpers';
27
27
  export * from './materialized-prep-time-close-day-helpers';
28
28
  export * from './materialized-prep-time-compile-helpers';
29
+ export * from './materialized-prep-time-read-helpers';
29
30
  export * from './materialized-report-drilldown-rows';
30
31
  export * from './materialized-reports-read-helpers';
31
32
  export * from './materialized-reports-scope-group-helpers';
@@ -42,6 +42,7 @@ __exportStar(require("./materialized-cash-compile-helpers"), exports);
42
42
  __exportStar(require("./materialized-prep-time-classification-helpers"), exports);
43
43
  __exportStar(require("./materialized-prep-time-close-day-helpers"), exports);
44
44
  __exportStar(require("./materialized-prep-time-compile-helpers"), exports);
45
+ __exportStar(require("./materialized-prep-time-read-helpers"), exports);
45
46
  __exportStar(require("./materialized-report-drilldown-rows"), exports);
46
47
  __exportStar(require("./materialized-reports-read-helpers"), exports);
47
48
  __exportStar(require("./materialized-reports-scope-group-helpers"), exports);
@@ -7,6 +7,8 @@ const materialized_tenant_discount_entries_1 = require("../../schemas/models/mat
7
7
  const materialized_tenant_discount_reports_1 = require("../../schemas/models/materialized_tenant_discount_reports");
8
8
  const materialized_tenant_discount_sources_1 = require("../../schemas/models/materialized_tenant_discount_sources");
9
9
  const materialized_tenant_reports_iterations_1 = require("../../schemas/models/materialized_tenant_reports_iterations");
10
+ const materialized_tenant_prep_time_entries_1 = require("../../schemas/models/materialized_tenant_prep_time_entries");
11
+ const materialized_tenant_prep_time_reports_1 = require("../../schemas/models/materialized_tenant_prep_time_reports");
10
12
  const materialized_tenant_sales_overview_reports_1 = require("../../schemas/models/materialized_tenant_sales_overview_reports");
11
13
  const materialized_report_drilldown_rows_1 = require("../../schemas/models/materialized_report_drilldown_rows");
12
14
  const tenant_calendar_1 = require("../../schemas/models/tenant_calendar");
@@ -29,6 +31,8 @@ const INDEXES = {
29
31
  [materialized_tenant_discount_reports_1.MATERIALIZED_TENANT_DISCOUNT_REPORTS_COLLECTION_NAME]: materialized_tenant_discount_reports_1.MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS,
30
32
  [materialized_tenant_discount_entries_1.MATERIALIZED_TENANT_DISCOUNT_ENTRIES_COLLECTION_NAME]: materialized_tenant_discount_entries_1.MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS,
31
33
  [materialized_tenant_discount_sources_1.MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_NAME]: materialized_tenant_discount_sources_1.MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS,
34
+ [materialized_tenant_prep_time_reports_1.MATERIALIZED_TENANT_PREP_TIME_REPORTS_COLLECTION_NAME]: materialized_tenant_prep_time_reports_1.MATERIALIZED_TENANT_PREP_TIME_REPORTS_INDEX_OPTIONS,
35
+ [materialized_tenant_prep_time_entries_1.MATERIALIZED_TENANT_PREP_TIME_ENTRIES_COLLECTION_NAME]: materialized_tenant_prep_time_entries_1.MATERIALIZED_TENANT_PREP_TIME_ENTRIES_INDEX_OPTIONS,
32
36
  [materialized_tenant_reports_iterations_1.MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME]: materialized_tenant_reports_iterations_1.MATERIALIZED_TENANT_REPORTS_ITERATIONS_INDEX_OPTIONS,
33
37
  [materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME]: materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS,
34
38
  [materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME]: materialized_report_drilldown_rows_1.MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS,
@@ -151,14 +151,18 @@ function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes = null,
151
151
  counters.coverage.own_anchor_count += 1;
152
152
  // RECONSTRUCTED ready instant - the source field ready_at does not exist.
153
153
  readyAt = new Date(prepStartedAt.getTime() + minutes * 60000);
154
- counters.duration.count += 1;
155
- if (minutes === 0)
156
- counters.duration.instant_count += 1;
157
- const bucket = resolveMaterializedPrepTimeBucket(minutes);
158
- counters.duration.buckets[bucket] = (counters.duration.buckets[bucket] ?? 0) + 1;
159
- // Counts above stay complete; only the EXTREMES are guarded, so a single
160
- // clock/backfill artefact cannot define min/max/sum.
161
- if (minutes <= MATERIALIZED_REPORTS_1.MATERIALIZED_PREP_TIME_MAX_MINUTES) {
154
+ // ONE canonical duration population: a duration is VALID only when it
155
+ // is finite, >= 0 and <= the outlier cap. Valid durations alone feed
156
+ // count / sum / min / max / buckets / instant count (and therefore
157
+ // avg = sum/count). An artefact must never understate the average by
158
+ // sitting in the denominator while being excluded from the numerator.
159
+ // Coverage still counts the MEASURED row (own_anchor_count above).
160
+ if (minutes >= 0 && minutes <= MATERIALIZED_REPORTS_1.MATERIALIZED_PREP_TIME_MAX_MINUTES) {
161
+ counters.duration.count += 1;
162
+ if (minutes === 0)
163
+ counters.duration.instant_count += 1;
164
+ const bucket = resolveMaterializedPrepTimeBucket(minutes);
165
+ counters.duration.buckets[bucket] = (counters.duration.buckets[bucket] ?? 0) + 1;
162
166
  counters.duration.sum += minutes;
163
167
  if (counters.duration.count === 1 || minutes < counters.duration.min) {
164
168
  counters.duration.min = minutes;
@@ -70,6 +70,15 @@ export declare function foldMaterializedPrepTimePeriodRows({ periodScopeField, p
70
70
  }>;
71
71
  /** The period scope contexts (everything except the day scope). */
72
72
  export declare const MATERIALIZED_PREP_TIME_PERIOD_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
73
+ /**
74
+ * Every `localDate` label whose DAY entry document can contribute to a period
75
+ * the closing day rolls into (week / ISO week / month).
76
+ *
77
+ * The worker uses this to fetch exactly the sibling day entries the period
78
+ * fold needs — never a full-period entry document and never a year-wide scan.
79
+ * Returns `null` (never throws) for a malformed date.
80
+ */
81
+ export declare function getMaterializedPrepTimePeriodDayScopeFields(localDate: string): string[] | null;
73
82
  /** True when a stored prep counter document equals the incoming one (skip write). */
74
83
  export declare function needsMaterializedPrepTimeReportWrite(existing: IMaterializedTenantPrepTimeReport | null | undefined, incoming: IMaterializedTenantPrepTimeReport | null | undefined): boolean;
75
84
  /** One planned write: the document plus its shared-history iteration row. */
@@ -114,6 +123,12 @@ export interface IBuildTenantPrepTimeCloseDayPlanInput {
114
123
  existing?: IMaterializedTenantPrepTimeReport[];
115
124
  existingEntries?: IMaterializedTenantPrepTimeEntries[];
116
125
  reason: string;
126
+ /**
127
+ * Structural writes even when the watermark says the day is unchanged
128
+ * (manual range repair). The period folds are idempotent, so a forced run
129
+ * rewrites the same values and advances the iteration.
130
+ */
131
+ force?: boolean;
117
132
  computedAt?: Date;
118
133
  }
119
134
  /**
@@ -8,6 +8,7 @@ exports.updateMaterializedPrepTimeEntries = updateMaterializedPrepTimeEntries;
8
8
  exports.needsMaterializedPrepTimeEntriesWrite = needsMaterializedPrepTimeEntriesWrite;
9
9
  exports.foldMaterializedPrepTimePeriodCounters = foldMaterializedPrepTimePeriodCounters;
10
10
  exports.foldMaterializedPrepTimePeriodRows = foldMaterializedPrepTimePeriodRows;
11
+ exports.getMaterializedPrepTimePeriodDayScopeFields = getMaterializedPrepTimePeriodDayScopeFields;
11
12
  exports.needsMaterializedPrepTimeReportWrite = needsMaterializedPrepTimeReportWrite;
12
13
  exports.buildTenantPrepTimeCloseDayPlan = buildTenantPrepTimeCloseDayPlan;
13
14
  const mongoose_1 = __importDefault(require("mongoose"));
@@ -168,6 +169,67 @@ function foldMaterializedPrepTimePeriodRows({ periodScopeField, periodScope, day
168
169
  }
169
170
  /** The period scope contexts (everything except the day scope). */
170
171
  exports.MATERIALIZED_PREP_TIME_PERIOD_SCOPES = MATERIALIZED_REPORTS_1.MATERIALIZED_PREP_TIME_REPORT_SCOPES.filter((scope) => !(0, exports.isMaterializedPrepTimeDayScope)(String(scope)));
172
+ /* ------------------------------------------------------------------------ */
173
+ /* Period sibling-day enumeration */
174
+ /* ------------------------------------------------------------------------ */
175
+ const pad2 = (value) => String(value).padStart(2, '0');
176
+ const toLocalDateKey = (date) => `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(date.getUTCDate())}`;
177
+ const addUtcDays = (date, amount) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount));
178
+ const addMonthDays = (year, month, days) => {
179
+ if (!Number.isInteger(year) || !Number.isInteger(month) || month < 1 || month > 12)
180
+ return false;
181
+ const last = new Date(Date.UTC(year, month, 0)).getUTCDate();
182
+ for (let day = 1; day <= last; day += 1) {
183
+ days.add(`${year}-${pad2(month)}-${pad2(day)}`);
184
+ }
185
+ return true;
186
+ };
187
+ /**
188
+ * Every `localDate` label whose DAY entry document can contribute to a period
189
+ * the closing day rolls into (week / ISO week / month).
190
+ *
191
+ * The worker uses this to fetch exactly the sibling day entries the period
192
+ * fold needs — never a full-period entry document and never a year-wide scan.
193
+ * Returns `null` (never throws) for a malformed date.
194
+ */
195
+ function getMaterializedPrepTimePeriodDayScopeFields(localDate) {
196
+ const periodFields = (0, scope_helpers_1.getMaterializedPeriodScopeFields)(localDate);
197
+ if (periodFields == null)
198
+ return null;
199
+ const days = new Set([localDate]);
200
+ const weekField = periodFields[MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK];
201
+ const weekParts = typeof weekField === 'string' ? (0, scope_helpers_1.parseMaterializedLocalDate)(weekField) : null;
202
+ if (weekParts == null)
203
+ return null;
204
+ const weekStart = new Date(Date.UTC(weekParts.year, weekParts.month - 1, weekParts.day));
205
+ if (weekStart.getUTCDay() !== 0)
206
+ return null;
207
+ for (let offset = 0; offset < 7; offset += 1) {
208
+ days.add(toLocalDateKey(addUtcDays(weekStart, offset)));
209
+ }
210
+ const isoWeekField = periodFields[MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR];
211
+ const isoMatch = typeof isoWeekField === 'string' ? /^(\d{4})-W(\d{2})$/.exec(isoWeekField) : null;
212
+ if (isoMatch == null)
213
+ return null;
214
+ const weekYear = Number(isoMatch[1]);
215
+ const week = Number(isoMatch[2]);
216
+ if (!Number.isInteger(week) || week < 1 || week > 53)
217
+ return null;
218
+ const jan4 = new Date(Date.UTC(weekYear, 0, 4));
219
+ const isoWeekday = jan4.getUTCDay() || 7;
220
+ const weekOneMonday = addUtcDays(jan4, 1 - isoWeekday);
221
+ const isoStart = addUtcDays(weekOneMonday, (week - 1) * 7);
222
+ for (let offset = 0; offset < 7; offset += 1) {
223
+ days.add(toLocalDateKey(addUtcDays(isoStart, offset)));
224
+ }
225
+ const monthField = periodFields[MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH];
226
+ const monthMatch = typeof monthField === 'string' ? /^(\d{4})-(\d{2})$/.exec(monthField) : null;
227
+ if (monthMatch == null)
228
+ return null;
229
+ if (!addMonthDays(Number(monthMatch[1]), Number(monthMatch[2]), days))
230
+ return null;
231
+ return [...days].sort();
232
+ }
171
233
  /** True when a stored prep counter document equals the incoming one (skip write). */
172
234
  function needsMaterializedPrepTimeReportWrite(existing, incoming) {
173
235
  if (existing == null || incoming == null)
@@ -208,6 +270,7 @@ function buildTenantPrepTimeCloseDayPlan(input) {
208
270
  if (reports.some((doc) => doc == null || doc.tenant_id !== tenantId))
209
271
  return null;
210
272
  const computedAt = input.computedAt ?? new Date();
273
+ const force = input.force === true;
211
274
  const existing = input.existing ?? [];
212
275
  const existingEntries = input.existingEntries ?? [];
213
276
  const dateDoc = reports.find((doc) => doc.scope_context === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE) ?? null;
@@ -358,14 +421,14 @@ function buildTenantPrepTimeCloseDayPlan(input) {
358
421
  sale_type_key_filters: existingDoc?.sale_type_key_filters ?? reports[0]?.sale_type_key_filters ?? [],
359
422
  prep_time_counters: counters,
360
423
  prep_time_counter_rows: counterRows,
361
- iteration: existingDoc?.iteration,
424
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
362
425
  schema_version: existingDoc?.schema_version ?? 1,
363
426
  source_watermark: watermark ?? new Date(computedAt),
364
427
  computed_at: computedAt,
365
428
  createdAt: existingDoc?.createdAt ?? computedAt,
366
429
  updatedAt: computedAt,
367
430
  };
368
- if (existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, report)) {
431
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, report)) {
369
432
  skippedDocuments.push(existingDoc);
370
433
  continue;
371
434
  }
@@ -375,11 +438,20 @@ function buildTenantPrepTimeCloseDayPlan(input) {
375
438
  // ---- the DAY scope: written straight from the compile --------------------
376
439
  for (const doc of compiledDateDocs) {
377
440
  const existingDoc = existingByScope.get(prepScopeKey(doc)) ?? null;
378
- if (existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, doc)) {
441
+ const report = {
442
+ ...doc,
443
+ // A reclose REPLACES the stored day document: preserving its _id and
444
+ // createdAt keeps the identity + immutable fields stable (Mongo rejects a
445
+ // replace that alters _id).
446
+ _id: existingDoc?._id ?? doc._id,
447
+ createdAt: existingDoc?.createdAt ?? doc.createdAt,
448
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
449
+ };
450
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, report)) {
379
451
  skippedDocuments.push(existingDoc);
380
452
  continue;
381
453
  }
382
- if (!addWrite(doc))
454
+ if (!addWrite(report))
383
455
  return null;
384
456
  }
385
457
  // ---- entry documents ------------------------------------------------------
@@ -455,14 +527,14 @@ function buildTenantPrepTimeCloseDayPlan(input) {
455
527
  day_index: null,
456
528
  sale_type_key_filters: existingDoc?.sale_type_key_filters ?? entries[0]?.sale_type_key_filters ?? [],
457
529
  prep_time_entries: sections,
458
- iteration: existingDoc?.iteration,
530
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
459
531
  schema_version: existingDoc?.schema_version ?? 1,
460
532
  source_watermark: entryWatermark ?? new Date(computedAt),
461
533
  computed_at: computedAt,
462
534
  createdAt: existingDoc?.createdAt ?? computedAt,
463
535
  updatedAt: computedAt,
464
536
  };
465
- if (existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, report)) {
537
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, report)) {
466
538
  skippedEntryDocuments.push(existingDoc);
467
539
  continue;
468
540
  }
@@ -473,11 +545,17 @@ function buildTenantPrepTimeCloseDayPlan(input) {
473
545
  if (doc.scope_context !== MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE)
474
546
  continue;
475
547
  const existingDoc = existingEntriesByScope.get(prepScopeKey(doc)) ?? null;
476
- if (existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, doc)) {
548
+ const report = {
549
+ ...doc,
550
+ _id: existingDoc?._id ?? doc._id,
551
+ createdAt: existingDoc?.createdAt ?? doc.createdAt,
552
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
553
+ };
554
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, report)) {
477
555
  skippedEntryDocuments.push(existingDoc);
478
556
  continue;
479
557
  }
480
- if (!addEntryWrite(doc))
558
+ if (!addEntryWrite(report))
481
559
  return null;
482
560
  }
483
561
  return {
@@ -0,0 +1,179 @@
1
+ import { IPrepTimeCategoriesResult, IPrepTimeCategoryRow, IPrepTimeCoverage, IPrepTimeItemRow, IPrepTimeReadFilters, IPrepTimeSeriesPoint, IPrepTimeSeriesResult, TMaterializedPrepTimeItemSort, TMaterializedPrepTimeReadAnchor } from '../types/materialized-reports-apis';
2
+ /**
3
+ * Pure read helpers for the PREP TIME item-level reads
4
+ * (`/reports/prep-time/items|categories|series`).
5
+ *
6
+ * The service reads ONE normalized row shape from either source (the flat
7
+ * drill-down projection for historical reads, the live compile for live reads)
8
+ * and EVERY aggregation below is shared by both modes — that is what makes live
9
+ * and historical parity structural instead of something to test by accident.
10
+ *
11
+ * THE RULES (frozen API contract):
12
+ *
13
+ * - filters apply BEFORE grouping;
14
+ * - coverage spans BOTH anchor populations (after every non-anchor filter), so a
15
+ * Measured view can still state how much of the operation was observed;
16
+ * - the anchor filter is a ROW filter (`MEASURED` / `UNMEASURED`); the Items
17
+ * route defaults it to `MEASURED`, categories/series default to BOTH;
18
+ * - only MEASURED rows contribute to avg / median / p90 / on-time grading;
19
+ * - only MEASURED rows with a target (`delta_minutes != null`) are graded;
20
+ * - durations outside `[0, MATERIALIZED_PREP_TIME_MAX_MINUTES]` are excluded
21
+ * from avg / median / p90 but STILL count as measured coverage;
22
+ * - percentiles are EXACT (computed from the raw durations, linearly
23
+ * interpolated), never derived from the histogram buckets;
24
+ * - a zero population yields `null`, never `0`.
25
+ *
26
+ * Everything here is pure and deterministic: no DB, no clock, no locale
27
+ * comparison (plain code-unit ordering), so the same input always produces the
28
+ * same rows, sort order and cursor page.
29
+ */
30
+ /** One normalized item row, as read from the flat projection or the live compile. */
31
+ export interface IPrepTimeReadRow {
32
+ /** Optional (brand reads); never part of the API row. */
33
+ tenant_id?: string | null;
34
+ order_id: string;
35
+ item_id: string;
36
+ item_name: string | null;
37
+ category_name: string | null;
38
+ anchor: TMaterializedPrepTimeReadAnchor;
39
+ /** Stored `ready_minutes`; null when never tracked. */
40
+ duration_minutes: number | null;
41
+ /** SIGNED minutes (ready - target); null when the row could not be graded. */
42
+ delta_minutes: number | null;
43
+ order_status: string;
44
+ platform: string;
45
+ created_at: Date | string;
46
+ /** The business day the row belongs to (`YYYY-MM-DD`). */
47
+ source_local_date: string;
48
+ }
49
+ /** Structured cursor (the wire cursor is this object, encoded by the service). */
50
+ export interface IPrepTimeItemSortCursor {
51
+ sort_value: string | number | null;
52
+ item_id: string;
53
+ }
54
+ /** The Items read BEFORE the cursor is made opaque (`IPrepTimeItemsPage` is the wire shape). */
55
+ export interface IPrepTimeItemsResult {
56
+ rows: IPrepTimeItemRow[];
57
+ next_cursor: IPrepTimeItemSortCursor | null;
58
+ coverage: IPrepTimeCoverage;
59
+ }
60
+ export type TPrepTimeReadFiltersParseResult = {
61
+ ok: true;
62
+ filters: IPrepTimeReadFilters;
63
+ } | {
64
+ ok: false;
65
+ };
66
+ /**
67
+ * Validates and NORMALIZES the request `filters` object. Never throws.
68
+ *
69
+ * `category_names` is ignored by the categories read (the read groups BY
70
+ * category, so a category filter would only hide the other cards) — the caller
71
+ * passes `ignoreCategoryNames` there.
72
+ */
73
+ export declare function parseMaterializedPrepTimeReadFilters(value: unknown, options?: {
74
+ ignoreCategoryNames?: boolean;
75
+ }): TPrepTimeReadFiltersParseResult;
76
+ /** Stable representation of normalized filters (cursor signature input). */
77
+ export declare function buildMaterializedPrepTimeFilterSignature(filters?: IPrepTimeReadFilters | null): string;
78
+ /** True when the row is a late, measured, graded row. */
79
+ export declare function isMaterializedPrepTimeLateRow(row: IPrepTimeReadRow): boolean;
80
+ /** True when the row is MEASURED and its duration may feed avg / median / p90. */
81
+ export declare function isMaterializedPrepTimeDurationCountable(minutes: unknown): minutes is number;
82
+ /**
83
+ * MEASURED / UNMEASURED row split. `anchor` null (or omitted) keeps BOTH
84
+ * populations — the categories / series default.
85
+ */
86
+ export declare function filterMaterializedPrepTimeRowsByAnchor(rows: IPrepTimeReadRow[] | null | undefined, anchor?: TMaterializedPrepTimeReadAnchor | null): IPrepTimeReadRow[];
87
+ /** True when one row passes every supplied filter. */
88
+ export declare function matchesMaterializedPrepTimeReadFilters(row: IPrepTimeReadRow, filters?: IPrepTimeReadFilters | null): boolean;
89
+ /** Returns only the rows that pass the filters (filters apply BEFORE grouping). */
90
+ export declare function applyMaterializedPrepTimeReadFilters(rows: IPrepTimeReadRow[] | null | undefined, filters?: IPrepTimeReadFilters | null): IPrepTimeReadRow[];
91
+ /**
92
+ * The filters minus the ANCHOR view selector.
93
+ *
94
+ * Anchoring selects which rows a view LISTS (Measured / Unmeasured). Coverage is
95
+ * the report's headline, so it is computed over the population BEFORE the anchor
96
+ * view is applied (but after every other filter) — that is how a Measured view
97
+ * can still state "1,192 of 1,552 served items have their own prep clock".
98
+ */
99
+ export declare const withoutMaterializedPrepTimeAnchorFilter: (filters?: IPrepTimeReadFilters | null) => IPrepTimeReadFilters;
100
+ /** Coverage of the supplied population (measured / served, one decimal). */
101
+ export declare function buildMaterializedPrepTimeCoverage(rows: IPrepTimeReadRow[] | null | undefined): IPrepTimeCoverage;
102
+ /**
103
+ * EXACT percentile of an UNSORTED duration list, linearly interpolated between
104
+ * the two closest ranks (the standard R-7 definition; the median of an even
105
+ * population is the mean of the two middle values). Returns null for an empty
106
+ * population. The result is rounded to one decimal — the underlying stored
107
+ * durations are whole minutes.
108
+ */
109
+ export declare function getMaterializedPrepTimePercentile(values: number[] | null | undefined, percentile: number): number | null;
110
+ /** EXACT median (p50), interpolated for even populations. */
111
+ export declare function getMaterializedPrepTimeMedian(values: number[] | null | undefined): number | null;
112
+ /** EXACT p90 (interpolated). */
113
+ export declare function getMaterializedPrepTimeP90(values: number[] | null | undefined): number | null;
114
+ /**
115
+ * Groups filtered rows by `item_id` (never by name). Counts are per ROW, so an
116
+ * item sold on many orders is never collapsed into one sale.
117
+ */
118
+ export declare function groupMaterializedPrepTimeItemRows(rows: IPrepTimeReadRow[] | null | undefined, filters?: IPrepTimeReadFilters | null): IPrepTimeItemRow[];
119
+ /** True when `value` is one of the frozen item sort modes. */
120
+ export declare function isMaterializedPrepTimeItemSort(value: unknown): value is TMaterializedPrepTimeItemSort;
121
+ /** The sort value of one item row (the cursor stores it verbatim). */
122
+ export declare function getMaterializedPrepTimeItemSortValue(row: IPrepTimeItemRow, sort: TMaterializedPrepTimeItemSort): string | number | null;
123
+ /** Total comparator: sort value first, `item_id` ascending as the final tie-break. */
124
+ export declare function compareMaterializedPrepTimeItemRows(a: IPrepTimeItemRow, b: IPrepTimeItemRow, sort: TMaterializedPrepTimeItemSort): number;
125
+ /** Stable sort (never mutates the input array). */
126
+ export declare function sortMaterializedPrepTimeItemRows(rows: IPrepTimeItemRow[] | null | undefined, sort: TMaterializedPrepTimeItemSort): IPrepTimeItemRow[];
127
+ /**
128
+ * Cuts one page strictly AFTER the cursor. Because the comparator is total, no
129
+ * row can be duplicated or skipped between pages.
130
+ */
131
+ export declare function getMaterializedPrepTimeItemPage(rows: IPrepTimeItemRow[] | null | undefined, sort: TMaterializedPrepTimeItemSort, cursor?: IPrepTimeItemSortCursor | null, limit?: number): {
132
+ rows: IPrepTimeItemRow[];
133
+ next_cursor: IPrepTimeItemSortCursor | null;
134
+ };
135
+ /**
136
+ * The complete Items read: filters -> grouping -> stable sort -> cursor page.
137
+ *
138
+ * The LISTED rows follow the anchor view; coverage spans both anchor
139
+ * populations (after every other filter) and is independent of the page window,
140
+ * so the measured view can still show the observed share of the whole period.
141
+ */
142
+ export declare function buildMaterializedPrepTimeItemsPage(args: {
143
+ rows: IPrepTimeReadRow[] | null | undefined;
144
+ filters?: IPrepTimeReadFilters | null;
145
+ sort?: TMaterializedPrepTimeItemSort | null;
146
+ cursor?: IPrepTimeItemSortCursor | null;
147
+ limit?: number;
148
+ }): IPrepTimeItemsResult;
149
+ /**
150
+ * Groups filtered rows by EXACT `category_name`. Rows without a category are
151
+ * not attributable to a category card and are excluded from this read (and
152
+ * therefore from its coverage); the Items and Series reads still count them.
153
+ *
154
+ * Sort: `measured_count` DESC, then `category_name` ASC (stable by construction
155
+ * — category names are the group identity).
156
+ */
157
+ export declare function groupMaterializedPrepTimeCategoryRows(rows: IPrepTimeReadRow[] | null | undefined, filters?: IPrepTimeReadFilters | null): IPrepTimeCategoryRow[];
158
+ /** The complete Categories read (rows + coverage over the same population). */
159
+ export declare function buildMaterializedPrepTimeCategoriesResult(args: {
160
+ rows: IPrepTimeReadRow[] | null | undefined;
161
+ filters?: IPrepTimeReadFilters | null;
162
+ }): IPrepTimeCategoriesResult;
163
+ /**
164
+ * Groups filtered rows by their SOURCE local date (`YYYY-MM-DD`), ascending.
165
+ *
166
+ * Never derives a day from `created_at` (a UTC day would shift the tenant's
167
+ * evening into the next date) and never emits an empty date. Rows without a
168
+ * valid source date cannot be plotted and are excluded from this read (and its
169
+ * coverage); the day-scoped flat projection always carries one.
170
+ */
171
+ export declare function groupMaterializedPrepTimeSeriesPoints(rows: IPrepTimeReadRow[] | null | undefined, filters?: IPrepTimeReadFilters | null): IPrepTimeSeriesPoint[];
172
+ /**
173
+ * The complete Series read. `target_minutes` is ALWAYS null: no tenant prep
174
+ * target exists in the read contract yet, and the report must not invent one.
175
+ */
176
+ export declare function buildMaterializedPrepTimeSeriesResult(args: {
177
+ rows: IPrepTimeReadRow[] | null | undefined;
178
+ filters?: IPrepTimeReadFilters | null;
179
+ }): IPrepTimeSeriesResult;