@managesome/eposmatic-toolkit 0.4.4 → 0.4.5

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 (45) hide show
  1. package/esm/helpers/materialized-reports/index.js +1 -0
  2. package/esm/helpers/materialized-reports/materialized-reports-read-helpers.js +96 -22
  3. package/esm/helpers/materialized-reports/materialized-reports-scope-group-helpers.js +281 -0
  4. package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +126 -7
  5. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +47 -1
  6. package/esm/helpers/order/generate-order.js +11 -0
  7. package/esm/helpers/store/common-order-actions.js +7 -3
  8. package/esm/helpers/types/materialized-reports-apis.js +1 -1
  9. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  10. package/lib/helpers/materialized-reports/index.js +1 -0
  11. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.d.ts +50 -21
  12. package/lib/helpers/materialized-reports/materialized-reports-read-helpers.js +96 -21
  13. package/lib/helpers/materialized-reports/materialized-reports-scope-group-helpers.d.ts +58 -0
  14. package/lib/helpers/materialized-reports/materialized-reports-scope-group-helpers.js +286 -0
  15. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +24 -0
  16. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +127 -7
  17. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +47 -1
  18. package/lib/helpers/order/generate-order.d.ts +2 -0
  19. package/lib/helpers/order/generate-order.js +13 -0
  20. package/lib/helpers/store/common-order-actions.js +7 -3
  21. package/lib/helpers/types/materialized-reports-apis.d.ts +115 -25
  22. package/lib/helpers/types/materialized-reports-apis.js +1 -0
  23. package/lib/schemas/models/internal_invoices.d.ts +3 -3
  24. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +9 -9
  25. package/lib/schemas/models/orders.d.ts +692 -692
  26. package/lib/schemas/models/tenant_purchase_orders.d.ts +90 -90
  27. package/lib/schemas/models/tenants.d.ts +9 -9
  28. package/lib/schemas/models/warehouse_communications.d.ts +3 -3
  29. package/lib/schemas/models/warehouse_internal_movements.d.ts +48 -48
  30. package/lib/schemas/models/warehouse_purchase_order_rfqs.d.ts +63 -63
  31. package/lib/schemas/models/warehouse_purchase_orders.d.ts +96 -96
  32. package/lib/schemas/models/warehouse_sale_invoices.d.ts +3 -3
  33. package/lib/schemas/models/warehouse_sale_order_rfqs.d.ts +69 -69
  34. package/lib/schemas/models/warehouse_sale_orders.d.ts +45 -45
  35. package/lib/schemas/models/warehouses.d.ts +6 -6
  36. package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.d.ts +1 -0
  37. package/lib/tests/materialized-reports/materialized-reports-read-helpers.test.js +100 -0
  38. package/lib/tests/materialized-reports/materialized-reports-scope-group-helpers.test.d.ts +1 -0
  39. package/lib/tests/materialized-reports/materialized-reports-scope-group-helpers.test.js +275 -0
  40. package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.d.ts +1 -0
  41. package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +143 -0
  42. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +22 -0
  43. package/lib/tests/num-of-guests-limit.test.d.ts +1 -0
  44. package/lib/tests/num-of-guests-limit.test.js +76 -0
  45. package/package.json +1 -1
@@ -1,4 +1,6 @@
1
- import { MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_TYPE_ENUM } from '../../constants';
1
+ import { MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_TYPE_ENUM, REPORT_SALE_TYPE_ENUM } from '../../constants';
2
+ import { MATERIALIZED_REPORT_KEY_FILTER_ENUM } from '../../constants/MATERIALIZED_REPORTS';
3
+ import { IMaterializedReportOrderMetric, IMaterializedReportPaymentMetric } from '../../schemas/types/materialized_tenant_sales_overview_reports';
2
4
  /**
3
5
  * Request body contracts for the materialized reports READ APIs
4
6
  * (operations-service, mounted at `/reports`) — shared between
@@ -7,39 +9,56 @@ import { MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_TYPE_ENUM } from '.
7
9
  *
8
10
  * Every endpoint takes the tenant scope as an ARRAY (`tenants`, minimum
9
11
  * length 1) so a single call can serve one tenant or many (brand-level
10
- * reports). Responses are the persisted documents themselves (see
11
- * `IMaterializedTenantSalesOverviewReport` /
12
- * `IMaterializedTenantReportIteration`) — amounts are INTEGER CENTS.
12
+ * reports). Amounts are INTEGER CENTS. The response shape never varies:
13
+ * EVERY read is answered with ONE aggregated record per tenant
14
+ * (`IMaterializedTenantSalesOverviewAggregatedReport[]`).
13
15
  */
14
16
  /**
15
- * Body of `POST /reports/overview` — materialized sales overview
16
- * documents (`materialized_tenant_sales_overview_reports`).
17
+ * ONE scope group of a read — a single `scope_context` with its exact
18
+ * values. A smart caller can mix groups (e.g. a time SPAN read: `localHour`
19
+ * labels for the partial boundary days + `localDate` values for the full
20
+ * days between them); the backend runs one aggregation branch per group and
21
+ * folds all of them into the SAME per-tenant record.
17
22
  *
18
- * The scope query is either the exact `scope_field`, or the inclusive
19
- * lexicographic range `from`..`to` (all scope_field formats are fixed-width,
20
- * so lexicographic order equals chronological order).
23
+ * `scope_context` is optional; the backend defaults it to `LOCAL_DATE`.
24
+ * `scope_field` holds EXACT values (minimum length 1) — a single value is
25
+ * matched with direct equality, multiple values with `$in`; lexical
26
+ * `from`..`to` ranges are NOT part of the contract (removed). Groups must
27
+ * not overlap — the backend simply unions their matched documents.
21
28
  */
22
- export interface IGetMaterializedTenantSalesOverviewReportsBody {
29
+ export interface IGetMaterializedReportScopeGroup {
30
+ scope_context?: MATERIALIZED_REPORT_SCOPE_ENUM;
31
+ scope_field: string[];
32
+ }
33
+ /**
34
+ * Shared body of the materialized reports READ APIs — every report endpoint
35
+ * (`POST /reports/overview` today; X / Z / Riders / Items / … as they land)
36
+ * takes the same shape. Build it with `buildMaterializedReportReadBody`
37
+ * (toolkit) and derive the groups from a calendar selection with
38
+ * `buildMaterializedReportScopeGroups` (toolkit) — never ad-hoc literals.
39
+ *
40
+ * The scope query is a LIST of exact-value groups (`scope_groups`, minimum
41
+ * length 1, one `scope_context` per group). The backend derives, per group,
42
+ * the query shape (a single value is matched with direct equality, multiple
43
+ * values with `$in`), folds each group inside MongoDB and answers with ONE
44
+ * aggregated record per tenant — the response shape never varies.
45
+ */
46
+ export interface IGetMaterializedReportBody {
23
47
  /** One or more tenant ids to read (minimum length 1). */
24
48
  tenants: string[];
25
49
  /**
26
- * Scope granularity — one of `MATERIALIZED_REPORT_SCOPE_ENUM`. Optional;
27
- * the backend defaults to `LOCAL_DATE`.
28
- */
29
- scope_context?: MATERIALIZED_REPORT_SCOPE_ENUM;
30
- /** Exact scope value (e.g. '2026-09-30' or '2026-09-30 18'). */
31
- scope_field?: string;
32
- /**
33
- * Inclusive lower bound on `scope_field` — required together with `to` when
34
- * `scope_field` is absent.
35
- */
36
- from?: string;
37
- /**
38
- * Inclusive upper bound on `scope_field` — required together with `from`
39
- * when `scope_field` is absent.
50
+ * One or more scope groups (minimum length 1). Groups may use DIFFERENT
51
+ * scope contexts (a span read mixes `localHour` boundary labels with full
52
+ * `localDate` / period values); their scopes must not overlap.
40
53
  */
41
- to?: string;
54
+ scope_groups: IGetMaterializedReportScopeGroup[];
42
55
  }
56
+ /**
57
+ * Body of `POST /reports/overview` — materialized sales overview
58
+ * documents (`materialized_tenant_sales_overview_reports`). Same shape as
59
+ * every materialized reports read body.
60
+ */
61
+ export type IGetMaterializedTenantSalesOverviewReportsBody = IGetMaterializedReportBody;
43
62
  /**
44
63
  * Body of `POST /reports/iterations` — the latest stored versions
45
64
  * of ONE report document from `materialized_tenant_reports_iterations` (the
@@ -63,3 +82,74 @@ export interface IGetMaterializedReportIterationsBody {
63
82
  /** Latest N iterations, newest-first. Optional; default 5, capped at 50. */
64
83
  limit?: number;
65
84
  }
85
+ /**
86
+ * Per-key metrics of an AGGREGATED overview record — same key grammar as the
87
+ * stored documents' `sale_type_metrics`, produced by the backend's
88
+ * aggregation pipeline (operations-service — backend-only).
89
+ *
90
+ * Deliberately leaner than the stored shape (the pipeline never materializes
91
+ * what no view reads):
92
+ * - `payments` is summed ONLY under `TOTAL_SALES` (the slot the frontend
93
+ * payment breakdown reads); `AMOUNT_COLLECTED` carries orders only;
94
+ * - the credit-bill ledgers (`issued.bills[]` / `received.bills[]`) are
95
+ * dropped — only the counters the report views derive from are kept.
96
+ */
97
+ export interface IMaterializedTenantSalesOverviewAggregatedKeyMetrics {
98
+ [REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: {
99
+ orders: IMaterializedReportOrderMetric;
100
+ payments: IMaterializedReportPaymentMetric[];
101
+ };
102
+ [REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED]: {
103
+ orders: IMaterializedReportOrderMetric;
104
+ };
105
+ [REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: {
106
+ issued: {
107
+ count: number;
108
+ amount: number;
109
+ settled_count: number;
110
+ settled_amount: number;
111
+ };
112
+ received: {
113
+ count: number;
114
+ amount: number;
115
+ };
116
+ };
117
+ }
118
+ /**
119
+ * ONE aggregated record per tenant — the response of EVERY overview read
120
+ * (for a single-value read `matched_documents` is 1 and the span collapses
121
+ * to that value). The backend folds every matched scope document into this
122
+ * record inside MongoDB — nothing beyond this record crosses the
123
+ * DB → service boundary.
124
+ *
125
+ * The `sale_type_metrics` key map is fully preserved, so the frontend can
126
+ * still apply its platform / order-status filters client-side on a single
127
+ * record — via `getFormattedTenantSalesOverviewAggregatedReporting`.
128
+ *
129
+ * NOT part of the stored schema: carries no `_id`, `iteration`,
130
+ * `schema_version`, `source_watermark`, `computed_at` or timestamps — only
131
+ * the report values plus the read context (`matched_documents` and the
132
+ * `scope_field` span) useful for debugging. No `scope_context`: a span read
133
+ * mixes several.
134
+ */
135
+ export interface IMaterializedTenantSalesOverviewAggregatedReport {
136
+ tenant_id: string;
137
+ brand_id: string;
138
+ /**
139
+ * How many stored scope documents were folded into this record — an EXACT
140
+ * count, independent of the key map (documents with disjoint key sets
141
+ * and order-less documents with an empty key map still count).
142
+ */
143
+ matched_documents: number;
144
+ /**
145
+ * First / last matched scope value. Lexicographic order is chronological
146
+ * for the fixed-width period formats; for hour labels it is per-label-day
147
+ * only — never order hour series lexicographically (see
148
+ * `getMaterializedBusinessHourIndex`). For a single-value read both are
149
+ * equal.
150
+ */
151
+ first_scope_field: string;
152
+ last_scope_field: string;
153
+ sale_type_key_filters: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
154
+ sale_type_metrics: Record<string, IMaterializedTenantSalesOverviewAggregatedKeyMetrics>;
155
+ }
@@ -1,2 +1,3 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ const constants_1 = require("../../constants");
@@ -16,9 +16,9 @@ export declare const InternalInvoiceSchema: Schema<any, import("mongoose").Model
16
16
  customer_name: string;
17
17
  status: import("../../constants").INTERNAL_INVOICE_STATUS_ENUM;
18
18
  payment_method: string;
19
- grand_total: number;
20
19
  tax_number: string;
21
20
  tax_amount: number;
21
+ grand_total: number;
22
22
  subtotal: number;
23
23
  payment_terms: string;
24
24
  notes: string;
@@ -44,9 +44,9 @@ export declare const InternalInvoiceSchema: Schema<any, import("mongoose").Model
44
44
  customer_name: string;
45
45
  status: import("../../constants").INTERNAL_INVOICE_STATUS_ENUM;
46
46
  payment_method: string;
47
- grand_total: number;
48
47
  tax_number: string;
49
48
  tax_amount: number;
49
+ grand_total: number;
50
50
  subtotal: number;
51
51
  payment_terms: string;
52
52
  notes: string;
@@ -72,9 +72,9 @@ export declare const InternalInvoiceSchema: Schema<any, import("mongoose").Model
72
72
  customer_name: string;
73
73
  status: import("../../constants").INTERNAL_INVOICE_STATUS_ENUM;
74
74
  payment_method: string;
75
- grand_total: number;
76
75
  tax_number: string;
77
76
  tax_amount: number;
77
+ grand_total: number;
78
78
  subtotal: number;
79
79
  payment_terms: string;
80
80
  notes: string;
@@ -37,8 +37,8 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
37
37
  brand_id: string;
38
38
  day_index: import("../../constants").DAY_INDEX_ENUM;
39
39
  iteration: number;
40
- schema_version: number;
41
40
  scope_context: import("../../constants").MATERIALIZED_REPORT_SCOPE_ENUM;
41
+ schema_version: number;
42
42
  scope_field: string;
43
43
  sale_type_key_filters: string[];
44
44
  sale_type_metrics: Map<string, {
@@ -47,9 +47,9 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
47
47
  count: number;
48
48
  discount_amount: number;
49
49
  delivery_charges: number;
50
- gst_amount: number;
51
50
  tip_amount: number;
52
51
  tax_amount: number;
52
+ gst_amount: number;
53
53
  tax_invoice_provider_charges: number;
54
54
  gross_amount: number;
55
55
  discount_by_type: {
@@ -89,9 +89,9 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
89
89
  count: number;
90
90
  discount_amount: number;
91
91
  delivery_charges: number;
92
- gst_amount: number;
93
92
  tip_amount: number;
94
93
  tax_amount: number;
94
+ gst_amount: number;
95
95
  tax_invoice_provider_charges: number;
96
96
  gross_amount: number;
97
97
  discount_by_type: {
@@ -202,8 +202,8 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
202
202
  brand_id: string;
203
203
  day_index: import("../../constants").DAY_INDEX_ENUM;
204
204
  iteration: number;
205
- schema_version: number;
206
205
  scope_context: import("../../constants").MATERIALIZED_REPORT_SCOPE_ENUM;
206
+ schema_version: number;
207
207
  scope_field: string;
208
208
  sale_type_key_filters: string[];
209
209
  sale_type_metrics: Map<string, {
@@ -212,9 +212,9 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
212
212
  count: number;
213
213
  discount_amount: number;
214
214
  delivery_charges: number;
215
- gst_amount: number;
216
215
  tip_amount: number;
217
216
  tax_amount: number;
217
+ gst_amount: number;
218
218
  tax_invoice_provider_charges: number;
219
219
  gross_amount: number;
220
220
  discount_by_type: {
@@ -254,9 +254,9 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
254
254
  count: number;
255
255
  discount_amount: number;
256
256
  delivery_charges: number;
257
- gst_amount: number;
258
257
  tip_amount: number;
259
258
  tax_amount: number;
259
+ gst_amount: number;
260
260
  tax_invoice_provider_charges: number;
261
261
  gross_amount: number;
262
262
  discount_by_type: {
@@ -367,8 +367,8 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
367
367
  brand_id: string;
368
368
  day_index: import("../../constants").DAY_INDEX_ENUM;
369
369
  iteration: number;
370
- schema_version: number;
371
370
  scope_context: import("../../constants").MATERIALIZED_REPORT_SCOPE_ENUM;
371
+ schema_version: number;
372
372
  scope_field: string;
373
373
  sale_type_key_filters: string[];
374
374
  sale_type_metrics: Map<string, {
@@ -377,9 +377,9 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
377
377
  count: number;
378
378
  discount_amount: number;
379
379
  delivery_charges: number;
380
- gst_amount: number;
381
380
  tip_amount: number;
382
381
  tax_amount: number;
382
+ gst_amount: number;
383
383
  tax_invoice_provider_charges: number;
384
384
  gross_amount: number;
385
385
  discount_by_type: {
@@ -419,9 +419,9 @@ export declare const MaterializedTenantSalesOverviewReportSchema: Schema<any, im
419
419
  count: number;
420
420
  discount_amount: number;
421
421
  delivery_charges: number;
422
- gst_amount: number;
423
422
  tip_amount: number;
424
423
  tax_amount: number;
424
+ gst_amount: number;
425
425
  tax_invoice_provider_charges: number;
426
426
  gross_amount: number;
427
427
  discount_by_type: {