@managesome/eposmatic-toolkit 0.4.23 → 0.4.24

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 (46) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +83 -2
  2. package/esm/helpers/materialized-reports/index.js +3 -0
  3. package/esm/helpers/materialized-reports/materialized-discount-accumulator-helpers.js +115 -35
  4. package/esm/helpers/materialized-reports/materialized-discount-classification-helpers.js +39 -12
  5. package/esm/helpers/materialized-reports/materialized-discount-details-helpers.js +28 -0
  6. package/esm/helpers/materialized-reports/materialized-discount-source-helpers.js +428 -0
  7. package/esm/helpers/materialized-reports/tenant-discount-source-formatter.js +140 -0
  8. package/esm/schemas/models/index.js +1 -0
  9. package/esm/schemas/models/materialized_tenant_discount_entries.js +12 -0
  10. package/esm/schemas/models/materialized_tenant_discount_sources.js +165 -0
  11. package/esm/schemas/types/index.js +1 -0
  12. package/esm/schemas/types/materialized_tenant_discount_sources.js +1 -0
  13. package/lib/constants/MATERIALIZED_REPORTS.d.ts +79 -2
  14. package/lib/constants/MATERIALIZED_REPORTS.js +85 -4
  15. package/lib/helpers/materialized-reports/index.d.ts +3 -0
  16. package/lib/helpers/materialized-reports/index.js +3 -0
  17. package/lib/helpers/materialized-reports/materialized-discount-accumulator-helpers.d.ts +30 -0
  18. package/lib/helpers/materialized-reports/materialized-discount-accumulator-helpers.js +116 -35
  19. package/lib/helpers/materialized-reports/materialized-discount-classification-helpers.d.ts +27 -4
  20. package/lib/helpers/materialized-reports/materialized-discount-classification-helpers.js +38 -11
  21. package/lib/helpers/materialized-reports/materialized-discount-details-helpers.d.ts +31 -0
  22. package/lib/helpers/materialized-reports/materialized-discount-details-helpers.js +31 -0
  23. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.d.ts +73 -0
  24. package/lib/helpers/materialized-reports/materialized-discount-source-helpers.js +437 -0
  25. package/lib/helpers/materialized-reports/tenant-discount-source-formatter.d.ts +79 -0
  26. package/lib/helpers/materialized-reports/tenant-discount-source-formatter.js +144 -0
  27. package/lib/helpers/types/materialized-reports-apis.d.ts +53 -1
  28. package/lib/schemas/models/index.d.ts +1 -0
  29. package/lib/schemas/models/index.js +1 -0
  30. package/lib/schemas/models/materialized_tenant_discount_entries.d.ts +21 -6
  31. package/lib/schemas/models/materialized_tenant_discount_entries.js +12 -0
  32. package/lib/schemas/models/materialized_tenant_discount_sources.d.ts +331 -0
  33. package/lib/schemas/models/materialized_tenant_discount_sources.js +168 -0
  34. package/lib/schemas/types/index.d.ts +1 -0
  35. package/lib/schemas/types/index.js +1 -0
  36. package/lib/schemas/types/materialized_tenant_discount_entries.d.ts +26 -0
  37. package/lib/schemas/types/materialized_tenant_discount_sources.d.ts +128 -0
  38. package/lib/schemas/types/materialized_tenant_discount_sources.js +2 -0
  39. package/lib/tests/materialized-reports/materialized-discount-classification.test.js +22 -2
  40. package/lib/tests/materialized-reports/materialized-discount-details-helpers.test.d.ts +1 -0
  41. package/lib/tests/materialized-reports/materialized-discount-details-helpers.test.js +59 -0
  42. package/lib/tests/materialized-reports/materialized-discount-sources.test.d.ts +1 -0
  43. package/lib/tests/materialized-reports/materialized-discount-sources.test.js +483 -0
  44. package/lib/tests/materialized-reports/tenant-discount-source-formatter.test.d.ts +1 -0
  45. package/lib/tests/materialized-reports/tenant-discount-source-formatter.test.js +203 -0
  46. package/package.json +1 -1
@@ -0,0 +1,165 @@
1
+ import { Schema } from 'mongoose';
2
+ import { ALL_DAY_INDEX } from '../../constants/ENUMS';
3
+ import { ALL_MATERIALIZED_DISCOUNT_ENTRY_KINDS, ALL_MATERIALIZED_DISCOUNT_LEVELS, ALL_MATERIALIZED_DISCOUNT_RATE_KINDS, ALL_MATERIALIZED_DISCOUNT_SLOTS, ALL_MATERIALIZED_DISCOUNT_SOURCE_CLASSES, ALL_MATERIALIZED_DISCOUNT_SUB_KINDS, ALL_MATERIALIZED_REPORT_KEY_FILTERS, DISCOUNTS_KEY_FILTERS, MATERIALIZED_DISCOUNT_REPORT_SCOPES, } from '../../constants/MATERIALIZED_REPORTS';
4
+ /**
5
+ * Mongoose schema for `materialized_tenant_discount_sources` — the DERIVED
6
+ * "by discount" projection of the discounts report (see
7
+ * `schemas/types/materialized_tenant_discount_sources.ts`).
8
+ *
9
+ * One document per (tenant, scope context, scope field, source key, level).
10
+ * The top-level metrics are the sum of `key_metrics`, which carries the
11
+ * `ORDER_STATUS:PLATFORM` split so the report filters stay exact.
12
+ *
13
+ * This collection is REBUILT from the post-plan entry documents in the close
14
+ * transaction. It has no iteration history of its own: the parent entry
15
+ * documents are the audit trail.
16
+ */
17
+ /**
18
+ * Version of the source-projection rules. Bump when the source identity,
19
+ * grouping or rate rule changes — historical documents must then be rebuilt
20
+ * with the backfill script.
21
+ */
22
+ export const MATERIALIZED_TENANT_DISCOUNT_SOURCES_SCHEMA_VERSION = 1;
23
+ const DiscountSourceKeyMetricsSchema = new Schema({
24
+ key: { type: String, required: true },
25
+ order_count: { type: Number, required: true, min: 0, default: 0 },
26
+ row_count: { type: Number, required: true, min: 0, default: 0 },
27
+ discount_amount: { type: Number, required: true, default: 0 },
28
+ free_item_count: { type: Number, required: true, min: 0, default: 0 },
29
+ free_item_value: { type: Number, required: true, default: 0 },
30
+ covered_amount: { type: Number, required: true, default: 0 },
31
+ percentage_row_count: { type: Number, required: true, min: 0, default: 0 },
32
+ percentage_rate_sum: { type: Number, required: true, default: 0 },
33
+ fixed_row_count: { type: Number, required: true, min: 0, default: 0 },
34
+ }, { _id: false });
35
+ export const MaterializedTenantDiscountSourceSchema = new Schema({
36
+ _id: {
37
+ type: Schema.Types.ObjectId,
38
+ required: true,
39
+ immutable: true,
40
+ },
41
+ tenant_id: { type: String, required: true },
42
+ brand_id: { type: String, required: true },
43
+ scope_context: {
44
+ type: String,
45
+ required: true,
46
+ enum: MATERIALIZED_DISCOUNT_REPORT_SCOPES,
47
+ },
48
+ scope_field: { type: String, required: true },
49
+ day_index: {
50
+ type: String,
51
+ default: null,
52
+ enum: [...ALL_DAY_INDEX, null],
53
+ },
54
+ source_key: { type: String, required: true },
55
+ source_id: { type: String, default: null },
56
+ source_name: { type: String, required: true },
57
+ source_class: {
58
+ type: String,
59
+ required: true,
60
+ enum: ALL_MATERIALIZED_DISCOUNT_SOURCE_CLASSES,
61
+ },
62
+ kind: { type: String, required: true, enum: ALL_MATERIALIZED_DISCOUNT_ENTRY_KINDS },
63
+ level: { type: String, required: true, enum: ALL_MATERIALIZED_DISCOUNT_LEVELS },
64
+ slot: {
65
+ type: String,
66
+ default: null,
67
+ enum: [...ALL_MATERIALIZED_DISCOUNT_SLOTS, null],
68
+ },
69
+ sub_kind: { type: String, required: true, enum: ALL_MATERIALIZED_DISCOUNT_SUB_KINDS },
70
+ rate: { type: Number, default: null },
71
+ rate_kind: {
72
+ type: String,
73
+ default: null,
74
+ enum: [...ALL_MATERIALIZED_DISCOUNT_RATE_KINDS, null],
75
+ },
76
+ percentage_row_count: { type: Number, required: true, min: 0, default: 0 },
77
+ percentage_rate_sum: { type: Number, required: true, default: 0 },
78
+ fixed_row_count: { type: Number, required: true, min: 0, default: 0 },
79
+ order_count: { type: Number, required: true, min: 0, default: 0 },
80
+ row_count: { type: Number, required: true, min: 0, default: 0 },
81
+ discount_amount: { type: Number, required: true, default: 0 },
82
+ free_item_count: { type: Number, required: true, min: 0, default: 0 },
83
+ free_item_value: { type: Number, required: true, default: 0 },
84
+ complimentary_full: { type: Boolean, default: null },
85
+ covered_amount: { type: Number, required: true, default: 0 },
86
+ key_metrics: {
87
+ type: [DiscountSourceKeyMetricsSchema],
88
+ required: true,
89
+ default: () => [],
90
+ },
91
+ sale_type_key_filters: {
92
+ type: [String],
93
+ required: true,
94
+ default: () => [...DISCOUNTS_KEY_FILTERS],
95
+ validate: {
96
+ validator: (value) => value.length > 0 &&
97
+ value.every((entry) => ALL_MATERIALIZED_REPORT_KEY_FILTERS.includes(entry)),
98
+ message: 'sale_type_key_filters must be a non-empty subset of the known key filters',
99
+ },
100
+ },
101
+ schema_version: {
102
+ type: Number,
103
+ required: true,
104
+ immutable: true,
105
+ default: MATERIALIZED_TENANT_DISCOUNT_SOURCES_SCHEMA_VERSION,
106
+ },
107
+ source_watermark: { type: Schema.Types.Date, required: true },
108
+ computed_at: { type: Schema.Types.Date, required: true },
109
+ createdAt: {
110
+ type: Schema.Types.Date,
111
+ required: true,
112
+ default: () => new Date(),
113
+ immutable: true,
114
+ },
115
+ updatedAt: {
116
+ type: Schema.Types.Date,
117
+ required: true,
118
+ default: () => new Date(),
119
+ },
120
+ }, {
121
+ timestamps: true,
122
+ versionKey: false,
123
+ minimize: false,
124
+ });
125
+ export { DiscountSourceKeyMetricsSchema };
126
+ export const MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_NAME = 'materialized_tenant_discount_sources';
127
+ /**
128
+ * Indexes for `materialized_tenant_discount_sources`.
129
+ *
130
+ * Compound keys are named by their field path (`field__field__field`), matching
131
+ * every other materialized collection's index constants.
132
+ *
133
+ * - `tenant_id__scope_context__scope_field__source_key__level` is the
134
+ * write-side upsert/delete key and the scope prefix every historical read
135
+ * uses.
136
+ * - `tenant_id__scope_context__scope_field__discount_amount` serves the
137
+ * "biggest source first" sort inside a scope.
138
+ */
139
+ export const MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_INDEXES = {
140
+ _id: { _id: 1 },
141
+ tenant_id__scope_context__scope_field__source_key__level: {
142
+ tenant_id: 1,
143
+ scope_context: 1,
144
+ scope_field: 1,
145
+ source_key: 1,
146
+ level: 1,
147
+ },
148
+ tenant_id__scope_context__scope_field__discount_amount: {
149
+ tenant_id: 1,
150
+ scope_context: 1,
151
+ scope_field: 1,
152
+ discount_amount: -1,
153
+ },
154
+ };
155
+ export const MATERIALIZED_TENANT_DISCOUNT_SOURCES_INDEX_OPTIONS = [
156
+ {
157
+ key: MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_INDEXES.tenant_id__scope_context__scope_field__source_key__level,
158
+ name: 'tenant_id__scope_context__scope_field__source_key__level',
159
+ unique: true,
160
+ },
161
+ {
162
+ key: MATERIALIZED_TENANT_DISCOUNT_SOURCES_COLLECTION_INDEXES.tenant_id__scope_context__scope_field__discount_amount,
163
+ name: 'tenant_id__scope_context__scope_field__discount_amount_desc',
164
+ },
165
+ ];
@@ -33,6 +33,7 @@ export * from './marketing_fingerprints';
33
33
  export * from './materialized_credit_bills';
34
34
  export * from './materialized_tenant_discount_entries';
35
35
  export * from './materialized_tenant_discount_reports';
36
+ export * from './materialized_tenant_discount_sources';
36
37
  export * from './materialized_tenant_cash_entries';
37
38
  export * from './materialized_tenant_delivery_entries';
38
39
  export * from './materialized_tenant_delivery_reports';
@@ -158,8 +158,9 @@ export declare const ALL_MATERIALIZED_DISCOUNT_SUB_KINDS: MATERIALIZED_DISCOUNT_
158
158
  * `materialized_tenant_discount_entries`.
159
159
  *
160
160
  * - `DISCOUNT` — a slot on the order or on one item.
161
- * - `FREE_ITEM` — a 100 % item row (also present as a `DISCOUNT` row; the
162
- * drill-down decides which view lists it).
161
+ * - `FREE_ITEM` — a 100 % item row. It is a SINGLE row of this kind (not
162
+ * duplicated as a DISCOUNT row: `entry_key` is the row's
163
+ * identity, so a duplicate would collide in a period merge).
163
164
  * - `COMPLIMENTARY` — a `COMPLIMENTARY` payment (no discount slot required).
164
165
  */
165
166
  export declare enum MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM {
@@ -188,6 +189,82 @@ export declare const MATERIALIZED_DISCOUNT_SOURCE_LIMIT = 12;
188
189
  export declare const MATERIALIZED_DISCOUNT_SPECIAL_DISCOUNT_ID = "SPECIAL_DISCOUNT";
189
190
  export declare const MATERIALIZED_DISCOUNT_MANUAL_PREFIX = "MANUAL_";
190
191
  export declare const MATERIALIZED_DISCOUNT_PRICE_OVERRIDE_PREFIX = "MANUAL_SINGLE_";
192
+ /**
193
+ * SOURCE CLASS of a discount row — the grouping the "By discount" view uses.
194
+ *
195
+ * This is a REPORTING taxonomy, not a new write-path discriminator: every
196
+ * value is derived from the row (slot + id shape + reason + item id), so it
197
+ * can be rebuilt from historical entry documents at any time.
198
+ *
199
+ * - `COLLECTION` — a `discounts` collection document (order- or item-level).
200
+ * - `MANUAL` — a quick/custom amount at the order or item level.
201
+ * - `PAYMENT_TYPE` — a discount configured on a payment type. It looks like a
202
+ * `MANUAL_*` row, but its `special_discount_reason` is
203
+ * `Discount applied for <payment type>`; grouping it as a
204
+ * manual discount would hide which tender drove it.
205
+ * - `PRICE_OVERRIDE` — an item price edit (`MANUAL_SINGLE_*`).
206
+ * - `CATALOG_AUTO` — the item's own catalog `discount_amount`, written with
207
+ * the ITEM id as `special_discount_id` (or the
208
+ * `SPECIAL_DISCOUNT` sentinel). This is why the source
209
+ * classifier compares the id to the row's `item_id`: a
210
+ * catalog id is usually a 24-hex ObjectId and would
211
+ * otherwise be mistaken for a collection discount.
212
+ * - `LOYALTY` — offers, gift cards and wallet cashback (loyalty slot).
213
+ * - `VOUCHER` — voucher / voucher-linked offer (voucher slot).
214
+ * - `COMPLIMENTARY` — a `COMPLIMENTARY` tender, fully or partially covering
215
+ * the order. NOT a discount: never added to the discount
216
+ * total or share.
217
+ * - `UNATTRIBUTED` — money the row's slots cannot explain.
218
+ */
219
+ export declare enum MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM {
220
+ COLLECTION = "COLLECTION",
221
+ MANUAL = "MANUAL",
222
+ PAYMENT_TYPE = "PAYMENT_TYPE",
223
+ PRICE_OVERRIDE = "PRICE_OVERRIDE",
224
+ CATALOG_AUTO = "CATALOG_AUTO",
225
+ LOYALTY = "LOYALTY",
226
+ VOUCHER = "VOUCHER",
227
+ COMPLIMENTARY = "COMPLIMENTARY",
228
+ UNATTRIBUTED = "UNATTRIBUTED"
229
+ }
230
+ export declare const ALL_MATERIALIZED_DISCOUNT_SOURCE_CLASSES: MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM[];
231
+ /**
232
+ * Rate shape of a source row, for the "Avg rate" column:
233
+ * `PERCENTAGE` rows show their average %, `FIXED` rows show "—" (a fixed
234
+ * amount has no rate), and `MIXED` rows show "mixed".
235
+ */
236
+ export declare enum MATERIALIZED_DISCOUNT_RATE_KIND_ENUM {
237
+ PERCENTAGE = "PERCENTAGE",
238
+ FIXED = "FIXED",
239
+ MIXED = "MIXED"
240
+ }
241
+ export declare const ALL_MATERIALIZED_DISCOUNT_RATE_KINDS: MATERIALIZED_DISCOUNT_RATE_KIND_ENUM[];
242
+ /**
243
+ * Source keys that are ONE row regardless of the individual amounts/rates.
244
+ * Manual order discounts are deliberately ONE source (`manual:order`): the id
245
+ * they carry is generated from the amount (`MANUAL_50%`, `MANUAL_Rs 500`), so
246
+ * keying on it would create a new "source" for every amount. The drill-down
247
+ * keeps every individual row/rate.
248
+ */
249
+ export declare const MATERIALIZED_DISCOUNT_SOURCE_KEY: {
250
+ readonly MANUAL_ORDER: "manual:order";
251
+ readonly MANUAL_ITEM: "manual:item";
252
+ readonly PRICE_OVERRIDE_ITEM: "price_override:item";
253
+ readonly CATALOG_AUTO: "catalog:auto";
254
+ readonly WALLET_CASHBACK: "loyalty:wallet_cashback";
255
+ readonly COMPLIMENTARY_FULL: "complimentary:full";
256
+ readonly COMPLIMENTARY_PARTIAL: "complimentary:partial";
257
+ readonly COMPLIMENTARY_UNKNOWN: "complimentary:unknown";
258
+ readonly UNATTRIBUTED: "unattributed";
259
+ };
260
+ /** Prefixes of the parameterised source keys (`discount:<id>` etc.). */
261
+ export declare const MATERIALIZED_DISCOUNT_SOURCE_KEY_PREFIX: {
262
+ readonly DISCOUNT: "discount:";
263
+ readonly LOYALTY_OFFER: "loyalty:offer:";
264
+ readonly LOYALTY_GIFT_CARD: "loyalty:gift_card:";
265
+ readonly VOUCHER: "voucher:";
266
+ readonly PAYMENT_TYPE: "payment_type:";
267
+ };
191
268
  /**
192
269
  * Payment-type label used by the frontend report formatter for the derived
193
270
  * credit-settlement line in a collection day's payments breakdown (a
@@ -10,8 +10,8 @@
10
10
  * explicitly-enabled step.
11
11
  */
12
12
  Object.defineProperty(exports, "__esModule", { value: true });
13
- exports.MATERIALIZED_SALES_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_MATERIALIZED_REPORT_TYPES = exports.MATERIALIZED_REPORT_TYPE_ENUM = exports.ALL_MATERIALIZED_PREP_TIME_TARGETS = exports.MATERIALIZED_PREP_TIME_TARGET_ENUM = exports.MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA = exports.MATERIALIZED_PREP_TIME_TOP_BUCKET = exports.MATERIALIZED_PREP_TIME_MAX_MINUTES = exports.ALL_MATERIALIZED_PREP_TIME_BUCKET_LABELS = exports.MATERIALIZED_PREP_TIME_BUCKETS = exports.ALL_MATERIALIZED_PREP_TIME_ANCHORS = exports.MATERIALIZED_PREP_TIME_ANCHOR_ENUM = exports.PREP_TIME_KEY_FILTERS = exports.MATERIALIZED_PREP_TIME_REPORT_SCOPES = exports.MATERIALIZED_DELIVERY_AREA_LIMIT = exports.MATERIALIZED_DELIVERY_RIDER_LIMIT = exports.MATERIALIZED_DELIVERY_DISTANCE_BUCKETS = exports.DELIVERY_KEY_FILTERS = exports.MATERIALIZED_DELIVERY_REPORT_SCOPES = exports.MATERIALIZED_CASH_SOURCE_LIMIT = exports.CASH_KEY_FILTERS = exports.MATERIALIZED_CASH_REPORT_SCOPES = exports.ALL_MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPES = exports.MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM = exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = exports.MATERIALIZED_DISCOUNT_PRICE_OVERRIDE_PREFIX = exports.MATERIALIZED_DISCOUNT_MANUAL_PREFIX = exports.MATERIALIZED_DISCOUNT_SPECIAL_DISCOUNT_ID = exports.MATERIALIZED_DISCOUNT_SOURCE_LIMIT = exports.ALL_MATERIALIZED_DISCOUNT_LEVELS = exports.MATERIALIZED_DISCOUNT_LEVEL_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_ENTRY_KINDS = exports.MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SUB_KINDS = exports.MATERIALIZED_DISCOUNT_SUB_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SLOTS = exports.MATERIALIZED_DISCOUNT_SLOT_ENUM = exports.DISCOUNTS_KEY_FILTERS = exports.MATERIALIZED_DISCOUNT_REPORT_SCOPES = exports.SALES_OVERVIEW_KEY_FILTERS = exports.ALL_MATERIALIZED_REPORT_KEY_FILTERS = exports.MATERIALIZED_REPORT_KEY_FILTER_ENUM = exports.MATERIALIZED_CREDIT_BILLS_SCOPES = exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = exports.ALL_MATERIALIZED_REPORT_WINDOW_KINDS = exports.MATERIALIZED_REPORT_WINDOW_KIND_ENUM = exports.ALL_MATERIALIZED_REPORT_SCOPES = exports.MATERIALIZED_REPORT_SCOPE_ENUM = void 0;
14
- exports.ALL_PAYMENTS_COMPARISON_METRICS = exports.PAYMENTS_COMPARISON_METRIC_ENUM = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_SCHEMA_VERSION = exports.PAYMENTS_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_PAYMENTS_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_SCHEMA_VERSION = exports.HOURLY_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_HOURLY_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_SALES_COMPARISON_METRICS = exports.SALES_COMPARISON_METRIC_ENUM = exports.ALL_SALES_COMPARISON_BASELINES = exports.SALES_COMPARISON_BASELINE_ENUM = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_SCHEMA_VERSION = exports.SALES_COMPARISON_KEY_FILTERS = void 0;
13
+ exports.MATERIALIZED_PREP_TIME_TARGET_ENUM = exports.MATERIALIZED_PREP_TIME_ON_TIME_MAX_DELTA = exports.MATERIALIZED_PREP_TIME_TOP_BUCKET = exports.MATERIALIZED_PREP_TIME_MAX_MINUTES = exports.ALL_MATERIALIZED_PREP_TIME_BUCKET_LABELS = exports.MATERIALIZED_PREP_TIME_BUCKETS = exports.ALL_MATERIALIZED_PREP_TIME_ANCHORS = exports.MATERIALIZED_PREP_TIME_ANCHOR_ENUM = exports.PREP_TIME_KEY_FILTERS = exports.MATERIALIZED_PREP_TIME_REPORT_SCOPES = exports.MATERIALIZED_DELIVERY_AREA_LIMIT = exports.MATERIALIZED_DELIVERY_RIDER_LIMIT = exports.MATERIALIZED_DELIVERY_DISTANCE_BUCKETS = exports.DELIVERY_KEY_FILTERS = exports.MATERIALIZED_DELIVERY_REPORT_SCOPES = exports.MATERIALIZED_CASH_SOURCE_LIMIT = exports.CASH_KEY_FILTERS = exports.MATERIALIZED_CASH_REPORT_SCOPES = exports.ALL_MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPES = exports.MATERIALIZED_REPORT_CREDIT_BILL_EVENT_TYPE_ENUM = exports.MATERIALIZED_CREDIT_SETTLEMENT_PAYMENT_TYPE = exports.MATERIALIZED_DISCOUNT_SOURCE_KEY_PREFIX = exports.MATERIALIZED_DISCOUNT_SOURCE_KEY = exports.ALL_MATERIALIZED_DISCOUNT_RATE_KINDS = exports.MATERIALIZED_DISCOUNT_RATE_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SOURCE_CLASSES = exports.MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM = exports.MATERIALIZED_DISCOUNT_PRICE_OVERRIDE_PREFIX = exports.MATERIALIZED_DISCOUNT_MANUAL_PREFIX = exports.MATERIALIZED_DISCOUNT_SPECIAL_DISCOUNT_ID = exports.MATERIALIZED_DISCOUNT_SOURCE_LIMIT = exports.ALL_MATERIALIZED_DISCOUNT_LEVELS = exports.MATERIALIZED_DISCOUNT_LEVEL_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_ENTRY_KINDS = exports.MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SUB_KINDS = exports.MATERIALIZED_DISCOUNT_SUB_KIND_ENUM = exports.ALL_MATERIALIZED_DISCOUNT_SLOTS = exports.MATERIALIZED_DISCOUNT_SLOT_ENUM = exports.DISCOUNTS_KEY_FILTERS = exports.MATERIALIZED_DISCOUNT_REPORT_SCOPES = exports.SALES_OVERVIEW_KEY_FILTERS = exports.ALL_MATERIALIZED_REPORT_KEY_FILTERS = exports.MATERIALIZED_REPORT_KEY_FILTER_ENUM = exports.MATERIALIZED_CREDIT_BILLS_SCOPES = exports.MATERIALIZED_REPORT_SCOPES_WITH_DAY_INDEX = exports.ALL_MATERIALIZED_REPORT_WINDOW_KINDS = exports.MATERIALIZED_REPORT_WINDOW_KIND_ENUM = exports.ALL_MATERIALIZED_REPORT_SCOPES = exports.MATERIALIZED_REPORT_SCOPE_ENUM = void 0;
14
+ exports.ALL_PAYMENTS_COMPARISON_METRICS = exports.PAYMENTS_COMPARISON_METRIC_ENUM = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_SCHEMA_VERSION = exports.PAYMENTS_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_PAYMENTS_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_PAYMENTS_COMPARISON_REPORTS_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_SCHEMA_VERSION = exports.HOURLY_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_HOURLY_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_HOURLY_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_SALES_COMPARISON_METRICS = exports.SALES_COMPARISON_METRIC_ENUM = exports.ALL_SALES_COMPARISON_BASELINES = exports.SALES_COMPARISON_BASELINE_ENUM = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_SCHEMA_VERSION = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_SCHEMA_VERSION = exports.SALES_COMPARISON_KEY_FILTERS = exports.MATERIALIZED_SALES_COMPARISON_REPORT_SCOPES = exports.MATERIALIZED_TENANT_SALES_COMPARISON_ENTRIES_COLLECTION_NAME = exports.MATERIALIZED_TENANT_SALES_COMPARISON_REPORTS_COLLECTION_NAME = exports.ALL_MATERIALIZED_REPORT_TYPES = exports.MATERIALIZED_REPORT_TYPE_ENUM = exports.ALL_MATERIALIZED_PREP_TIME_TARGETS = void 0;
15
15
  /**
16
16
  * Time-scope of a materialized report document. Every document covers exactly
17
17
  * one tenant × one scope context × one scope value (`scope_field`), and the
@@ -201,8 +201,9 @@ exports.ALL_MATERIALIZED_DISCOUNT_SUB_KINDS = Object.values(MATERIALIZED_DISCOUN
201
201
  * `materialized_tenant_discount_entries`.
202
202
  *
203
203
  * - `DISCOUNT` — a slot on the order or on one item.
204
- * - `FREE_ITEM` — a 100 % item row (also present as a `DISCOUNT` row; the
205
- * drill-down decides which view lists it).
204
+ * - `FREE_ITEM` — a 100 % item row. It is a SINGLE row of this kind (not
205
+ * duplicated as a DISCOUNT row: `entry_key` is the row's
206
+ * identity, so a duplicate would collide in a period merge).
206
207
  * - `COMPLIMENTARY` — a `COMPLIMENTARY` payment (no discount slot required).
207
208
  */
208
209
  var MATERIALIZED_DISCOUNT_ENTRY_KIND_ENUM;
@@ -233,6 +234,86 @@ exports.MATERIALIZED_DISCOUNT_SOURCE_LIMIT = 12;
233
234
  exports.MATERIALIZED_DISCOUNT_SPECIAL_DISCOUNT_ID = 'SPECIAL_DISCOUNT';
234
235
  exports.MATERIALIZED_DISCOUNT_MANUAL_PREFIX = 'MANUAL_';
235
236
  exports.MATERIALIZED_DISCOUNT_PRICE_OVERRIDE_PREFIX = 'MANUAL_SINGLE_';
237
+ /**
238
+ * SOURCE CLASS of a discount row — the grouping the "By discount" view uses.
239
+ *
240
+ * This is a REPORTING taxonomy, not a new write-path discriminator: every
241
+ * value is derived from the row (slot + id shape + reason + item id), so it
242
+ * can be rebuilt from historical entry documents at any time.
243
+ *
244
+ * - `COLLECTION` — a `discounts` collection document (order- or item-level).
245
+ * - `MANUAL` — a quick/custom amount at the order or item level.
246
+ * - `PAYMENT_TYPE` — a discount configured on a payment type. It looks like a
247
+ * `MANUAL_*` row, but its `special_discount_reason` is
248
+ * `Discount applied for <payment type>`; grouping it as a
249
+ * manual discount would hide which tender drove it.
250
+ * - `PRICE_OVERRIDE` — an item price edit (`MANUAL_SINGLE_*`).
251
+ * - `CATALOG_AUTO` — the item's own catalog `discount_amount`, written with
252
+ * the ITEM id as `special_discount_id` (or the
253
+ * `SPECIAL_DISCOUNT` sentinel). This is why the source
254
+ * classifier compares the id to the row's `item_id`: a
255
+ * catalog id is usually a 24-hex ObjectId and would
256
+ * otherwise be mistaken for a collection discount.
257
+ * - `LOYALTY` — offers, gift cards and wallet cashback (loyalty slot).
258
+ * - `VOUCHER` — voucher / voucher-linked offer (voucher slot).
259
+ * - `COMPLIMENTARY` — a `COMPLIMENTARY` tender, fully or partially covering
260
+ * the order. NOT a discount: never added to the discount
261
+ * total or share.
262
+ * - `UNATTRIBUTED` — money the row's slots cannot explain.
263
+ */
264
+ var MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM;
265
+ (function (MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM) {
266
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["COLLECTION"] = "COLLECTION";
267
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["MANUAL"] = "MANUAL";
268
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["PAYMENT_TYPE"] = "PAYMENT_TYPE";
269
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["PRICE_OVERRIDE"] = "PRICE_OVERRIDE";
270
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["CATALOG_AUTO"] = "CATALOG_AUTO";
271
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["LOYALTY"] = "LOYALTY";
272
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["VOUCHER"] = "VOUCHER";
273
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["COMPLIMENTARY"] = "COMPLIMENTARY";
274
+ MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM["UNATTRIBUTED"] = "UNATTRIBUTED";
275
+ })(MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM || (exports.MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM = MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM = {}));
276
+ exports.ALL_MATERIALIZED_DISCOUNT_SOURCE_CLASSES = Object.values(MATERIALIZED_DISCOUNT_SOURCE_CLASS_ENUM);
277
+ /**
278
+ * Rate shape of a source row, for the "Avg rate" column:
279
+ * `PERCENTAGE` rows show their average %, `FIXED` rows show "—" (a fixed
280
+ * amount has no rate), and `MIXED` rows show "mixed".
281
+ */
282
+ var MATERIALIZED_DISCOUNT_RATE_KIND_ENUM;
283
+ (function (MATERIALIZED_DISCOUNT_RATE_KIND_ENUM) {
284
+ MATERIALIZED_DISCOUNT_RATE_KIND_ENUM["PERCENTAGE"] = "PERCENTAGE";
285
+ MATERIALIZED_DISCOUNT_RATE_KIND_ENUM["FIXED"] = "FIXED";
286
+ MATERIALIZED_DISCOUNT_RATE_KIND_ENUM["MIXED"] = "MIXED";
287
+ })(MATERIALIZED_DISCOUNT_RATE_KIND_ENUM || (exports.MATERIALIZED_DISCOUNT_RATE_KIND_ENUM = MATERIALIZED_DISCOUNT_RATE_KIND_ENUM = {}));
288
+ exports.ALL_MATERIALIZED_DISCOUNT_RATE_KINDS = Object.values(MATERIALIZED_DISCOUNT_RATE_KIND_ENUM);
289
+ /**
290
+ * Source keys that are ONE row regardless of the individual amounts/rates.
291
+ * Manual order discounts are deliberately ONE source (`manual:order`): the id
292
+ * they carry is generated from the amount (`MANUAL_50%`, `MANUAL_Rs 500`), so
293
+ * keying on it would create a new "source" for every amount. The drill-down
294
+ * keeps every individual row/rate.
295
+ */
296
+ exports.MATERIALIZED_DISCOUNT_SOURCE_KEY = {
297
+ MANUAL_ORDER: 'manual:order',
298
+ MANUAL_ITEM: 'manual:item',
299
+ PRICE_OVERRIDE_ITEM: 'price_override:item',
300
+ CATALOG_AUTO: 'catalog:auto',
301
+ WALLET_CASHBACK: 'loyalty:wallet_cashback',
302
+ COMPLIMENTARY_FULL: 'complimentary:full',
303
+ COMPLIMENTARY_PARTIAL: 'complimentary:partial',
304
+ // Defensive invalid-data bucket only: the current close always writes
305
+ // `complimentary_full`. This is NOT a legacy compatibility path.
306
+ COMPLIMENTARY_UNKNOWN: 'complimentary:unknown',
307
+ UNATTRIBUTED: 'unattributed',
308
+ };
309
+ /** Prefixes of the parameterised source keys (`discount:<id>` etc.). */
310
+ exports.MATERIALIZED_DISCOUNT_SOURCE_KEY_PREFIX = {
311
+ DISCOUNT: 'discount:',
312
+ LOYALTY_OFFER: 'loyalty:offer:',
313
+ LOYALTY_GIFT_CARD: 'loyalty:gift_card:',
314
+ VOUCHER: 'voucher:',
315
+ PAYMENT_TYPE: 'payment_type:',
316
+ };
236
317
  /**
237
318
  * Payment-type label used by the frontend report formatter for the derived
238
319
  * credit-settlement line in a collection day's payments breakdown (a
@@ -4,6 +4,8 @@ export * from './materialized-discount-accumulator-helpers';
4
4
  export * from './materialized-discount-classification-helpers';
5
5
  export * from './materialized-discount-close-day-helpers';
6
6
  export * from './materialized-discount-compile-helpers';
7
+ export * from './materialized-discount-details-helpers';
8
+ export * from './materialized-discount-source-helpers';
7
9
  export * from './materialized-hourly-comparison-close-day-helpers';
8
10
  export * from './materialized-hourly-comparison-compile-helpers';
9
11
  export * from './materialized-hourly-comparison-selection-helpers';
@@ -36,6 +38,7 @@ export * from './tenant-payments-comparison-formatter';
36
38
  export * from './tenant-sales-comparison-formatter';
37
39
  export * from './tenant-sales-overview-close-day-helpers';
38
40
  export * from './tenant-discount-formatter';
41
+ export * from './tenant-discount-source-formatter';
39
42
  export * from './tenant-cash-in-out-formatter';
40
43
  export * from './tenant-delivery-formatter';
41
44
  export * from './tenant-prep-time-formatter';
@@ -20,6 +20,8 @@ __exportStar(require("./materialized-discount-accumulator-helpers"), exports);
20
20
  __exportStar(require("./materialized-discount-classification-helpers"), exports);
21
21
  __exportStar(require("./materialized-discount-close-day-helpers"), exports);
22
22
  __exportStar(require("./materialized-discount-compile-helpers"), exports);
23
+ __exportStar(require("./materialized-discount-details-helpers"), exports);
24
+ __exportStar(require("./materialized-discount-source-helpers"), exports);
23
25
  __exportStar(require("./materialized-hourly-comparison-close-day-helpers"), exports);
24
26
  __exportStar(require("./materialized-hourly-comparison-compile-helpers"), exports);
25
27
  __exportStar(require("./materialized-hourly-comparison-selection-helpers"), exports);
@@ -52,6 +54,7 @@ __exportStar(require("./tenant-payments-comparison-formatter"), exports);
52
54
  __exportStar(require("./tenant-sales-comparison-formatter"), exports);
53
55
  __exportStar(require("./tenant-sales-overview-close-day-helpers"), exports);
54
56
  __exportStar(require("./tenant-discount-formatter"), exports);
57
+ __exportStar(require("./tenant-discount-source-formatter"), exports);
55
58
  __exportStar(require("./tenant-cash-in-out-formatter"), exports);
56
59
  __exportStar(require("./tenant-delivery-formatter"), exports);
57
60
  __exportStar(require("./tenant-prep-time-formatter"), exports);
@@ -40,6 +40,36 @@ export interface IAccumulateOrderDiscountsResult {
40
40
  /** Orders the accumulator would count (has ANY discount or a comp payment). */
41
41
  has_discount: boolean;
42
42
  }
43
+ /** One comp tender's share of an order's coverage. */
44
+ export interface IComplimentaryPaymentShare {
45
+ payment_id: string | null;
46
+ covered_amount: number;
47
+ note: string | null;
48
+ }
49
+ /** Full/partial classification of an order's COMPLIMENTARY tenders. */
50
+ export interface IComplimentaryOrderClassification {
51
+ /** Every tender is COMPLIMENTARY AND covers the order. */
52
+ full: boolean;
53
+ /** Σ comp `amount_paid`. */
54
+ covered_amount: number;
55
+ /** `grand_total` (fallback `amount_earned`) used for the full/partial test. */
56
+ order_amount: number;
57
+ payments: IComplimentaryPaymentShare[];
58
+ }
59
+ /**
60
+ * Classifies an order's COMPLIMENTARY tenders. Returns null when there is none.
61
+ *
62
+ * A PARTIAL comp has two real shapes in the POS:
63
+ * 1. one COMPLIMENTARY payment with `amount_paid < amount_due` (the "pay
64
+ * partially" flow, no other tender); or
65
+ * 2. a COMPLIMENTARY payment beside another settled tender.
66
+ * Both are partial. "All payments are COMPLIMENTARY" alone would call shape 1
67
+ * full, so the amount is part of the test too.
68
+ *
69
+ * Used by the current close for every comp row. Pre-release has no legacy
70
+ * comp-row inference path.
71
+ */
72
+ export declare function classifyComplimentaryOrder(order: IOrder | null | undefined): IComplimentaryOrderClassification | null;
43
73
  /** The line label of a punch hour (null when the hour is unknown). */
44
74
  export declare const toDiscountHourLabel: (localDate: string, hour: number | null) => string | null;
45
75
  /**