@managesome/eposmatic-toolkit 0.4.5 → 0.4.7

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 (27) hide show
  1. package/esm/constants/REPORT_CALENDAR.js +47 -0
  2. package/esm/constants/index.js +1 -0
  3. package/esm/helpers/materialized-reports/index.js +1 -0
  4. package/esm/helpers/materialized-reports/materialized-reports-read-helpers.js +1 -76
  5. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +473 -0
  6. package/esm/helpers/types/index.js +1 -0
  7. package/lib/constants/REPORT_CALENDAR.d.ts +31 -0
  8. package/lib/constants/REPORT_CALENDAR.js +50 -0
  9. package/lib/constants/index.d.ts +1 -0
  10. package/lib/constants/index.js +1 -0
  11. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  12. package/lib/helpers/materialized-reports/index.js +1 -0
  13. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.d.ts +0 -30
  14. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.js +0 -76
  15. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +25 -0
  16. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +479 -0
  17. package/lib/helpers/types/index.d.ts +1 -0
  18. package/lib/helpers/types/index.js +1 -0
  19. package/lib/helpers/types/materialized-reports-apis.d.ts +14 -12
  20. package/lib/helpers/types/report-calendar.d.ts +20 -0
  21. package/lib/helpers/types/report-calendar.js +2 -0
  22. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +3 -3
  23. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.d.ts +1 -0
  24. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +166 -0
  25. package/package.json +1 -1
  26. package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.js +0 -100
  27. /package/{lib/tests/materialized-reports/materialized-reports-read-helpers.test.d.ts → esm/helpers/types/report-calendar.js} +0 -0
@@ -0,0 +1,50 @@
1
+ "use strict";
2
+ // Report Calendar selection model constants (see the Report Calendar
3
+ // concept doc §5). The calendar produces an `IReportCalendarSelection`;
4
+ // every materialized report read API decodes it server-side with the
5
+ // toolkit's `buildMaterializedReportScopeGroupsFromSelection` — the
6
+ // selection model is the SINGLE shared contract between the calendar UI and
7
+ // the read services.
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.MATERIALIZED_REPORT_SELECTION_SPEC_VERSION = exports.ALL_CALENDAR_VIEW_MODE_ENUMS = exports.CALENDAR_VIEW_MODE_ENUM = exports.ALL_CALENDAR_MODE_ENUMS = exports.CALENDAR_MODE_ENUM = void 0;
10
+ var CALENDAR_MODE_ENUM;
11
+ (function (CALENDAR_MODE_ENUM) {
12
+ CALENDAR_MODE_ENUM["LIVE"] = "LIVE";
13
+ CALENDAR_MODE_ENUM["HISTORICAL"] = "HISTORICAL";
14
+ })(CALENDAR_MODE_ENUM || (exports.CALENDAR_MODE_ENUM = CALENDAR_MODE_ENUM = {}));
15
+ exports.ALL_CALENDAR_MODE_ENUMS = Object.values(CALENDAR_MODE_ENUM);
16
+ // Historical selection modes (doc §4.2) — default = DATE_RANGE.
17
+ // Every materialized scope context is selectable: day/hour ranges, calendar
18
+ // weeks (Sun–Sat), ISO weeks of year (Mon–Sun), months, quarters, semesters
19
+ // and years — contiguous ranges plus discrete (DIFFERENT_*) picks.
20
+ // Two refinements apply to ANY historical view (they are modifiers, not
21
+ // modes): the time-of-day window (hour-level, own `localHour`
22
+ // materialization) and the weekday filter (`day_index`, applied by the
23
+ // decoder).
24
+ var CALENDAR_VIEW_MODE_ENUM;
25
+ (function (CALENDAR_VIEW_MODE_ENUM) {
26
+ CALENDAR_VIEW_MODE_ENUM["DATE_RANGE"] = "DATE_RANGE";
27
+ CALENDAR_VIEW_MODE_ENUM["MULTI_DATE"] = "MULTI_DATE";
28
+ CALENDAR_VIEW_MODE_ENUM["DATE_RANGE_TIME_WINDOW"] = "DATE_RANGE_TIME_WINDOW";
29
+ CALENDAR_VIEW_MODE_ENUM["WEEK"] = "WEEK";
30
+ CALENDAR_VIEW_MODE_ENUM["DIFFERENT_WEEKS"] = "DIFFERENT_WEEKS";
31
+ CALENDAR_VIEW_MODE_ENUM["WEEK_OF_YEAR"] = "WEEK_OF_YEAR";
32
+ CALENDAR_VIEW_MODE_ENUM["DIFFERENT_WEEKS_OF_YEAR"] = "DIFFERENT_WEEKS_OF_YEAR";
33
+ CALENDAR_VIEW_MODE_ENUM["MONTH"] = "MONTH";
34
+ CALENDAR_VIEW_MODE_ENUM["DIFFERENT_MONTHS"] = "DIFFERENT_MONTHS";
35
+ CALENDAR_VIEW_MODE_ENUM["QUARTER"] = "QUARTER";
36
+ CALENDAR_VIEW_MODE_ENUM["DIFFERENT_QUARTERS"] = "DIFFERENT_QUARTERS";
37
+ CALENDAR_VIEW_MODE_ENUM["SEMESTER"] = "SEMESTER";
38
+ CALENDAR_VIEW_MODE_ENUM["DIFFERENT_SEMESTERS"] = "DIFFERENT_SEMESTERS";
39
+ CALENDAR_VIEW_MODE_ENUM["YEAR"] = "YEAR";
40
+ CALENDAR_VIEW_MODE_ENUM["DIFFERENT_YEARS"] = "DIFFERENT_YEARS";
41
+ })(CALENDAR_VIEW_MODE_ENUM || (exports.CALENDAR_VIEW_MODE_ENUM = CALENDAR_VIEW_MODE_ENUM = {}));
42
+ exports.ALL_CALENDAR_VIEW_MODE_ENUMS = Object.values(CALENDAR_VIEW_MODE_ENUM);
43
+ /**
44
+ * Version of the `IReportCalendarSelection` spec carried by a materialized
45
+ * report READ body (`selection.spec_version`). Bump on any meaning-changing
46
+ * reshape of the selection model — the read API rejects unknown versions
47
+ * with a 400, so rolling deploys (old frontend → new backend) fail loudly
48
+ * instead of decoding a stale shape.
49
+ */
50
+ exports.MATERIALIZED_REPORT_SELECTION_SPEC_VERSION = 1;
@@ -11,6 +11,7 @@ export * from './MATERIALIZED_REPORTS';
11
11
  export * from './NOTIFICATIONS';
12
12
  export * from './ORDER';
13
13
  export * from './PRA_ENUMS';
14
+ export * from './REPORT_CALENDAR';
14
15
  export * from './REPORT_WEBVIEW';
15
16
  export * from './RFQ_GO';
16
17
  export * from './SMARTPAY_ENUMS';
@@ -27,6 +27,7 @@ __exportStar(require("./MATERIALIZED_REPORTS"), exports);
27
27
  __exportStar(require("./NOTIFICATIONS"), exports);
28
28
  __exportStar(require("./ORDER"), exports);
29
29
  __exportStar(require("./PRA_ENUMS"), exports);
30
+ __exportStar(require("./REPORT_CALENDAR"), exports);
30
31
  __exportStar(require("./REPORT_WEBVIEW"), exports);
31
32
  __exportStar(require("./RFQ_GO"), exports);
32
33
  __exportStar(require("./SMARTPAY_ENUMS"), exports);
@@ -1,6 +1,7 @@
1
1
  export * from './key-helpers';
2
2
  export * from './materialized-reports-read-helpers';
3
3
  export * from './materialized-reports-scope-group-helpers';
4
+ export * from './materialized-reports-selection-helpers';
4
5
  export * from './materialized-tenant-reports-iterations-helpers';
5
6
  export * from './scope-helpers';
6
7
  export * from './tenant-sales-overview-close-day-helpers';
@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
17
17
  __exportStar(require("./key-helpers"), exports);
18
18
  __exportStar(require("./materialized-reports-read-helpers"), exports);
19
19
  __exportStar(require("./materialized-reports-scope-group-helpers"), exports);
20
+ __exportStar(require("./materialized-reports-selection-helpers"), exports);
20
21
  __exportStar(require("./materialized-tenant-reports-iterations-helpers"), exports);
21
22
  __exportStar(require("./scope-helpers"), exports);
22
23
  __exportStar(require("./tenant-sales-overview-close-day-helpers"), exports);
@@ -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,25 @@
1
+ import { IGetMaterializedReportScopeGroup } from '../types/materialized-reports-apis';
2
+ import { IReportCalendarSelection } from '../types/report-calendar';
3
+ /**
4
+ * All day keys covered by a selection — keeps only days that match the
5
+ * active weekday refinement, so non-matching days never contribute to
6
+ * summaries, DateContext bounds, or requests.
7
+ */
8
+ export declare const getDayKeysFromCalendarSelection: (selection: IReportCalendarSelection) => string[];
9
+ /**
10
+ * Whether an hour window `[fromHour, toHour)` fits one business day
11
+ * (06:00 → 06:00) — mirrors the toolkit's materialized window rule
12
+ * (`getMaterializedHourWindowScopeFields`): whole-hour buckets, end-exclusive
13
+ * (18 → 20 = hours 18, 19), midnight wrap allowed (22 → 2), but never a walk
14
+ * crossing the 06:00 business-morning boundary (4 → 8 is invalid). The
15
+ * calendar's time field uses this to disable unservable picker options, so an
16
+ * invalid window can never be composed for the read request.
17
+ */
18
+ export declare const isValidBusinessHourWindow: (fromHour: number, toHour: number) => boolean;
19
+ /**
20
+ * Maps a committed calendar selection to the exact `scope_groups` of the
21
+ * overview read. Returns `null` when the selection cannot be served (LIVE
22
+ * without a committed day, a malformed/empty selection, or unservable
23
+ * refinement input).
24
+ */
25
+ export declare const buildMaterializedReportScopeGroupsFromSelection: (selection: IReportCalendarSelection) => IGetMaterializedReportScopeGroup[] | null;