@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
@@ -421,17 +421,15 @@ export const MATERIALIZED_DELIVERY_AREA_LIMIT = 50;
421
421
  *
422
422
  * NO `localHour` (decision h2): the tracked population per hour is 2-3 items in
423
423
  * the dev stores, so an hourly prep time would be noise. Day + periods only,
424
- * capped at `LOCAL_MONTH` because the itemized rows live in the SIBLING entries
425
- * collection (`materialized_tenant_prep_time_entries`).
424
+ * CAPPED AT `LOCAL_MONTH`: quarter / semester / year are deliberately absent so
425
+ * the Summary, Details and the item-level reads all apply the SAME range policy,
426
+ * and the itemized rows in the sibling entries collection stay month-bounded.
426
427
  */
427
428
  export const MATERIALIZED_PREP_TIME_REPORT_SCOPES = [
428
429
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
429
430
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK,
430
431
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR,
431
432
  MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
432
- MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_QUARTER,
433
- MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_SEMESTER,
434
- MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
435
433
  ];
436
434
  /** Ordered key filters of the prep time report (`COMPLETED:POS_WALK-IN`). */
437
435
  export const PREP_TIME_KEY_FILTERS = [
@@ -65,12 +65,6 @@ export var PATHWAY_TO_UNLOCK_TYPE_ENUM;
65
65
  PATHWAY_TO_UNLOCK_TYPE_ENUM["POINTS"] = "POINTS";
66
66
  })(PATHWAY_TO_UNLOCK_TYPE_ENUM || (PATHWAY_TO_UNLOCK_TYPE_ENUM = {}));
67
67
  export const ALL_PATHWAY_TO_UNLOCK_TYPES = Object.values(PATHWAY_TO_UNLOCK_TYPE_ENUM);
68
- export var REWARDS_USAGE_REF_TYPE_ENUM;
69
- (function (REWARDS_USAGE_REF_TYPE_ENUM) {
70
- REWARDS_USAGE_REF_TYPE_ENUM["VOUCHER"] = "VOUCHER";
71
- REWARDS_USAGE_REF_TYPE_ENUM["GIFT_CARD"] = "GIFT_CARD";
72
- })(REWARDS_USAGE_REF_TYPE_ENUM || (REWARDS_USAGE_REF_TYPE_ENUM = {}));
73
- export const ALL_REWARDS_USAGE_REF_TYPES = Object.values(REWARDS_USAGE_REF_TYPE_ENUM);
74
68
  /* ================><================= */
75
69
  export var RATING_TYPE_ENUM;
76
70
  (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';
@@ -3,6 +3,8 @@ import { MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS, MATERIALIZED_TENANT
3
3
  import { MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS, MATERIALIZED_TENANT_DISCOUNT_REPORTS_COLLECTION_NAME, } from '../../schemas/models/materialized_tenant_discount_reports';
4
4
  import { MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS, MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_NAME, } from '../../schemas/models/materialized_tenant_discount_sources';
5
5
  import { MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME, MATERIALIZED_TENANT_REPORTS_ITERATIONS_INDEX_OPTIONS, } from '../../schemas/models/materialized_tenant_reports_iterations';
6
+ import { MATERIALIZED_TENANT_PREP_TIME_ENTRIES_COLLECTION_NAME, MATERIALIZED_TENANT_PREP_TIME_ENTRIES_INDEX_OPTIONS, } from '../../schemas/models/materialized_tenant_prep_time_entries';
7
+ import { MATERIALIZED_TENANT_PREP_TIME_REPORTS_COLLECTION_NAME, MATERIALIZED_TENANT_PREP_TIME_REPORTS_INDEX_OPTIONS, } from '../../schemas/models/materialized_tenant_prep_time_reports';
6
8
  import { MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_COLLECTION_NAME, MATERIALIZED_TENANT_SALES_OVERVIEW_REPORTS_INDEX_OPTIONS, } from '../../schemas/models/materialized_tenant_sales_overview_reports';
7
9
  import { MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME, MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS, MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME, MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS, } from '../../schemas/models/materialized_report_drilldown_rows';
8
10
  import { TENANT_CALENDAR_COLLECTION_NAME, TENANT_CALENDAR_INDEX_OPTIONS } from '../../schemas/models/tenant_calendar';
@@ -25,6 +27,8 @@ const INDEXES = {
25
27
  [MATERIALIZED_TENANT_DISCOUNT_REPORTS_COLLECTION_NAME]: MATERIALIZED_TENANT_DISCOUNT_REPORTS_INDEX_OPTIONS,
26
28
  [MATERIALIZED_TENANT_DISCOUNT_ENTRIES_COLLECTION_NAME]: MATERIALIZED_TENANT_DISCOUNT_ENTRIES_INDEX_OPTIONS,
27
29
  [MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_NAME]: MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS,
30
+ [MATERIALIZED_TENANT_PREP_TIME_REPORTS_COLLECTION_NAME]: MATERIALIZED_TENANT_PREP_TIME_REPORTS_INDEX_OPTIONS,
31
+ [MATERIALIZED_TENANT_PREP_TIME_ENTRIES_COLLECTION_NAME]: MATERIALIZED_TENANT_PREP_TIME_ENTRIES_INDEX_OPTIONS,
28
32
  [MATERIALIZED_TENANT_REPORTS_ITERATIONS_COLLECTION_NAME]: MATERIALIZED_TENANT_REPORTS_ITERATIONS_INDEX_OPTIONS,
29
33
  [MATERIALIZED_REPORT_DRILLDOWN_ROWS_COLLECTION_NAME]: MATERIALIZED_REPORT_DRILLDOWN_ROWS_INDEX_OPTIONS,
30
34
  [MATERIALIZED_REPORT_DRILLDOWN_SCOPES_COLLECTION_NAME]: MATERIALIZED_REPORT_DRILLDOWN_SCOPES_INDEX_OPTIONS,
@@ -142,14 +142,18 @@ export function accumulateOrderPrepTime({ order, context, tenantDefaultMinutes =
142
142
  counters.coverage.own_anchor_count += 1;
143
143
  // RECONSTRUCTED ready instant - the source field ready_at does not exist.
144
144
  readyAt = new Date(prepStartedAt.getTime() + minutes * 60000);
145
- counters.duration.count += 1;
146
- if (minutes === 0)
147
- counters.duration.instant_count += 1;
148
- const bucket = resolveMaterializedPrepTimeBucket(minutes);
149
- counters.duration.buckets[bucket] = (counters.duration.buckets[bucket] ?? 0) + 1;
150
- // Counts above stay complete; only the EXTREMES are guarded, so a single
151
- // clock/backfill artefact cannot define min/max/sum.
152
- if (minutes <= MATERIALIZED_PREP_TIME_MAX_MINUTES) {
145
+ // ONE canonical duration population: a duration is VALID only when it
146
+ // is finite, >= 0 and <= the outlier cap. Valid durations alone feed
147
+ // count / sum / min / max / buckets / instant count (and therefore
148
+ // avg = sum/count). An artefact must never understate the average by
149
+ // sitting in the denominator while being excluded from the numerator.
150
+ // Coverage still counts the MEASURED row (own_anchor_count above).
151
+ if (minutes >= 0 && minutes <= MATERIALIZED_PREP_TIME_MAX_MINUTES) {
152
+ counters.duration.count += 1;
153
+ if (minutes === 0)
154
+ counters.duration.instant_count += 1;
155
+ const bucket = resolveMaterializedPrepTimeBucket(minutes);
156
+ counters.duration.buckets[bucket] = (counters.duration.buckets[bucket] ?? 0) + 1;
153
157
  counters.duration.sum += minutes;
154
158
  if (counters.duration.count === 1 || minutes < counters.duration.min) {
155
159
  counters.duration.min = minutes;
@@ -3,7 +3,7 @@ import { MATERIALIZED_PREP_TIME_REPORT_SCOPES, MATERIALIZED_REPORT_SCOPE_ENUM, M
3
3
  import { freshMaterializedPrepTimeCounters } from './materialized-prep-time-classification-helpers';
4
4
  import { mergeMaterializedPrepTimeCounters } from './materialized-prep-time-compile-helpers';
5
5
  import { buildMaterializedTenantReportIteration } from './materialized-tenant-reports-iterations-helpers';
6
- import { getMaterializedPeriodScopeFields } from './scope-helpers';
6
+ import { getMaterializedPeriodScopeFields, parseMaterializedLocalDate, } from './scope-helpers';
7
7
  /**
8
8
  * M2 close-day helpers.
9
9
  *
@@ -154,6 +154,67 @@ export function foldMaterializedPrepTimePeriodRows({ periodScopeField, periodSco
154
154
  }
155
155
  /** The period scope contexts (everything except the day scope). */
156
156
  export const MATERIALIZED_PREP_TIME_PERIOD_SCOPES = MATERIALIZED_PREP_TIME_REPORT_SCOPES.filter((scope) => !isMaterializedPrepTimeDayScope(String(scope)));
157
+ /* ------------------------------------------------------------------------ */
158
+ /* Period sibling-day enumeration */
159
+ /* ------------------------------------------------------------------------ */
160
+ const pad2 = (value) => String(value).padStart(2, '0');
161
+ const toLocalDateKey = (date) => `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(date.getUTCDate())}`;
162
+ const addUtcDays = (date, amount) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + amount));
163
+ const addMonthDays = (year, month, days) => {
164
+ if (!Number.isInteger(year) || !Number.isInteger(month) || month < 1 || month > 12)
165
+ return false;
166
+ const last = new Date(Date.UTC(year, month, 0)).getUTCDate();
167
+ for (let day = 1; day <= last; day += 1) {
168
+ days.add(`${year}-${pad2(month)}-${pad2(day)}`);
169
+ }
170
+ return true;
171
+ };
172
+ /**
173
+ * Every `localDate` label whose DAY entry document can contribute to a period
174
+ * the closing day rolls into (week / ISO week / month).
175
+ *
176
+ * The worker uses this to fetch exactly the sibling day entries the period
177
+ * fold needs — never a full-period entry document and never a year-wide scan.
178
+ * Returns `null` (never throws) for a malformed date.
179
+ */
180
+ export function getMaterializedPrepTimePeriodDayScopeFields(localDate) {
181
+ const periodFields = getMaterializedPeriodScopeFields(localDate);
182
+ if (periodFields == null)
183
+ return null;
184
+ const days = new Set([localDate]);
185
+ const weekField = periodFields[MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK];
186
+ const weekParts = typeof weekField === 'string' ? parseMaterializedLocalDate(weekField) : null;
187
+ if (weekParts == null)
188
+ return null;
189
+ const weekStart = new Date(Date.UTC(weekParts.year, weekParts.month - 1, weekParts.day));
190
+ if (weekStart.getUTCDay() !== 0)
191
+ return null;
192
+ for (let offset = 0; offset < 7; offset += 1) {
193
+ days.add(toLocalDateKey(addUtcDays(weekStart, offset)));
194
+ }
195
+ const isoWeekField = periodFields[MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR];
196
+ const isoMatch = typeof isoWeekField === 'string' ? /^(\d{4})-W(\d{2})$/.exec(isoWeekField) : null;
197
+ if (isoMatch == null)
198
+ return null;
199
+ const weekYear = Number(isoMatch[1]);
200
+ const week = Number(isoMatch[2]);
201
+ if (!Number.isInteger(week) || week < 1 || week > 53)
202
+ return null;
203
+ const jan4 = new Date(Date.UTC(weekYear, 0, 4));
204
+ const isoWeekday = jan4.getUTCDay() || 7;
205
+ const weekOneMonday = addUtcDays(jan4, 1 - isoWeekday);
206
+ const isoStart = addUtcDays(weekOneMonday, (week - 1) * 7);
207
+ for (let offset = 0; offset < 7; offset += 1) {
208
+ days.add(toLocalDateKey(addUtcDays(isoStart, offset)));
209
+ }
210
+ const monthField = periodFields[MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH];
211
+ const monthMatch = typeof monthField === 'string' ? /^(\d{4})-(\d{2})$/.exec(monthField) : null;
212
+ if (monthMatch == null)
213
+ return null;
214
+ if (!addMonthDays(Number(monthMatch[1]), Number(monthMatch[2]), days))
215
+ return null;
216
+ return [...days].sort();
217
+ }
157
218
  /** True when a stored prep counter document equals the incoming one (skip write). */
158
219
  export function needsMaterializedPrepTimeReportWrite(existing, incoming) {
159
220
  if (existing == null || incoming == null)
@@ -194,6 +255,7 @@ export function buildTenantPrepTimeCloseDayPlan(input) {
194
255
  if (reports.some((doc) => doc == null || doc.tenant_id !== tenantId))
195
256
  return null;
196
257
  const computedAt = input.computedAt ?? new Date();
258
+ const force = input.force === true;
197
259
  const existing = input.existing ?? [];
198
260
  const existingEntries = input.existingEntries ?? [];
199
261
  const dateDoc = reports.find((doc) => doc.scope_context === MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE) ?? null;
@@ -344,14 +406,14 @@ export function buildTenantPrepTimeCloseDayPlan(input) {
344
406
  sale_type_key_filters: existingDoc?.sale_type_key_filters ?? reports[0]?.sale_type_key_filters ?? [],
345
407
  prep_time_counters: counters,
346
408
  prep_time_counter_rows: counterRows,
347
- iteration: existingDoc?.iteration,
409
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
348
410
  schema_version: existingDoc?.schema_version ?? 1,
349
411
  source_watermark: watermark ?? new Date(computedAt),
350
412
  computed_at: computedAt,
351
413
  createdAt: existingDoc?.createdAt ?? computedAt,
352
414
  updatedAt: computedAt,
353
415
  };
354
- if (existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, report)) {
416
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, report)) {
355
417
  skippedDocuments.push(existingDoc);
356
418
  continue;
357
419
  }
@@ -361,11 +423,20 @@ export function buildTenantPrepTimeCloseDayPlan(input) {
361
423
  // ---- the DAY scope: written straight from the compile --------------------
362
424
  for (const doc of compiledDateDocs) {
363
425
  const existingDoc = existingByScope.get(prepScopeKey(doc)) ?? null;
364
- if (existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, doc)) {
426
+ const report = {
427
+ ...doc,
428
+ // A reclose REPLACES the stored day document: preserving its _id and
429
+ // createdAt keeps the identity + immutable fields stable (Mongo rejects a
430
+ // replace that alters _id).
431
+ _id: existingDoc?._id ?? doc._id,
432
+ createdAt: existingDoc?.createdAt ?? doc.createdAt,
433
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
434
+ };
435
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeReportWrite(existingDoc, report)) {
365
436
  skippedDocuments.push(existingDoc);
366
437
  continue;
367
438
  }
368
- if (!addWrite(doc))
439
+ if (!addWrite(report))
369
440
  return null;
370
441
  }
371
442
  // ---- entry documents ------------------------------------------------------
@@ -441,14 +512,14 @@ export function buildTenantPrepTimeCloseDayPlan(input) {
441
512
  day_index: null,
442
513
  sale_type_key_filters: existingDoc?.sale_type_key_filters ?? entries[0]?.sale_type_key_filters ?? [],
443
514
  prep_time_entries: sections,
444
- iteration: existingDoc?.iteration,
515
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
445
516
  schema_version: existingDoc?.schema_version ?? 1,
446
517
  source_watermark: entryWatermark ?? new Date(computedAt),
447
518
  computed_at: computedAt,
448
519
  createdAt: existingDoc?.createdAt ?? computedAt,
449
520
  updatedAt: computedAt,
450
521
  };
451
- if (existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, report)) {
522
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, report)) {
452
523
  skippedEntryDocuments.push(existingDoc);
453
524
  continue;
454
525
  }
@@ -459,11 +530,17 @@ export function buildTenantPrepTimeCloseDayPlan(input) {
459
530
  if (doc.scope_context !== MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE)
460
531
  continue;
461
532
  const existingDoc = existingEntriesByScope.get(prepScopeKey(doc)) ?? null;
462
- if (existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, doc)) {
533
+ const report = {
534
+ ...doc,
535
+ _id: existingDoc?._id ?? doc._id,
536
+ createdAt: existingDoc?.createdAt ?? doc.createdAt,
537
+ iteration: existingDoc == null ? 1 : (existingDoc.iteration ?? 1) + 1,
538
+ };
539
+ if (!force && existingDoc != null && !needsMaterializedPrepTimeEntriesWrite(existingDoc, report)) {
463
540
  skippedEntryDocuments.push(existingDoc);
464
541
  continue;
465
542
  }
466
- if (!addEntryWrite(doc))
543
+ if (!addEntryWrite(report))
467
544
  return null;
468
545
  }
469
546
  return {