@managesome/eposmatic-toolkit 0.4.5 → 0.4.8
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 +33 -0
- package/esm/constants/REPORT_CALENDAR.js +47 -0
- package/esm/constants/index.js +1 -0
- package/esm/helpers/materialized-reports/index.js +2 -0
- package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +982 -0
- package/esm/helpers/materialized-reports/materialized-reports-read-helpers.js +1 -76
- package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +716 -0
- package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +327 -41
- package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
- package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +118 -235
- package/esm/helpers/types/index.js +1 -0
- package/esm/schemas/models/index.js +1 -0
- package/esm/schemas/models/materialized_credit_bills.js +265 -0
- package/esm/schemas/models/materialized_tenant_reports_iterations.js +13 -0
- package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +39 -97
- package/esm/schemas/types/index.js +1 -0
- package/esm/schemas/types/materialized_credit_bills.js +1 -0
- package/lib/constants/MATERIALIZED_REPORTS.d.ts +28 -2
- package/lib/constants/MATERIALIZED_REPORTS.js +34 -1
- package/lib/constants/REPORT_CALENDAR.d.ts +31 -0
- package/lib/constants/REPORT_CALENDAR.js +50 -0
- package/lib/constants/index.d.ts +1 -0
- package/lib/constants/index.js +1 -0
- package/lib/helpers/materialized-reports/index.d.ts +2 -0
- package/lib/helpers/materialized-reports/index.js +2 -0
- package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +307 -0
- package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +1003 -0
- package/lib/helpers/materialized-reports/materialized-reports-read-helpers.d.ts +0 -30
- package/lib/helpers/materialized-reports/materialized-reports-read-helpers.js +0 -76
- package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +59 -0
- package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +723 -0
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +66 -8
- package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +326 -40
- package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +18 -2
- package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +46 -37
- package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +119 -238
- package/lib/helpers/types/index.d.ts +1 -0
- package/lib/helpers/types/index.js +1 -0
- package/lib/helpers/types/materialized-reports-apis.d.ts +46 -17
- package/lib/helpers/types/report-calendar.d.ts +20 -0
- package/lib/helpers/types/report-calendar.js +2 -0
- package/lib/schemas/models/index.d.ts +1 -0
- package/lib/schemas/models/index.js +1 -0
- package/lib/schemas/models/materialized_credit_bills.d.ts +337 -0
- package/lib/schemas/models/materialized_credit_bills.js +268 -0
- package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +20 -6
- package/lib/schemas/models/materialized_tenant_reports_iterations.js +14 -1
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +37 -165
- package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +40 -98
- package/lib/schemas/types/index.d.ts +1 -0
- package/lib/schemas/types/index.js +1 -0
- package/lib/schemas/types/materialized_credit_bills.d.ts +139 -0
- package/lib/schemas/types/materialized_credit_bills.js +2 -0
- package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +32 -77
- package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +715 -0
- package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.d.ts +1 -0
- package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +262 -0
- package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +9 -0
- package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +23 -24
- package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +327 -22
- package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +27 -2
- package/lib/tests/materialized-reports/tenant-sales-overview-formatter.test.js +12 -27
- package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +79 -146
- package/package.json +1 -1
- package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.js +0 -100
- /package/{lib/tests/materialized-reports/materialized-reports-read-helpers.test.d.ts → esm/helpers/types/report-calendar.js} +0 -0
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import { MATERIALIZED_REPORT_SCOPE_ENUM } from '../../constants/MATERIALIZED_REPORTS';
|
|
2
2
|
import { IMaterializedTenantSalesOverviewReport } from '../../schemas/types/materialized_tenant_sales_overview_reports';
|
|
3
|
-
import { IGetMaterializedReportBody, IGetMaterializedReportScopeGroup } from '../types/materialized-reports-apis';
|
|
4
3
|
/**
|
|
5
4
|
* Read-side helpers for materialized-report documents — the frontend-facing
|
|
6
5
|
* half of the query story (see `MATERIALIZED_REPORTS.md` "Time scopes").
|
|
@@ -77,32 +76,3 @@ export declare function getMaterializedScopeSpan(scope_context: MATERIALIZED_REP
|
|
|
77
76
|
* nothing (absence = zero).
|
|
78
77
|
*/
|
|
79
78
|
export declare function filterMaterializedTenantSalesOverviewReportsByScopeFields(docs: IMaterializedTenantSalesOverviewReport[], scopeFields: string[]): IMaterializedTenantSalesOverviewReport[] | null;
|
|
80
|
-
/**
|
|
81
|
-
* Builds the canonical body of a materialized reports READ call —
|
|
82
|
-
* `{ tenants, scope_groups }`, the shared shape of every report endpoint.
|
|
83
|
-
*
|
|
84
|
-
* Normalization (invalid input → `null`, never throws):
|
|
85
|
-
* - tenants are trimmed + deduped (whitespace-only tenants are rejected);
|
|
86
|
-
* - each group's `scope_context` is RESOLVED to its server default
|
|
87
|
-
* (`localDate`) BEFORE bucketing, so an omitted context and an explicit
|
|
88
|
-
* `localDate` group merge into ONE — never two semantically identical
|
|
89
|
-
* groups (the backend merges branch rows with `$sum`, so overlapping
|
|
90
|
-
* groups would double-count every shared document);
|
|
91
|
-
* - values are trimmed + deduped + sorted (lexicographic order is
|
|
92
|
-
* chronological for the fixed-width period formats; hour labels are
|
|
93
|
-
* `$in`-matched, so their order is cosmetic only);
|
|
94
|
-
* - groups with the same context are merged (values unioned); every emitted
|
|
95
|
-
* group carries an explicit `scope_context`.
|
|
96
|
-
*
|
|
97
|
-
* The body carries NO response-mode switch: every read is answered with
|
|
98
|
-
* the aggregated record(s). Per group, `scope_field.length` only picks the
|
|
99
|
-
* backend's query strategy (a single value → direct equality; multiple →
|
|
100
|
-
* `$in`).
|
|
101
|
-
*
|
|
102
|
-
* Returns `null` (never throws) for invalid input — `null` means the caller
|
|
103
|
-
* passed invalid data.
|
|
104
|
-
*/
|
|
105
|
-
export declare function buildMaterializedReportReadBody(input: {
|
|
106
|
-
tenants: string[];
|
|
107
|
-
groups: IGetMaterializedReportScopeGroup[];
|
|
108
|
-
}): IGetMaterializedReportBody | null;
|
|
@@ -5,7 +5,6 @@ exports.getMaterializedHourWindowScopeFields = getMaterializedHourWindowScopeFie
|
|
|
5
5
|
exports.getMaterializedHourScopeSpan = getMaterializedHourScopeSpan;
|
|
6
6
|
exports.getMaterializedScopeSpan = getMaterializedScopeSpan;
|
|
7
7
|
exports.filterMaterializedTenantSalesOverviewReportsByScopeFields = filterMaterializedTenantSalesOverviewReportsByScopeFields;
|
|
8
|
-
exports.buildMaterializedReportReadBody = buildMaterializedReportReadBody;
|
|
9
8
|
const MATERIALIZED_REPORTS_1 = require("../../constants/MATERIALIZED_REPORTS");
|
|
10
9
|
const scope_helpers_1 = require("./scope-helpers");
|
|
11
10
|
/**
|
|
@@ -157,78 +156,3 @@ function filterMaterializedTenantSalesOverviewReportsByScopeFields(docs, scopeFi
|
|
|
157
156
|
const wanted = new Set(scopeFields);
|
|
158
157
|
return docs.filter((doc) => doc != null && wanted.has(doc.scope_field));
|
|
159
158
|
}
|
|
160
|
-
/**
|
|
161
|
-
* Builds the canonical body of a materialized reports READ call —
|
|
162
|
-
* `{ tenants, scope_groups }`, the shared shape of every report endpoint.
|
|
163
|
-
*
|
|
164
|
-
* Normalization (invalid input → `null`, never throws):
|
|
165
|
-
* - tenants are trimmed + deduped (whitespace-only tenants are rejected);
|
|
166
|
-
* - each group's `scope_context` is RESOLVED to its server default
|
|
167
|
-
* (`localDate`) BEFORE bucketing, so an omitted context and an explicit
|
|
168
|
-
* `localDate` group merge into ONE — never two semantically identical
|
|
169
|
-
* groups (the backend merges branch rows with `$sum`, so overlapping
|
|
170
|
-
* groups would double-count every shared document);
|
|
171
|
-
* - values are trimmed + deduped + sorted (lexicographic order is
|
|
172
|
-
* chronological for the fixed-width period formats; hour labels are
|
|
173
|
-
* `$in`-matched, so their order is cosmetic only);
|
|
174
|
-
* - groups with the same context are merged (values unioned); every emitted
|
|
175
|
-
* group carries an explicit `scope_context`.
|
|
176
|
-
*
|
|
177
|
-
* The body carries NO response-mode switch: every read is answered with
|
|
178
|
-
* the aggregated record(s). Per group, `scope_field.length` only picks the
|
|
179
|
-
* backend's query strategy (a single value → direct equality; multiple →
|
|
180
|
-
* `$in`).
|
|
181
|
-
*
|
|
182
|
-
* Returns `null` (never throws) for invalid input — `null` means the caller
|
|
183
|
-
* passed invalid data.
|
|
184
|
-
*/
|
|
185
|
-
function buildMaterializedReportReadBody(input) {
|
|
186
|
-
if (input == null)
|
|
187
|
-
return null;
|
|
188
|
-
const { tenants, groups } = input;
|
|
189
|
-
if (!Array.isArray(tenants) || tenants.length === 0)
|
|
190
|
-
return null;
|
|
191
|
-
if (tenants.some((tenantId) => typeof tenantId !== 'string' || tenantId.trim() === '')) {
|
|
192
|
-
return null;
|
|
193
|
-
}
|
|
194
|
-
if (!Array.isArray(groups) || groups.length === 0)
|
|
195
|
-
return null;
|
|
196
|
-
const buckets = new Map();
|
|
197
|
-
for (const group of groups) {
|
|
198
|
-
if (group == null || !Array.isArray(group.scope_field) || group.scope_field.length === 0)
|
|
199
|
-
return null;
|
|
200
|
-
const { scope_context } = group;
|
|
201
|
-
if (scope_context != null && !MATERIALIZED_REPORTS_1.ALL_MATERIALIZED_REPORT_SCOPES.includes(scope_context))
|
|
202
|
-
return null;
|
|
203
|
-
// Resolve the context default BEFORE bucketing — an omitted context IS
|
|
204
|
-
// `localDate` (the server default), so it must merge with an explicit
|
|
205
|
-
// `localDate` group instead of surviving as a second, overlapping group.
|
|
206
|
-
const context = scope_context ?? MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE;
|
|
207
|
-
let values = buckets.get(context);
|
|
208
|
-
if (values == null) {
|
|
209
|
-
values = new Set();
|
|
210
|
-
buckets.set(context, values);
|
|
211
|
-
}
|
|
212
|
-
for (const field of group.scope_field) {
|
|
213
|
-
if (typeof field !== 'string')
|
|
214
|
-
return null;
|
|
215
|
-
const trimmed = field.trim();
|
|
216
|
-
if (trimmed === '')
|
|
217
|
-
return null;
|
|
218
|
-
values.add(trimmed);
|
|
219
|
-
}
|
|
220
|
-
}
|
|
221
|
-
const scope_groups = [];
|
|
222
|
-
for (const [scope_context, values] of buckets) {
|
|
223
|
-
const scope_field = [...values].sort();
|
|
224
|
-
if (scope_field.length === 0)
|
|
225
|
-
continue;
|
|
226
|
-
scope_groups.push({ scope_context, scope_field });
|
|
227
|
-
}
|
|
228
|
-
if (scope_groups.length === 0)
|
|
229
|
-
return null;
|
|
230
|
-
return {
|
|
231
|
-
tenants: Array.from(new Set(tenants.map((tenantId) => tenantId.trim()))),
|
|
232
|
-
scope_groups,
|
|
233
|
-
};
|
|
234
|
-
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { IGetMaterializedReportScopeGroup } from '../types/materialized-reports-apis';
|
|
2
|
+
import { IReportCalendarSelection } from '../types/report-calendar';
|
|
3
|
+
/**
|
|
4
|
+
* Upper bound on the raw day span one selection may cover (~10 years).
|
|
5
|
+
* Bounds every date-walk expansion in the decoder; read services surface an
|
|
6
|
+
* over-bound selection as `selectionTooLarge` (400 "narrow the selection")
|
|
7
|
+
* BEFORE any decoding work happens.
|
|
8
|
+
*/
|
|
9
|
+
export declare const MATERIALIZED_REPORT_MAX_SELECTION_DAY_SPAN = 3660;
|
|
10
|
+
/**
|
|
11
|
+
* All day keys covered by a selection — keeps only days that match the
|
|
12
|
+
* active weekday refinement, so non-matching days never contribute to
|
|
13
|
+
* summaries, DateContext bounds, or requests.
|
|
14
|
+
*/
|
|
15
|
+
export declare const getDayKeysFromCalendarSelection: (selection: IReportCalendarSelection) => string[];
|
|
16
|
+
/**
|
|
17
|
+
* Whether an hour window `[fromHour, toHour)` fits one business day
|
|
18
|
+
* (06:00 → 06:00) — mirrors the toolkit's materialized window rule
|
|
19
|
+
* (`getMaterializedHourWindowScopeFields`): whole-hour buckets, end-exclusive
|
|
20
|
+
* (18 → 20 = hours 18, 19), midnight wrap allowed (22 → 2), but never a walk
|
|
21
|
+
* crossing the 06:00 business-morning boundary (4 → 8 is invalid). The
|
|
22
|
+
* calendar's time field uses this to disable unservable picker options, so an
|
|
23
|
+
* invalid window can never be composed for the read request.
|
|
24
|
+
*/
|
|
25
|
+
export declare const isValidBusinessHourWindow: (fromHour: number, toHour: number) => boolean;
|
|
26
|
+
export type TMaterializedReportSelectionValidation = {
|
|
27
|
+
ok: true;
|
|
28
|
+
} | {
|
|
29
|
+
ok: false;
|
|
30
|
+
reason: 'invalid' | 'tooLarge';
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* Validates the RAW calendar selection BEFORE any decoding work happens:
|
|
34
|
+
* - time keys, when present, must be whole `'HH:00'` hours (minute-level keys
|
|
35
|
+
* are malformed wire values — they must never silently truncate);
|
|
36
|
+
* - the weekday refinement must carry real `DAY_INDEX_ENUM` entries;
|
|
37
|
+
* - every date key (`rangeStart` / `rangeEnd` / `selectedDates` / week-start
|
|
38
|
+
* picks) must be a REAL `'YYYY-MM-DD'` calendar date;
|
|
39
|
+
* - `selectedPeriods` picks must match their view's period grammar and
|
|
40
|
+
* semantics (months 01–12, ISO weeks within the year's week count,
|
|
41
|
+
* quarters Q1–Q4, semesters S1–S2, four-digit years);
|
|
42
|
+
* - contiguous range walks may not cover more than
|
|
43
|
+
* `MATERIALIZED_REPORT_MAX_SELECTION_DAY_SPAN` days, and discrete picks may
|
|
44
|
+
* not exceed that count — both are `tooLarge` (narrow the selection).
|
|
45
|
+
*
|
|
46
|
+
* The decoder calls this first and maps BOTH failures to `null`; read
|
|
47
|
+
* services call it (via their read parser) to answer a clean 400 before the
|
|
48
|
+
* decoder is ever entered — a malformed request can never reach a date walk.
|
|
49
|
+
*/
|
|
50
|
+
export declare const validateMaterializedReportSelectionInput: (selection: IReportCalendarSelection) => TMaterializedReportSelectionValidation;
|
|
51
|
+
/**
|
|
52
|
+
* Maps a committed calendar selection to the exact `scope_groups` of the
|
|
53
|
+
* overview read — the PUBLIC decoder: it validates the raw selection
|
|
54
|
+
* (`validateMaterializedReportSelectionInput`) first and NEVER throws.
|
|
55
|
+
* Returns `null` when the selection cannot be served (LIVE without a
|
|
56
|
+
* committed day, a malformed/oversized/empty selection, or unservable
|
|
57
|
+
* refinement input).
|
|
58
|
+
*/
|
|
59
|
+
export declare const buildMaterializedReportScopeGroupsFromSelection: (selection: IReportCalendarSelection) => IGetMaterializedReportScopeGroup[] | null;
|