@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.
Files changed (68) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +33 -0
  2. package/esm/constants/REPORT_CALENDAR.js +47 -0
  3. package/esm/constants/index.js +1 -0
  4. package/esm/helpers/materialized-reports/index.js +2 -0
  5. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +982 -0
  6. package/esm/helpers/materialized-reports/materialized-reports-read-helpers.js +1 -76
  7. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +716 -0
  8. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +327 -41
  9. package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  10. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +118 -235
  11. package/esm/helpers/types/index.js +1 -0
  12. package/esm/schemas/models/index.js +1 -0
  13. package/esm/schemas/models/materialized_credit_bills.js +265 -0
  14. package/esm/schemas/models/materialized_tenant_reports_iterations.js +13 -0
  15. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +39 -97
  16. package/esm/schemas/types/index.js +1 -0
  17. package/esm/schemas/types/materialized_credit_bills.js +1 -0
  18. package/lib/constants/MATERIALIZED_REPORTS.d.ts +28 -2
  19. package/lib/constants/MATERIALIZED_REPORTS.js +34 -1
  20. package/lib/constants/REPORT_CALENDAR.d.ts +31 -0
  21. package/lib/constants/REPORT_CALENDAR.js +50 -0
  22. package/lib/constants/index.d.ts +1 -0
  23. package/lib/constants/index.js +1 -0
  24. package/lib/helpers/materialized-reports/index.d.ts +2 -0
  25. package/lib/helpers/materialized-reports/index.js +2 -0
  26. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +307 -0
  27. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +1003 -0
  28. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.d.ts +0 -30
  29. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.js +0 -76
  30. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +59 -0
  31. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +723 -0
  32. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +66 -8
  33. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +326 -40
  34. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +18 -2
  35. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  36. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +46 -37
  37. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +119 -238
  38. package/lib/helpers/types/index.d.ts +1 -0
  39. package/lib/helpers/types/index.js +1 -0
  40. package/lib/helpers/types/materialized-reports-apis.d.ts +46 -17
  41. package/lib/helpers/types/report-calendar.d.ts +20 -0
  42. package/lib/helpers/types/report-calendar.js +2 -0
  43. package/lib/schemas/models/index.d.ts +1 -0
  44. package/lib/schemas/models/index.js +1 -0
  45. package/lib/schemas/models/materialized_credit_bills.d.ts +337 -0
  46. package/lib/schemas/models/materialized_credit_bills.js +268 -0
  47. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +20 -6
  48. package/lib/schemas/models/materialized_tenant_reports_iterations.js +14 -1
  49. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +37 -165
  50. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +40 -98
  51. package/lib/schemas/types/index.d.ts +1 -0
  52. package/lib/schemas/types/index.js +1 -0
  53. package/lib/schemas/types/materialized_credit_bills.d.ts +139 -0
  54. package/lib/schemas/types/materialized_credit_bills.js +2 -0
  55. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +32 -77
  56. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.d.ts +1 -0
  57. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +715 -0
  58. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.d.ts +1 -0
  59. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +262 -0
  60. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +9 -0
  61. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +23 -24
  62. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +327 -22
  63. package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +27 -2
  64. package/lib/tests/materialized-reports/tenant-sales-overview-formatter.test.js +12 -27
  65. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +79 -146
  66. package/package.json +1 -1
  67. package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.js +0 -100
  68. /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;