@managesome/eposmatic-toolkit 0.4.53 → 0.4.55

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 (82) hide show
  1. package/esm/helpers/materialized-reports/index.js +1 -0
  2. package/esm/helpers/materialized-reports/materialized-delivery-wipe-targets.js +18 -0
  3. package/esm/helpers/materialized-reports/report-platform/definition.js +508 -0
  4. package/esm/helpers/materialized-reports/report-platform/index.js +4 -0
  5. package/esm/helpers/materialized-reports/report-platform/lifecycle/budget.js +27 -0
  6. package/esm/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +12 -0
  7. package/esm/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +121 -0
  8. package/esm/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +14 -0
  9. package/esm/helpers/materialized-reports/report-platform/lifecycle/index.js +8 -0
  10. package/esm/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +10 -0
  11. package/esm/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +42 -0
  12. package/esm/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +28 -0
  13. package/esm/helpers/materialized-reports/report-platform/lifecycle/top-n.js +24 -0
  14. package/esm/helpers/materialized-reports/report-platform/registry.js +23 -0
  15. package/esm/helpers/materialized-reports/report-platform/validate-report-registry.js +214 -0
  16. package/esm/schemas/models/index.js +1 -0
  17. package/esm/schemas/models/tenant_dialer_events.js +133 -0
  18. package/esm/schemas/types/index.js +1 -0
  19. package/esm/schemas/types/tenant_dialer_events.js +1 -0
  20. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  21. package/lib/helpers/materialized-reports/index.js +1 -0
  22. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.d.ts +1 -0
  23. package/lib/helpers/materialized-reports/materialized-delivery-wipe-targets.js +19 -0
  24. package/lib/helpers/materialized-reports/report-platform/definition.d.ts +133 -0
  25. package/lib/helpers/materialized-reports/report-platform/definition.js +511 -0
  26. package/lib/helpers/materialized-reports/report-platform/index.d.ts +4 -0
  27. package/lib/helpers/materialized-reports/report-platform/index.js +20 -0
  28. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.d.ts +8 -0
  29. package/lib/helpers/materialized-reports/report-platform/lifecycle/budget.js +31 -0
  30. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.d.ts +8 -0
  31. package/lib/helpers/materialized-reports/report-platform/lifecycle/cap-metadata.js +16 -0
  32. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.d.ts +40 -0
  33. package/lib/helpers/materialized-reports/report-platform/lifecycle/entry-pages.js +130 -0
  34. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.d.ts +22 -0
  35. package/lib/helpers/materialized-reports/report-platform/lifecycle/flat-projection.js +17 -0
  36. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.d.ts +8 -0
  37. package/lib/helpers/materialized-reports/report-platform/lifecycle/index.js +24 -0
  38. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.d.ts +13 -0
  39. package/lib/helpers/materialized-reports/report-platform/lifecycle/iteration-row.js +13 -0
  40. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.d.ts +20 -0
  41. package/lib/helpers/materialized-reports/report-platform/lifecycle/run-stats.js +47 -0
  42. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.d.ts +13 -0
  43. package/lib/helpers/materialized-reports/report-platform/lifecycle/scope-refs.js +31 -0
  44. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.d.ts +16 -0
  45. package/lib/helpers/materialized-reports/report-platform/lifecycle/top-n.js +29 -0
  46. package/lib/helpers/materialized-reports/report-platform/registry.d.ts +13 -0
  47. package/lib/helpers/materialized-reports/report-platform/registry.js +31 -0
  48. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.d.ts +20 -0
  49. package/lib/helpers/materialized-reports/report-platform/validate-report-registry.js +218 -0
  50. package/lib/schemas/models/index.d.ts +1 -0
  51. package/lib/schemas/models/index.js +1 -0
  52. package/lib/schemas/models/tenant-activity-logs.d.ts +3 -3
  53. package/lib/schemas/models/tenant_dialer_events.d.ts +130 -0
  54. package/lib/schemas/models/tenant_dialer_events.js +136 -0
  55. package/lib/schemas/models/warehouse-activity-logs.d.ts +3 -3
  56. package/lib/schemas/types/index.d.ts +1 -0
  57. package/lib/schemas/types/index.js +1 -0
  58. package/lib/schemas/types/tenant_dialer_events.d.ts +35 -0
  59. package/lib/schemas/types/tenant_dialer_events.js +2 -0
  60. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.d.ts +1 -0
  61. package/lib/tests/materialized-reports/characterization/delivery.characterization.test.js +229 -0
  62. package/lib/tests/materialized-reports/characterization/discount.characterization.test.d.ts +1 -0
  63. package/lib/tests/materialized-reports/characterization/discount.characterization.test.js +99 -0
  64. package/lib/tests/materialized-reports/characterization/fixtures.d.ts +30 -0
  65. package/lib/tests/materialized-reports/characterization/fixtures.js +402 -0
  66. package/lib/tests/materialized-reports/characterization/golden.d.ts +18 -0
  67. package/lib/tests/materialized-reports/characterization/golden.js +127 -0
  68. package/lib/tests/materialized-reports/characterization/overview.characterization.test.d.ts +1 -0
  69. package/lib/tests/materialized-reports/characterization/overview.characterization.test.js +69 -0
  70. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.d.ts +1 -0
  71. package/lib/tests/materialized-reports/characterization/prep-time.characterization.test.js +102 -0
  72. package/lib/tests/materialized-reports/materialized-wipe-tooling.test.d.ts +1 -0
  73. package/lib/tests/materialized-reports/materialized-wipe-tooling.test.js +37 -0
  74. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.d.ts +1 -0
  75. package/lib/tests/materialized-reports/report-platform/lifecycle-primitives.test.js +177 -0
  76. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.d.ts +1 -0
  77. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.js +214 -0
  78. package/lib/tests/materialized-reports/report-platform/registry-validation.test.d.ts +1 -0
  79. package/lib/tests/materialized-reports/report-platform/registry-validation.test.js +103 -0
  80. package/lib/tests/tenant-dialer-events-schema.test.d.ts +1 -0
  81. package/lib/tests/tenant-dialer-events-schema.test.js +191 -0
  82. package/package.json +4 -2
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ __exportStar(require("./definition"), exports);
18
+ __exportStar(require("./registry"), exports);
19
+ __exportStar(require("./validate-report-registry"), exports);
20
+ __exportStar(require("./lifecycle"), exports);
@@ -0,0 +1,8 @@
1
+ import type { IReportDefinition } from '../definition';
2
+ /** PHASE 2 — per-collection budget lookup + assertion. */
3
+ export type TReportBudgetKind = 'report' | 'entries' | 'side';
4
+ export declare function getReportCollectionBudget(definition: Pick<IReportDefinition, 'budgets' | 'report' | 'entries' | 'sideCollections'>, kind: TReportBudgetKind, collectionName?: string): number | null;
5
+ export declare function assertReportDocumentBudget(definition: Pick<IReportDefinition, 'key' | 'budgets' | 'report' | 'entries' | 'sideCollections'>, kind: TReportBudgetKind, document: unknown, options?: {
6
+ collectionName?: string;
7
+ label?: string;
8
+ }): void;
@@ -0,0 +1,31 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.getReportCollectionBudget = getReportCollectionBudget;
4
+ exports.assertReportDocumentBudget = assertReportDocumentBudget;
5
+ const materialized_document_size_1 = require("../../materialized-document-size");
6
+ function getReportCollectionBudget(definition, kind, collectionName) {
7
+ if (kind === 'report')
8
+ return definition.budgets[definition.report.name] ?? null;
9
+ if (kind === 'entries') {
10
+ if (definition.entries == null)
11
+ return null;
12
+ return definition.budgets[definition.entries.name] ?? null;
13
+ }
14
+ if (collectionName == null)
15
+ return null;
16
+ if (!definition.sideCollections.some((collection) => collection.name === collectionName)) {
17
+ return null;
18
+ }
19
+ return definition.budgets[collectionName] ?? null;
20
+ }
21
+ function assertReportDocumentBudget(definition, kind, document, options = {}) {
22
+ const budget = getReportCollectionBudget(definition, kind, options.collectionName);
23
+ if (budget == null) {
24
+ throw new Error(`assertReportDocumentBudget: ${definition.key} has no budget for ${kind}${options.collectionName == null ? '' : `:${options.collectionName}`}`);
25
+ }
26
+ (0, materialized_document_size_1.assertMaterializedDocumentSize)(document, {
27
+ collection: options.collectionName ?? (kind === 'report' ? definition.report.name : definition.entries?.name),
28
+ label: options.label ?? definition.key,
29
+ maxBytes: budget,
30
+ });
31
+ }
@@ -0,0 +1,8 @@
1
+ /** PHASE 2 — generic suppression/cap metadata merge. */
2
+ export interface IReportCapMetadata {
3
+ cappedCellCount: number;
4
+ cappedOrderCount: number;
5
+ exact: boolean;
6
+ }
7
+ export declare const EMPTY_REPORT_CAP_METADATA: IReportCapMetadata;
8
+ export declare function mergeReportCapMetadata(left: IReportCapMetadata | null | undefined, right: IReportCapMetadata | null | undefined): IReportCapMetadata;
@@ -0,0 +1,16 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.EMPTY_REPORT_CAP_METADATA = void 0;
4
+ exports.mergeReportCapMetadata = mergeReportCapMetadata;
5
+ exports.EMPTY_REPORT_CAP_METADATA = {
6
+ cappedCellCount: 0,
7
+ cappedOrderCount: 0,
8
+ exact: true,
9
+ };
10
+ function mergeReportCapMetadata(left, right) {
11
+ return {
12
+ cappedCellCount: Number(left?.cappedCellCount ?? 0) + Number(right?.cappedCellCount ?? 0),
13
+ cappedOrderCount: Number(left?.cappedOrderCount ?? 0) + Number(right?.cappedOrderCount ?? 0),
14
+ exact: (left?.exact ?? true) && (right?.exact ?? true),
15
+ };
16
+ }
@@ -0,0 +1,40 @@
1
+ import { type IReportDefinition } from '../definition';
2
+ /**
3
+ * PHASE 2 — generic entry page identity + deterministic #N splitter.
4
+ *
5
+ * The splitter is a generic transcription of the CURRENT Delivery splitter. It
6
+ * is not wired into any writer; the equivalence test runs both implementations
7
+ * over the same compiled Delivery page and requires byte-identical output.
8
+ */
9
+ export declare const ENTRY_PAGE_ALL = "all";
10
+ export declare function isEntryPageScope(scope: unknown): boolean;
11
+ /**
12
+ * `page` value for one entry scope, matching Discounts and Delivery:
13
+ * day/hour scopes are already one day -> `all`; period scopes use the SOURCE day.
14
+ * Reports with `ONE_PER_SCOPE` or `NONE` return null.
15
+ */
16
+ export declare function resolveEntryPageForScope(definition: Pick<IReportDefinition, 'entryStorage'>, scopeContext: unknown, sourceLocalDate: string): string | null;
17
+ export declare function entryPageBase(page: unknown): string;
18
+ export declare function isEntryPageForSourceDay(definition: Pick<IReportDefinition, 'entryStorage'>, scopeContext: unknown, page: unknown, sourceLocalDate: string): boolean;
19
+ export declare function buildEntrySubPage(basePage: string, index: number): string;
20
+ export interface IEntryPageSections {
21
+ [key: string]: {
22
+ rows: unknown[];
23
+ } | null | undefined;
24
+ }
25
+ export interface IEntryPageSplitSpec<TDocument> {
26
+ document: TDocument;
27
+ maxBytes: number;
28
+ /** `page` of the document (may already carry a `#N` suffix). */
29
+ pageOf: (document: TDocument) => string;
30
+ /** The itemized sections; null/undefined means "nothing to split". */
31
+ sectionsOf: (document: TDocument) => IEntryPageSections | null;
32
+ /** Rebuild with a new page and sections; all other fields are preserved. */
33
+ rebuild: (document: TDocument, page: string, sections: IEntryPageSections) => TDocument;
34
+ scopeLabel?: (document: TDocument) => string;
35
+ }
36
+ /**
37
+ * Splits one oversized entry page into deterministic `page#0`, `page#1`, ...
38
+ * chunks. A page that fits keeps its original identity.
39
+ */
40
+ export declare function splitEntryPage<TDocument>(spec: IEntryPageSplitSpec<TDocument>): TDocument[];
@@ -0,0 +1,130 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ENTRY_PAGE_ALL = void 0;
4
+ exports.isEntryPageScope = isEntryPageScope;
5
+ exports.resolveEntryPageForScope = resolveEntryPageForScope;
6
+ exports.entryPageBase = entryPageBase;
7
+ exports.isEntryPageForSourceDay = isEntryPageForSourceDay;
8
+ exports.buildEntrySubPage = buildEntrySubPage;
9
+ exports.splitEntryPage = splitEntryPage;
10
+ const MATERIALIZED_REPORTS_1 = require("../../../../constants/MATERIALIZED_REPORTS");
11
+ const materialized_document_size_1 = require("../../materialized-document-size");
12
+ const definition_1 = require("../definition");
13
+ /**
14
+ * PHASE 2 — generic entry page identity + deterministic #N splitter.
15
+ *
16
+ * The splitter is a generic transcription of the CURRENT Delivery splitter. It
17
+ * is not wired into any writer; the equivalence test runs both implementations
18
+ * over the same compiled Delivery page and requires byte-identical output.
19
+ */
20
+ exports.ENTRY_PAGE_ALL = 'all';
21
+ const SUB_PAGE_PATTERN = /^(.*)#(\d+)$/;
22
+ function isEntryPageScope(scope) {
23
+ return (String(scope) === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR ||
24
+ String(scope) === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE ||
25
+ String(scope) === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK ||
26
+ String(scope) === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_WEEK_OF_YEAR ||
27
+ String(scope) === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH);
28
+ }
29
+ /**
30
+ * `page` value for one entry scope, matching Discounts and Delivery:
31
+ * day/hour scopes are already one day -> `all`; period scopes use the SOURCE day.
32
+ * Reports with `ONE_PER_SCOPE` or `NONE` return null.
33
+ */
34
+ function resolveEntryPageForScope(definition, scopeContext, sourceLocalDate) {
35
+ if (definition.entryStorage !== definition_1.REPORT_ENTRY_STORAGE.PAGE_PER_SOURCE_DAY) {
36
+ return null;
37
+ }
38
+ if (!isEntryPageScope(scopeContext))
39
+ return null;
40
+ const scope = String(scopeContext);
41
+ if (scope === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR || scope === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE) {
42
+ return exports.ENTRY_PAGE_ALL;
43
+ }
44
+ return typeof sourceLocalDate === 'string' && sourceLocalDate !== '' ? sourceLocalDate : null;
45
+ }
46
+ function entryPageBase(page) {
47
+ const text = String(page ?? '');
48
+ const match = SUB_PAGE_PATTERN.exec(text);
49
+ return match == null ? text : match[1];
50
+ }
51
+ function isEntryPageForSourceDay(definition, scopeContext, page, sourceLocalDate) {
52
+ const base = resolveEntryPageForScope(definition, scopeContext, sourceLocalDate);
53
+ return base != null && entryPageBase(page) === base;
54
+ }
55
+ function buildEntrySubPage(basePage, index) {
56
+ return `${basePage}#${Math.max(0, Math.floor(index))}`;
57
+ }
58
+ /**
59
+ * Splits one oversized entry page into deterministic `page#0`, `page#1`, ...
60
+ * chunks. A page that fits keeps its original identity.
61
+ */
62
+ function splitEntryPage(spec) {
63
+ const { document, maxBytes } = spec;
64
+ if (document == null)
65
+ return [];
66
+ if ((0, materialized_document_size_1.materializedDocumentBsonBytes)(document) <= maxBytes)
67
+ return [document];
68
+ const sections = spec.sectionsOf(document);
69
+ if (sections == null)
70
+ return [document];
71
+ const basePage = entryPageBase(spec.pageOf(document));
72
+ const baseDoc = spec.rebuild(document, basePage, {});
73
+ const envelopeBytes = (0, materialized_document_size_1.materializedDocumentBsonBytes)(baseDoc);
74
+ const chunks = [];
75
+ let current = {};
76
+ let currentBytes = envelopeBytes;
77
+ let currentRows = 0;
78
+ const flush = () => {
79
+ if (currentRows > 0)
80
+ chunks.push(current);
81
+ current = {};
82
+ currentBytes = envelopeBytes;
83
+ currentRows = 0;
84
+ };
85
+ for (const key of Object.keys(sections)) {
86
+ for (const row of sections[key]?.rows ?? []) {
87
+ const rowBytes = (0, materialized_document_size_1.materializedDocumentBsonBytes)(row) + key.length + 24;
88
+ if (currentRows > 0 && currentBytes + rowBytes > maxBytes - 512)
89
+ flush();
90
+ if (current[key] == null)
91
+ current[key] = { rows: [] };
92
+ current[key].rows.push(row);
93
+ currentBytes += rowBytes;
94
+ currentRows += 1;
95
+ if (currentBytes > maxBytes) {
96
+ throw new Error(`Entry page ${spec.scopeLabel?.(document) ?? ''}:${basePage} ` +
97
+ 'cannot split below the budget (one row is too large)');
98
+ }
99
+ }
100
+ }
101
+ flush();
102
+ if (chunks.length <= 1) {
103
+ const allRows = [];
104
+ for (const key of Object.keys(sections)) {
105
+ for (const row of sections[key]?.rows ?? [])
106
+ allRows.push({ key, row });
107
+ }
108
+ if (allRows.length < 2) {
109
+ throw new Error(`Entry page ${spec.scopeLabel?.(document) ?? ''}:${basePage} ` + 'is over budget and has no splittable row');
110
+ }
111
+ const mid = Math.ceil(allRows.length / 2);
112
+ const toChunk = (rows) => {
113
+ const chunk = {};
114
+ for (const { key, row } of rows) {
115
+ if (chunk[key] == null)
116
+ chunk[key] = { rows: [] };
117
+ chunk[key].rows.push(row);
118
+ }
119
+ return chunk;
120
+ };
121
+ chunks.push(toChunk(allRows.slice(0, mid)), toChunk(allRows.slice(mid)));
122
+ }
123
+ return chunks.map((chunk, index) => {
124
+ const page = spec.rebuild(document, buildEntrySubPage(basePage, index), chunk);
125
+ if ((0, materialized_document_size_1.materializedDocumentBsonBytes)(page) > maxBytes) {
126
+ throw new Error(`Entry sub-page ${spec.scopeLabel?.(document) ?? ''}:${spec.pageOf(page)} ` + 'exceeds the entry-page budget');
127
+ }
128
+ return page;
129
+ });
130
+ }
@@ -0,0 +1,22 @@
1
+ import type { MATERIALIZED_REPORT_SCOPE_ENUM } from '../../../../constants/MATERIALIZED_REPORTS';
2
+ import type { TDrilldownReportType } from '../../../../schemas/types/materialized_report_drilldown_rows';
3
+ /**
4
+ * PHASE 2 — one scope's flat-projection plan.
5
+ *
6
+ * Pure composition of the existing row/scope builders. The caller still owns
7
+ * the replace/delta decision; this helper only turns one entry document into
8
+ * the exact rows/scopes the existing builders already produce.
9
+ */
10
+ export interface IReportFlatProjectionPlan {
11
+ rows: unknown[];
12
+ scope: unknown | null;
13
+ }
14
+ export declare function buildReportFlatProjectionPlan(input: {
15
+ reportType: TDrilldownReportType;
16
+ entryDocument: unknown;
17
+ scopeContext: MATERIALIZED_REPORT_SCOPE_ENUM;
18
+ scopeField: string;
19
+ page?: string | null;
20
+ sourceLocalDate?: string | null;
21
+ dayIndex?: string | null;
22
+ }): IReportFlatProjectionPlan | null;
@@ -0,0 +1,17 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.buildReportFlatProjectionPlan = buildReportFlatProjectionPlan;
4
+ const materialized_report_drilldown_rows_1 = require("../../materialized-report-drilldown-rows");
5
+ function buildReportFlatProjectionPlan(input) {
6
+ if (input.entryDocument == null)
7
+ return null;
8
+ const retargeted = {
9
+ ...input.entryDocument,
10
+ scope_context: input.scopeContext,
11
+ scope_field: input.scopeField,
12
+ day_index: input.dayIndex ?? null,
13
+ };
14
+ const flattened = (0, materialized_report_drilldown_rows_1.buildMaterializedDrilldownRows)(input.reportType, retargeted, input.sourceLocalDate ?? null);
15
+ const scope = (0, materialized_report_drilldown_rows_1.buildMaterializedDrilldownScope)(input.reportType, retargeted, flattened.rows, input.sourceLocalDate ?? null);
16
+ return { rows: flattened.rows, scope };
17
+ }
@@ -0,0 +1,8 @@
1
+ export * from './scope-refs';
2
+ export * from './entry-pages';
3
+ export * from './iteration-row';
4
+ export * from './flat-projection';
5
+ export * from './budget';
6
+ export * from './run-stats';
7
+ export * from './cap-metadata';
8
+ export * from './top-n';
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ __exportStar(require("./scope-refs"), exports);
18
+ __exportStar(require("./entry-pages"), exports);
19
+ __exportStar(require("./iteration-row"), exports);
20
+ __exportStar(require("./flat-projection"), exports);
21
+ __exportStar(require("./budget"), exports);
22
+ __exportStar(require("./run-stats"), exports);
23
+ __exportStar(require("./cap-metadata"), exports);
24
+ __exportStar(require("./top-n"), exports);
@@ -0,0 +1,13 @@
1
+ import type { MATERIALIZED_REPORT_TYPE_ENUM } from '../../../../constants/MATERIALIZED_REPORTS';
2
+ import { buildMaterializedTenantReportIteration } from '../../materialized-tenant-reports-iterations-helpers';
3
+ /**
4
+ * PHASE 2 — generic iteration-row builder.
5
+ *
6
+ * Thin composition over the existing builder so later phases have one place to
7
+ * pass a registry report type. The existing builder remains the source of truth.
8
+ */
9
+ export declare function buildReportIterationRow(report: unknown, options: {
10
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM;
11
+ reason: string;
12
+ computedAt?: Date;
13
+ }): ReturnType<typeof buildMaterializedTenantReportIteration>;
@@ -0,0 +1,13 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.buildReportIterationRow = buildReportIterationRow;
4
+ const materialized_tenant_reports_iterations_helpers_1 = require("../../materialized-tenant-reports-iterations-helpers");
5
+ /**
6
+ * PHASE 2 — generic iteration-row builder.
7
+ *
8
+ * Thin composition over the existing builder so later phases have one place to
9
+ * pass a registry report type. The existing builder remains the source of truth.
10
+ */
11
+ function buildReportIterationRow(report, options) {
12
+ return (0, materialized_tenant_reports_iterations_helpers_1.buildMaterializedTenantReportIteration)(report, options);
13
+ }
@@ -0,0 +1,20 @@
1
+ /** PHASE 2 — pure run-stat aggregation. */
2
+ export interface IReportRunStats {
3
+ reportKey: string;
4
+ localDate: string;
5
+ documents: number;
6
+ entryDocuments: number;
7
+ entryPages: number;
8
+ flatRows: number;
9
+ flatScopes: number;
10
+ geoCells: number;
11
+ iterationRows: number;
12
+ deletes: number;
13
+ cappedCells: number;
14
+ cappedOrders: number;
15
+ skipped: number;
16
+ warnings: string[];
17
+ }
18
+ export declare const EMPTY_REPORT_RUN_STATS: IReportRunStats;
19
+ export declare function buildReportRunStats(input: Partial<IReportRunStats> & Pick<IReportRunStats, 'reportKey' | 'localDate'>): IReportRunStats;
20
+ export declare function mergeReportRunStats(left: IReportRunStats, right: IReportRunStats): IReportRunStats;
@@ -0,0 +1,47 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.EMPTY_REPORT_RUN_STATS = void 0;
4
+ exports.buildReportRunStats = buildReportRunStats;
5
+ exports.mergeReportRunStats = mergeReportRunStats;
6
+ exports.EMPTY_REPORT_RUN_STATS = {
7
+ reportKey: '',
8
+ localDate: '',
9
+ documents: 0,
10
+ entryDocuments: 0,
11
+ entryPages: 0,
12
+ flatRows: 0,
13
+ flatScopes: 0,
14
+ geoCells: 0,
15
+ iterationRows: 0,
16
+ deletes: 0,
17
+ cappedCells: 0,
18
+ cappedOrders: 0,
19
+ skipped: 0,
20
+ warnings: [],
21
+ };
22
+ function buildReportRunStats(input) {
23
+ return {
24
+ ...exports.EMPTY_REPORT_RUN_STATS,
25
+ ...input,
26
+ warnings: [...(input.warnings ?? [])],
27
+ };
28
+ }
29
+ function mergeReportRunStats(left, right) {
30
+ const sum = (key) => Number(left[key] ?? 0) + Number(right[key] ?? 0);
31
+ return {
32
+ reportKey: left.reportKey === right.reportKey ? left.reportKey : `${left.reportKey}+${right.reportKey}`,
33
+ localDate: left.localDate === right.localDate ? left.localDate : `${left.localDate}+${right.localDate}`,
34
+ documents: sum('documents'),
35
+ entryDocuments: sum('entryDocuments'),
36
+ entryPages: sum('entryPages'),
37
+ flatRows: sum('flatRows'),
38
+ flatScopes: sum('flatScopes'),
39
+ geoCells: sum('geoCells'),
40
+ iterationRows: sum('iterationRows'),
41
+ deletes: sum('deletes'),
42
+ cappedCells: sum('cappedCells'),
43
+ cappedOrders: sum('cappedOrders'),
44
+ skipped: sum('skipped'),
45
+ warnings: [...left.warnings, ...right.warnings],
46
+ };
47
+ }
@@ -0,0 +1,13 @@
1
+ import { MATERIALIZED_REPORT_SCOPE_ENUM } from '../../../../constants/MATERIALIZED_REPORTS';
2
+ import type { IReportDefinition } from '../definition';
3
+ /**
4
+ * PHASE 2 — generic scope-ref resolution.
5
+ *
6
+ * This is a pure composition of the existing scope helpers. It does not replace
7
+ * the per-report ref builders; it is the primitive later phases can use.
8
+ */
9
+ export interface IReportScopeRef {
10
+ scope_context: MATERIALIZED_REPORT_SCOPE_ENUM;
11
+ scope_field: string;
12
+ }
13
+ export declare function resolveReportScopeRefsForDay(definition: Pick<IReportDefinition, 'reportScopes'>, localDate: string): IReportScopeRef[] | null;
@@ -0,0 +1,31 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.resolveReportScopeRefsForDay = resolveReportScopeRefsForDay;
4
+ const MATERIALIZED_REPORTS_1 = require("../../../../constants/MATERIALIZED_REPORTS");
5
+ const scope_helpers_1 = require("../../scope-helpers");
6
+ function resolveReportScopeRefsForDay(definition, localDate) {
7
+ const periodFields = (0, scope_helpers_1.getMaterializedPeriodScopeFields)(localDate);
8
+ if (periodFields == null)
9
+ return null;
10
+ const refs = [];
11
+ for (const [scopeContext, scopeField] of Object.entries(periodFields)) {
12
+ if (definition.reportScopes.includes(scopeContext)) {
13
+ refs.push({
14
+ scope_context: scopeContext,
15
+ scope_field: scopeField,
16
+ });
17
+ }
18
+ }
19
+ if (definition.reportScopes.includes(MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR)) {
20
+ for (let hour = 0; hour < 24; hour += 1) {
21
+ const scopeField = (0, scope_helpers_1.getMaterializedHourScopeField)(localDate, hour);
22
+ if (scopeField == null)
23
+ return null;
24
+ refs.push({
25
+ scope_context: MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR,
26
+ scope_field: scopeField,
27
+ });
28
+ }
29
+ }
30
+ return refs;
31
+ }
@@ -0,0 +1,16 @@
1
+ /** PHASE 2 — deterministic top-N + reserved overflow token. */
2
+ export declare const REPORT_OTHER_TOKEN = "__OTHER__";
3
+ export interface IReportTopNKey {
4
+ key: string;
5
+ count: number;
6
+ }
7
+ /**
8
+ * Selects the top-N keys by `count DESC, key ASC` and folds the rest into the
9
+ * reserved `__OTHER__` token. Generic; report-specific mapping stays report-owned.
10
+ */
11
+ export declare function selectReportTopN(entries: readonly IReportTopNKey[] | null | undefined, limit: number, otherToken?: string): {
12
+ kept: string[];
13
+ dropped: string[];
14
+ other: string | null;
15
+ };
16
+ export declare function resolveReportTopNKey(selection: ReturnType<typeof selectReportTopN>, key: string): string;
@@ -0,0 +1,29 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.REPORT_OTHER_TOKEN = void 0;
4
+ exports.selectReportTopN = selectReportTopN;
5
+ exports.resolveReportTopNKey = resolveReportTopNKey;
6
+ /** PHASE 2 — deterministic top-N + reserved overflow token. */
7
+ exports.REPORT_OTHER_TOKEN = '__OTHER__';
8
+ /**
9
+ * Selects the top-N keys by `count DESC, key ASC` and folds the rest into the
10
+ * reserved `__OTHER__` token. Generic; report-specific mapping stays report-owned.
11
+ */
12
+ function selectReportTopN(entries, limit, otherToken = exports.REPORT_OTHER_TOKEN) {
13
+ const counts = new Map();
14
+ for (const entry of entries ?? []) {
15
+ if (entry == null || typeof entry.key !== 'string' || entry.key === '')
16
+ continue;
17
+ counts.set(entry.key, (counts.get(entry.key) ?? 0) + (Number(entry.count) || 0));
18
+ }
19
+ const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
20
+ if (ranked.length <= Math.max(1, limit)) {
21
+ return { kept: ranked.map(([key]) => key), dropped: [], other: null };
22
+ }
23
+ const kept = ranked.slice(0, Math.max(1, limit)).map(([key]) => key);
24
+ const dropped = ranked.slice(Math.max(1, limit)).map(([key]) => key);
25
+ return { kept, dropped, other: otherToken };
26
+ }
27
+ function resolveReportTopNKey(selection, key) {
28
+ return selection.other != null && selection.dropped.includes(key) ? selection.other : key;
29
+ }
@@ -0,0 +1,13 @@
1
+ import { REPORT_KEY_ENUM } from '../../reporting-contract/report-contract';
2
+ import { type IReportDefinition, type IReportRegistryExemption } from './definition';
3
+ /**
4
+ * PHASE 2 — the metadata registry lookup surface.
5
+ *
6
+ * Pure lookups only; no side effects and no service imports.
7
+ */
8
+ export declare const REPORT_REGISTRY_KEYS: REPORT_KEY_ENUM[];
9
+ export declare function getReportDefinition(key: REPORT_KEY_ENUM | string): IReportDefinition | null;
10
+ export declare function getReportExemption(key: REPORT_KEY_ENUM | string): IReportRegistryExemption | null;
11
+ export declare function isProductionReportKey(key: REPORT_KEY_ENUM | string): boolean;
12
+ export declare function getProductionReportDefinitions(): IReportDefinition[];
13
+ export declare function getReportDefinitionBySegment(segment: string): IReportDefinition | null;
@@ -0,0 +1,31 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.REPORT_REGISTRY_KEYS = void 0;
4
+ exports.getReportDefinition = getReportDefinition;
5
+ exports.getReportExemption = getReportExemption;
6
+ exports.isProductionReportKey = isProductionReportKey;
7
+ exports.getProductionReportDefinitions = getProductionReportDefinitions;
8
+ exports.getReportDefinitionBySegment = getReportDefinitionBySegment;
9
+ const report_contract_1 = require("../../reporting-contract/report-contract");
10
+ const definition_1 = require("./definition");
11
+ /**
12
+ * PHASE 2 — the metadata registry lookup surface.
13
+ *
14
+ * Pure lookups only; no side effects and no service imports.
15
+ */
16
+ exports.REPORT_REGISTRY_KEYS = report_contract_1.ALL_REPORT_KEYS;
17
+ function getReportDefinition(key) {
18
+ return definition_1.REPORT_DEFINITIONS[String(key)] ?? null;
19
+ }
20
+ function getReportExemption(key) {
21
+ return definition_1.REPORT_REGISTRY_EXEMPTIONS[String(key)] ?? null;
22
+ }
23
+ function isProductionReportKey(key) {
24
+ return getReportDefinition(key)?.status === definition_1.REPORT_DEFINITION_STATUS.PRODUCTION;
25
+ }
26
+ function getProductionReportDefinitions() {
27
+ return [...definition_1.PRODUCTION_REPORT_DEFINITIONS];
28
+ }
29
+ function getReportDefinitionBySegment(segment) {
30
+ return definition_1.PRODUCTION_REPORT_DEFINITIONS.find((definition) => definition.segment === segment) ?? null;
31
+ }
@@ -0,0 +1,20 @@
1
+ import { type IReportDefinition, type IReportRegistryExemption } from './definition';
2
+ /**
3
+ * PHASE 2 — metadata conformance.
4
+ *
5
+ * Pure validation of the declarative registry. It does not read the database,
6
+ * import Mongoose/Express or inspect service code. The service-level conformance
7
+ * tests separately prove that the declared writer/live/historical adapters exist.
8
+ */
9
+ export interface IReportRegistryValidation {
10
+ ok: boolean;
11
+ errors: string[];
12
+ warnings: string[];
13
+ }
14
+ export interface IValidateReportRegistryInput {
15
+ definitions?: Record<string, IReportDefinition>;
16
+ exemptions?: Record<string, IReportRegistryExemption>;
17
+ keys?: readonly string[];
18
+ }
19
+ export declare function validateReportRegistry(input?: IValidateReportRegistryInput): IReportRegistryValidation;
20
+ export declare const REPORT_REGISTRY_VALIDATION: IReportRegistryValidation;