@managesome/eposmatic-toolkit 0.4.32 → 0.4.35
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.
- package/esm/constants/MATERIALIZED_REPORTS.js +22 -4
- package/esm/constants/enums/offers.js +0 -6
- package/esm/helpers/materialized-reports/index.js +1 -0
- package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +4 -0
- package/esm/helpers/materialized-reports/materialized-prep-time-classification-helpers.js +12 -8
- package/esm/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +141 -10
- package/esm/helpers/materialized-reports/materialized-prep-time-compile-helpers.js +7 -3
- package/esm/helpers/materialized-reports/materialized-prep-time-read-helpers.js +638 -0
- package/esm/helpers/types/materialized-reports-apis.js +10 -0
- package/esm/schemas/models/index.js +0 -1
- package/esm/schemas/models/materialized_tenant_prep_time_entries.js +2 -2
- package/esm/schemas/types/index.js +0 -1
- package/lib/constants/MATERIALIZED_REPORTS.d.ts +17 -4
- package/lib/constants/MATERIALIZED_REPORTS.js +24 -6
- package/lib/constants/enums/offers.d.ts +0 -5
- package/lib/constants/enums/offers.js +1 -7
- package/lib/helpers/materialized-reports/index.d.ts +1 -0
- package/lib/helpers/materialized-reports/index.js +1 -0
- package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +4 -0
- package/lib/helpers/materialized-reports/materialized-prep-time-classification-helpers.js +12 -8
- package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.d.ts +22 -0
- package/lib/helpers/materialized-reports/materialized-prep-time-close-day-helpers.js +142 -9
- package/lib/helpers/materialized-reports/materialized-prep-time-compile-helpers.js +6 -2
- package/lib/helpers/materialized-reports/materialized-prep-time-read-helpers.d.ts +198 -0
- package/lib/helpers/materialized-reports/materialized-prep-time-read-helpers.js +666 -0
- package/lib/helpers/types/materialized-reports-apis.d.ts +145 -1
- package/lib/helpers/types/materialized-reports-apis.js +11 -0
- package/lib/schemas/models/index.d.ts +0 -1
- package/lib/schemas/models/index.js +0 -1
- package/lib/schemas/models/materialized_tenant_prep_time_entries.d.ts +6 -6
- package/lib/schemas/models/materialized_tenant_prep_time_entries.js +1 -1
- package/lib/schemas/types/index.d.ts +0 -1
- package/lib/schemas/types/index.js +0 -1
- package/lib/schemas/types/materialized_tenant_prep_time_reports.d.ts +7 -5
- package/lib/tests/materialized-reports/materialized-prep-time-classification.test.js +28 -5
- package/lib/tests/materialized-reports/materialized-prep-time-close-day.test.js +33 -1
- package/lib/tests/materialized-reports/materialized-prep-time-compile.test.js +10 -1
- package/lib/tests/materialized-reports/materialized-prep-time-constants.test.js +14 -1
- package/lib/tests/materialized-reports/materialized-prep-time-duration-consistency.test.js +135 -0
- package/lib/tests/materialized-reports/materialized-prep-time-plan.test.js +106 -0
- package/lib/tests/materialized-reports/materialized-prep-time-read-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-prep-time-read-helpers.test.js +620 -0
- package/lib/tests/offers-matrix.test.d.ts +1 -0
- package/lib/tests/offers-matrix.test.js +401 -0
- package/package.json +1 -1
- package/esm/schemas/models/rewards_usage.js +0 -61
- package/lib/schemas/models/rewards_usage.d.ts +0 -53
- package/lib/schemas/models/rewards_usage.js +0 -64
- package/lib/schemas/types/rewards_usage.d.ts +0 -13
- package/lib/schemas/types/rewards_usage.js +0 -2
- /package/{esm/schemas/types/rewards_usage.js → lib/tests/materialized-reports/materialized-prep-time-duration-consistency.test.d.ts} +0 -0
|
@@ -0,0 +1,198 @@
|
|
|
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
|
+
/**
|
|
101
|
+
* Coverage from COUNTS (the server-side Series aggregation groups in Mongo and
|
|
102
|
+
* therefore has no raw rows). Same math as `buildMaterializedPrepTimeCoverage`.
|
|
103
|
+
*/
|
|
104
|
+
export declare function buildMaterializedPrepTimeCoverageFromCounts(input: {
|
|
105
|
+
served_count: number;
|
|
106
|
+
measured_count: number;
|
|
107
|
+
}): IPrepTimeCoverage;
|
|
108
|
+
/** Coverage of the supplied population (measured / served, one decimal). */
|
|
109
|
+
export declare function buildMaterializedPrepTimeCoverage(rows: IPrepTimeReadRow[] | null | undefined): IPrepTimeCoverage;
|
|
110
|
+
/**
|
|
111
|
+
* EXACT percentile of an UNSORTED duration list, linearly interpolated between
|
|
112
|
+
* the two closest ranks (the standard R-7 definition; the median of an even
|
|
113
|
+
* population is the mean of the two middle values). Returns null for an empty
|
|
114
|
+
* population. The result is rounded to one decimal — the underlying stored
|
|
115
|
+
* durations are whole minutes.
|
|
116
|
+
*/
|
|
117
|
+
export declare function getMaterializedPrepTimePercentile(values: number[] | null | undefined, percentile: number): number | null;
|
|
118
|
+
/** EXACT median (p50), interpolated for even populations. */
|
|
119
|
+
export declare function getMaterializedPrepTimeMedian(values: number[] | null | undefined): number | null;
|
|
120
|
+
/** EXACT p90 (interpolated). */
|
|
121
|
+
export declare function getMaterializedPrepTimeP90(values: number[] | null | undefined): number | null;
|
|
122
|
+
/** The three duration statistics for ONE population (avg / exact median / exact p90). */
|
|
123
|
+
export interface IPrepTimeDurationSummary {
|
|
124
|
+
avg_minutes: number | null;
|
|
125
|
+
median_minutes: number | null;
|
|
126
|
+
p90_minutes: number | null;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Duration statistics for a list of VALID durations (invalid values are
|
|
130
|
+
* filtered defensively). `null` for an empty population — never 0.
|
|
131
|
+
*/
|
|
132
|
+
export declare function summarizeMaterializedPrepTimeDurations(durations: number[] | null | undefined): IPrepTimeDurationSummary;
|
|
133
|
+
/**
|
|
134
|
+
* Groups filtered rows by `item_id` (never by name). Counts are per ROW, so an
|
|
135
|
+
* item sold on many orders is never collapsed into one sale.
|
|
136
|
+
*/
|
|
137
|
+
export declare function groupMaterializedPrepTimeItemRows(rows: IPrepTimeReadRow[] | null | undefined, filters?: IPrepTimeReadFilters | null): IPrepTimeItemRow[];
|
|
138
|
+
/** True when `value` is one of the frozen item sort modes. */
|
|
139
|
+
export declare function isMaterializedPrepTimeItemSort(value: unknown): value is TMaterializedPrepTimeItemSort;
|
|
140
|
+
/** The sort value of one item row (the cursor stores it verbatim). */
|
|
141
|
+
export declare function getMaterializedPrepTimeItemSortValue(row: IPrepTimeItemRow, sort: TMaterializedPrepTimeItemSort): string | number | null;
|
|
142
|
+
/** Total comparator: sort value first, `item_id` ascending as the final tie-break. */
|
|
143
|
+
export declare function compareMaterializedPrepTimeItemRows(a: IPrepTimeItemRow, b: IPrepTimeItemRow, sort: TMaterializedPrepTimeItemSort): number;
|
|
144
|
+
/** Stable sort (never mutates the input array). */
|
|
145
|
+
export declare function sortMaterializedPrepTimeItemRows(rows: IPrepTimeItemRow[] | null | undefined, sort: TMaterializedPrepTimeItemSort): IPrepTimeItemRow[];
|
|
146
|
+
/**
|
|
147
|
+
* Cuts one page strictly AFTER the cursor. Because the comparator is total, no
|
|
148
|
+
* row can be duplicated or skipped between pages.
|
|
149
|
+
*/
|
|
150
|
+
export declare function getMaterializedPrepTimeItemPage(rows: IPrepTimeItemRow[] | null | undefined, sort: TMaterializedPrepTimeItemSort, cursor?: IPrepTimeItemSortCursor | null, limit?: number): {
|
|
151
|
+
rows: IPrepTimeItemRow[];
|
|
152
|
+
next_cursor: IPrepTimeItemSortCursor | null;
|
|
153
|
+
};
|
|
154
|
+
/**
|
|
155
|
+
* The complete Items read: filters -> grouping -> stable sort -> cursor page.
|
|
156
|
+
*
|
|
157
|
+
* The LISTED rows follow the anchor view; coverage spans both anchor
|
|
158
|
+
* populations (after every other filter) and is independent of the page window,
|
|
159
|
+
* so the measured view can still show the observed share of the whole period.
|
|
160
|
+
*/
|
|
161
|
+
export declare function buildMaterializedPrepTimeItemsPage(args: {
|
|
162
|
+
rows: IPrepTimeReadRow[] | null | undefined;
|
|
163
|
+
filters?: IPrepTimeReadFilters | null;
|
|
164
|
+
sort?: TMaterializedPrepTimeItemSort | null;
|
|
165
|
+
cursor?: IPrepTimeItemSortCursor | null;
|
|
166
|
+
limit?: number;
|
|
167
|
+
}): IPrepTimeItemsResult;
|
|
168
|
+
/**
|
|
169
|
+
* Groups filtered rows by EXACT `category_name`. Rows without a category are
|
|
170
|
+
* not attributable to a category card and are excluded from this read (and
|
|
171
|
+
* therefore from its coverage); the Items and Series reads still count them.
|
|
172
|
+
*
|
|
173
|
+
* Sort: `measured_count` DESC, then `category_name` ASC (stable by construction
|
|
174
|
+
* — category names are the group identity).
|
|
175
|
+
*/
|
|
176
|
+
export declare function groupMaterializedPrepTimeCategoryRows(rows: IPrepTimeReadRow[] | null | undefined, filters?: IPrepTimeReadFilters | null): IPrepTimeCategoryRow[];
|
|
177
|
+
/** The complete Categories read (rows + coverage over the same population). */
|
|
178
|
+
export declare function buildMaterializedPrepTimeCategoriesResult(args: {
|
|
179
|
+
rows: IPrepTimeReadRow[] | null | undefined;
|
|
180
|
+
filters?: IPrepTimeReadFilters | null;
|
|
181
|
+
}): IPrepTimeCategoriesResult;
|
|
182
|
+
/**
|
|
183
|
+
* Groups filtered rows by their SOURCE local date (`YYYY-MM-DD`), ascending.
|
|
184
|
+
*
|
|
185
|
+
* Never derives a day from `created_at` (a UTC day would shift the tenant's
|
|
186
|
+
* evening into the next date) and never emits an empty date. Rows without a
|
|
187
|
+
* valid source date cannot be plotted and are excluded from this read (and its
|
|
188
|
+
* coverage); the day-scoped flat projection always carries one.
|
|
189
|
+
*/
|
|
190
|
+
export declare function groupMaterializedPrepTimeSeriesPoints(rows: IPrepTimeReadRow[] | null | undefined, filters?: IPrepTimeReadFilters | null): IPrepTimeSeriesPoint[];
|
|
191
|
+
/**
|
|
192
|
+
* The complete Series read. `target_minutes` is ALWAYS null: no tenant prep
|
|
193
|
+
* target exists in the read contract yet, and the report must not invent one.
|
|
194
|
+
*/
|
|
195
|
+
export declare function buildMaterializedPrepTimeSeriesResult(args: {
|
|
196
|
+
rows: IPrepTimeReadRow[] | null | undefined;
|
|
197
|
+
filters?: IPrepTimeReadFilters | null;
|
|
198
|
+
}): IPrepTimeSeriesResult;
|