@managesome/eposmatic-toolkit 0.4.31 → 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 (55) 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/store/cart-actions.js +3 -12
  9. package/esm/helpers/types/materialized-reports-apis.js +10 -0
  10. package/esm/helpers/utils/offer-apply-helpers.js +2 -10
  11. package/esm/helpers/utils/offers-helpers.js +117 -2
  12. package/esm/schemas/models/index.js +0 -1
  13. package/esm/schemas/types/index.js +0 -1
  14. package/lib/constants/MATERIALIZED_REPORTS.d.ts +3 -2
  15. package/lib/constants/MATERIALIZED_REPORTS.js +3 -5
  16. package/lib/constants/enums/offers.d.ts +0 -5
  17. package/lib/constants/enums/offers.js +1 -7
  18. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  19. package/lib/helpers/materialized-reports/index.js +1 -0
  20. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +4 -0
  21. package/lib/helpers/materialized-reports/materialized-prep-time-classification-helpers.js +12 -8
  22. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.d.ts +15 -0
  23. package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +86 -8
  24. package/lib/helpers/materialized-reports/materialized-prep-time-read-helpers.d.ts +179 -0
  25. package/lib/helpers/materialized-reports/materialized-prep-time-read-helpers.js +639 -0
  26. package/lib/helpers/store/cart-actions.js +1 -10
  27. package/lib/helpers/types/materialized-reports-apis.d.ts +145 -1
  28. package/lib/helpers/types/materialized-reports-apis.js +11 -0
  29. package/lib/helpers/utils/offer-apply-helpers.js +2 -10
  30. package/lib/helpers/utils/offers-helpers.d.ts +50 -0
  31. package/lib/helpers/utils/offers-helpers.js +120 -2
  32. package/lib/schemas/models/index.d.ts +0 -1
  33. package/lib/schemas/models/index.js +0 -1
  34. package/lib/schemas/models/materialized_tenant_prep_time_entries.d.ts +6 -6
  35. package/lib/schemas/types/index.d.ts +0 -1
  36. package/lib/schemas/types/index.js +0 -1
  37. package/lib/schemas/types/materialized_tenant_prep_time_reports.d.ts +7 -5
  38. package/lib/tests/materialized-reports/materialized-prep-time-classification.test.js +28 -5
  39. package/lib/tests/materialized-reports/materialized-prep-time-close-day.test.js +17 -4
  40. package/lib/tests/materialized-reports/materialized-prep-time-constants.test.js +6 -4
  41. package/lib/tests/materialized-reports/materialized-prep-time-duration-consistency.test.js +135 -0
  42. package/lib/tests/materialized-reports/materialized-prep-time-plan.test.js +71 -3
  43. package/lib/tests/materialized-reports/materialized-prep-time-read-helpers.test.d.ts +1 -0
  44. package/lib/tests/materialized-reports/materialized-prep-time-read-helpers.test.js +620 -0
  45. package/lib/tests/offers-helpers-points-evidence.test.d.ts +1 -0
  46. package/lib/tests/offers-helpers-points-evidence.test.js +338 -0
  47. package/lib/tests/offers-matrix.test.d.ts +1 -0
  48. package/lib/tests/offers-matrix.test.js +401 -0
  49. package/package.json +1 -1
  50. package/esm/schemas/models/rewards_usage.js +0 -61
  51. package/lib/schemas/models/rewards_usage.d.ts +0 -53
  52. package/lib/schemas/models/rewards_usage.js +0 -64
  53. package/lib/schemas/types/rewards_usage.d.ts +0 -13
  54. package/lib/schemas/types/rewards_usage.js +0 -2
  55. /package/{esm/schemas/types/rewards_usage.js → lib/tests/materialized-reports/materialized-prep-time-duration-consistency.test.d.ts} +0 -0
@@ -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;