@managesome/eposmatic-toolkit 0.4.7 → 0.4.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +33 -0
  2. package/esm/helpers/materialized-reports/index.js +1 -0
  3. package/esm/helpers/materialized-reports/materialized-credit-bills-helpers.js +982 -0
  4. package/esm/helpers/materialized-reports/materialized-reports-selection-helpers.js +276 -33
  5. package/esm/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +327 -41
  6. package/esm/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  7. package/esm/helpers/materialized-reports/tenant-sales-overview-helpers.js +118 -235
  8. package/esm/schemas/models/index.js +1 -0
  9. package/esm/schemas/models/materialized_credit_bills.js +265 -0
  10. package/esm/schemas/models/materialized_tenant_reports_iterations.js +13 -0
  11. package/esm/schemas/models/materialized_tenant_sales_overview_reports.js +39 -97
  12. package/esm/schemas/types/index.js +1 -0
  13. package/esm/schemas/types/materialized_credit_bills.js +1 -0
  14. package/lib/constants/MATERIALIZED_REPORTS.d.ts +28 -2
  15. package/lib/constants/MATERIALIZED_REPORTS.js +34 -1
  16. package/lib/helpers/materialized-reports/index.d.ts +1 -0
  17. package/lib/helpers/materialized-reports/index.js +1 -0
  18. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.d.ts +307 -0
  19. package/lib/helpers/materialized-reports/materialized-credit-bills-helpers.js +1003 -0
  20. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.d.ts +36 -2
  21. package/lib/helpers/materialized-reports/materialized-reports-selection-helpers.js +278 -34
  22. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.d.ts +66 -8
  23. package/lib/helpers/materialized-reports/tenant-sales-overview-close-day-helpers.js +326 -40
  24. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.d.ts +18 -2
  25. package/lib/helpers/materialized-reports/tenant-sales-overview-formatter.js +72 -11
  26. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.d.ts +46 -37
  27. package/lib/helpers/materialized-reports/tenant-sales-overview-helpers.js +119 -238
  28. package/lib/helpers/types/materialized-reports-apis.d.ts +32 -5
  29. package/lib/schemas/models/index.d.ts +1 -0
  30. package/lib/schemas/models/index.js +1 -0
  31. package/lib/schemas/models/materialized_credit_bills.d.ts +337 -0
  32. package/lib/schemas/models/materialized_credit_bills.js +268 -0
  33. package/lib/schemas/models/materialized_tenant_reports_iterations.d.ts +20 -6
  34. package/lib/schemas/models/materialized_tenant_reports_iterations.js +14 -1
  35. package/lib/schemas/models/materialized_tenant_sales_overview_reports.d.ts +37 -165
  36. package/lib/schemas/models/materialized_tenant_sales_overview_reports.js +40 -98
  37. package/lib/schemas/types/index.d.ts +1 -0
  38. package/lib/schemas/types/index.js +1 -0
  39. package/lib/schemas/types/materialized_credit_bills.d.ts +139 -0
  40. package/lib/schemas/types/materialized_credit_bills.js +2 -0
  41. package/lib/schemas/types/materialized_tenant_sales_overview_reports.d.ts +32 -77
  42. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.d.ts +1 -0
  43. package/lib/tests/materialized-reports/materialized-credit-bills-helpers.test.js +715 -0
  44. package/lib/tests/materialized-reports/materialized-reports-selection-helpers.test.js +96 -0
  45. package/lib/tests/materialized-reports/materialized-tenant-reports-iterations-schema.test.js +9 -0
  46. package/lib/tests/materialized-reports/materialized-tenant-sales-overview-reports-schema.test.js +23 -24
  47. package/lib/tests/materialized-reports/tenant-sales-overview-close-day-helpers.test.js +327 -22
  48. package/lib/tests/materialized-reports/tenant-sales-overview-formatter-aggregated.test.js +27 -2
  49. package/lib/tests/materialized-reports/tenant-sales-overview-formatter.test.js +12 -27
  50. package/lib/tests/materialized-reports/tenant-sales-overview-helpers.test.js +79 -146
  51. package/package.json +1 -1
@@ -34,7 +34,16 @@ const keyMetrics = (over = {}) => ({
34
34
  TOTAL_SALES: { orders: orderMetric(), payments: [] },
35
35
  AMOUNT_COLLECTED: { orders: orderMetric() },
36
36
  CREDIT_BILLS: {
37
- issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0 },
37
+ issued: {
38
+ count: 0,
39
+ amount: 0,
40
+ settled_count: 0,
41
+ settled_amount: 0,
42
+ outstanding_count: 0,
43
+ outstanding_amount: 0,
44
+ outstanding_now_count: 0,
45
+ outstanding_now_amount: 0,
46
+ },
38
47
  received: { count: 0, amount: 0 },
39
48
  },
40
49
  ...over,
@@ -42,6 +51,8 @@ const keyMetrics = (over = {}) => ({
42
51
  const makeRecord = (over = {}) => ({
43
52
  tenant_id: 'tenant-a',
44
53
  brand_id: 'brand-1',
54
+ max_iteration: 2,
55
+ max_updated_at: new Date('2026-09-03T23:00:00.000Z'),
45
56
  matched_documents: 3,
46
57
  first_scope_field: '2026-09-01',
47
58
  last_scope_field: '2026-09-03',
@@ -54,7 +65,16 @@ const makeRecord = (over = {}) => ({
54
65
  },
55
66
  AMOUNT_COLLECTED: { orders: orderMetric({ count: 4, gross_amount: 200000 }) },
56
67
  CREDIT_BILLS: {
57
- issued: { count: 1, amount: 100000, settled_count: 1, settled_amount: 100000 },
68
+ issued: {
69
+ count: 1,
70
+ amount: 100000,
71
+ settled_count: 1,
72
+ settled_amount: 100000,
73
+ outstanding_count: 0,
74
+ outstanding_amount: 0,
75
+ outstanding_now_count: 0,
76
+ outstanding_now_amount: 0,
77
+ },
58
78
  received: { count: 1, amount: 5000 },
59
79
  },
60
80
  }),
@@ -103,7 +123,12 @@ describe('getFormattedTenantSalesOverviewAggregatedReporting', () => {
103
123
  expect(page?.credit_bills).toEqual({
104
124
  issued: { count: 1, amount: 1000, settled_count: 1, settled_amount: 1000 },
105
125
  received: { count: 1, amount: 50 },
126
+ outstanding_count: 0,
106
127
  outstanding_amount: 0,
128
+ outstanding_now_count: 0,
129
+ outstanding_now_amount: 0,
130
+ collected_at_issue_count: 0,
131
+ collected_at_issue_amount: 0,
107
132
  });
108
133
  // slice-derived sections are never available on aggregated records
109
134
  expect(page?.weekday).toBeNull();
@@ -28,11 +28,11 @@ const makePayment = (over = {}) => ({
28
28
  card_charges: 0,
29
29
  ...over,
30
30
  });
31
- // Ledger counters are recomputed from the itemized bills during the merge —
32
- // fixtures only need to carry the bills.
33
- const makeCreditBills = (issuedBills = [], receivedBills = []) => ({
34
- issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0, bills: issuedBills },
35
- received: { count: 0, amount: 0, bills: receivedBills },
31
+ // Credit-bill counters are stored directly on the documents (the itemized
32
+ // ledger lives in `materialized_tenant_credit_bills`) — fixtures set them explicitly.
33
+ const makeCreditBills = (issued = {}, received = {}) => ({
34
+ issued: { count: 0, amount: 0, settled_count: 0, settled_amount: 0, ...issued },
35
+ received: { count: 0, amount: 0, ...received },
36
36
  });
37
37
  const makeKeyMetrics = (orders, over = {}) => ({
38
38
  [constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: { orders, payments: [] },
@@ -57,22 +57,6 @@ const makeDoc = (over = {}) => ({
57
57
  updatedAt: new Date('2026-10-01T10:00:00.000Z'),
58
58
  ...over,
59
59
  });
60
- const issuedBill = {
61
- order_id: 'o1',
62
- payment_id: 'p1',
63
- amount: 11000,
64
- received_amount: 0,
65
- issued_at: new Date('2026-10-01T18:00:00.000Z'),
66
- settled_at: null,
67
- };
68
- // Same receipt recorded in two documents — the merge must count it ONCE.
69
- const receivedBill = {
70
- order_id: 'o9',
71
- payment_id: 'p9',
72
- amount: 11000,
73
- received_amount: 11000,
74
- issued_local_date: '2026-09-30',
75
- };
76
60
  const docA = makeDoc({
77
61
  _id: 'docA',
78
62
  tenant_id: 't1',
@@ -99,7 +83,7 @@ const docA = makeDoc({
99
83
  orders: makeOrderMetric({ count: 1, gross_amount: 9000 }),
100
84
  payments: [],
101
85
  },
102
- [constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: makeCreditBills([issuedBill], [receivedBill]),
86
+ [constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: makeCreditBills({ count: 1, amount: 11000 }, { count: 1, amount: 11000 }),
103
87
  },
104
88
  'CANCELLED:POS_WALK-IN': makeKeyMetrics(makeOrderMetric({ count: 1, gross_amount: 5000 })),
105
89
  },
@@ -121,9 +105,9 @@ const docB = makeDoc({
121
105
  },
122
106
  [constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: makeCreditBills(),
123
107
  },
124
- // Same receipt under the SAME key as in docA — the overlapping-compile case
125
- // (e.g. a day document and a period document both carrying the key); the
126
- // merge de-duplicates it by (order_id, payment_id).
108
+ // The same key on another tenant's document — credit counters SUM (reads
109
+ // never mix overlapping scopes; the aggregation selects non-overlapping
110
+ // scope documents, so per-document counters never double-count a bill).
127
111
  'COMPLETED:POS_WALK-IN': {
128
112
  [constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES]: {
129
113
  orders: makeOrderMetric({ count: 0, gross_amount: 0 }),
@@ -133,7 +117,7 @@ const docB = makeDoc({
133
117
  orders: makeOrderMetric({ count: 0, gross_amount: 0 }),
134
118
  payments: [],
135
119
  },
136
- [constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: makeCreditBills([], [receivedBill]),
120
+ [constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: makeCreditBills(),
137
121
  },
138
122
  },
139
123
  });
@@ -185,7 +169,8 @@ describe('getFormattedTenantSalesOverviewReporting', () => {
185
169
  expect(settlement.derived).toBe(true);
186
170
  expect(settlement.count).toBe(1); // de-duplicated across documents
187
171
  expect(settlement.gross_amount).toBe(110);
188
- // Credit-bill ledger (counters recomputed from the de-duplicated bills).
172
+ // Credit-bill counters (summed per key across the selected documents;
173
+ // the derived settlement line counts the `received` bucket once).
189
174
  expect(data.credit_bills.issued).toEqual({
190
175
  count: 1,
191
176
  amount: 110,
@@ -132,6 +132,7 @@ describe('convertOrdersToMaterializedTenantSalesOverviewReports — live parity
132
132
  expect(doc.tenant_id).toBe(BASHA);
133
133
  expect(doc.brand_id).toBe(BRAND);
134
134
  expect(doc.sale_type_key_filters).toEqual(MATERIALIZED_REPORTS_1.SALES_OVERVIEW_KEY_FILTERS);
135
+ // Pre-release: every schema change folds into version 1 (no migration).
135
136
  expect(doc.schema_version).toBe(1);
136
137
  if (doc.scope_context !== MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_HOUR &&
137
138
  doc.scope_context !== MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE) {
@@ -140,7 +141,8 @@ describe('convertOrdersToMaterializedTenantSalesOverviewReports — live parity
140
141
  }
141
142
  }
142
143
  expect(dateDoc.day_index).toBe(ENUMS_1.DAY_INDEX_ENUM.WED);
143
- expect(result.received_payments).toEqual([]);
144
+ expect(result.credit_bill_issues).toEqual([]);
145
+ expect(result.credit_bill_events).toEqual([]);
144
146
  });
145
147
  it('reproduces the live TOTAL_SALES / AMOUNT_COLLECTED facets for the day (cancelled keys excluded)', () => {
146
148
  const reference = (0, sales_overview_reference_1.computeSalesOverviewReference)(allOrders, {
@@ -278,7 +280,7 @@ describe('credit-bill lifecycle (synthetic PAY_LATER orders)', () => {
278
280
  expect(metrics).toBeDefined();
279
281
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES].orders.count).toBe(1);
280
282
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.count).toBe(1);
281
- expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.bills[0]).toMatchObject({
283
+ expect(issueCompile.credit_bill_issues[0]).toMatchObject({
282
284
  order_id: 'order-credit-1',
283
285
  payment_id: 'pay-1',
284
286
  amount: 1200,
@@ -298,41 +300,44 @@ describe('credit-bill lifecycle (synthetic PAY_LATER orders)', () => {
298
300
  });
299
301
  backfill.createdAt = new Date('2026-09-29T20:10:00.000Z'); // punch time ≠ collection time
300
302
  const backfillCompile = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(ISSUE_DAY, [backfill], { brandId: BRAND }));
301
- const backfillDateDoc = backfillCompile.materializedReports.find((doc) => doc.scope_context === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE);
302
- const bill = getKeyMetrics(backfillDateDoc, 'COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued
303
- .bills[0];
304
- expect(bill?.issued_at).toEqual(new Date('2026-09-29T20:10:00.000Z'));
305
- expect(bill?.settled_at).toEqual(new Date('2026-09-30T14:30:00.000Z'));
306
- expect(bill?.received_amount).toBe(1200);
307
- });
308
- it('compiles the collection day as received_payments only (no sales)', () => {
309
- expect(collectCompile.received_payments).toHaveLength(1);
310
- expect(collectCompile.received_payments[0]).toMatchObject({
303
+ const row = backfillCompile.credit_bill_issues[0];
304
+ expect(row?.issued_at).toEqual(new Date('2026-09-29T20:10:00.000Z'));
305
+ expect(row?.settled_at).toEqual(new Date('2026-09-30T14:30:00.000Z'));
306
+ expect(row?.received_amount).toBe(1200);
307
+ });
308
+ it('compiles the collection day as receipt events only (no sales)', () => {
309
+ expect(collectCompile.credit_bill_events).toHaveLength(1);
310
+ expect(collectCompile.credit_bill_events[0]).toMatchObject({
311
311
  order_id: 'order-credit-1',
312
312
  payment_id: 'pay-1',
313
313
  amount: 1200,
314
- received_amount: 1200,
315
- credit_note: 'CN-2026-09-30',
314
+ candidate_cumulative: 1200,
316
315
  issued_local_date: ISSUE_DAY,
317
316
  });
317
+ expect(collectCompile.credit_bill_events[0].event.credit_note).toBe('CN-2026-09-30');
318
318
  const metrics = getKeyMetrics(collectDateDoc, 'COMPLETED:POS_WALK-IN');
319
319
  expect(metrics).toBeDefined();
320
320
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES].orders.count).toBe(0);
321
321
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].received.count).toBe(1);
322
- expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].received.amount).toBe(1200);
322
+ // The compile is order-pure: `received_delta` is RESOLVED by the
323
+ // close-day plan against the stored row — the compile's counter stays 0
324
+ // until resolution (the plan suite covers resolution).
325
+ expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].received.amount).toBe(0);
326
+ expect(collectCompile.credit_bill_events[0].event).toMatchObject({
327
+ received_delta: 0,
328
+ event_local_date: DAY,
329
+ });
323
330
  });
324
- it('patches the issue-day ledger through updateMaterializedTenantSalesOverviewReport', () => {
331
+ it('patches the issue-day settled counters through updateMaterializedTenantSalesOverviewReport', () => {
325
332
  const computedAt = new Date('2026-09-30T23:00:00.000Z');
326
- const patched = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(issueDateDoc, { received_payments: collectCompile.received_payments }, { computedAt }));
333
+ const patched = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(issueDateDoc, { settled_credit_bills: [{ key: 'COMPLETED:POS_WALK-IN', amount: 1200 }] }, { computedAt }));
327
334
  const metrics = getKeyMetrics(patched, 'COMPLETED:POS_WALK-IN');
328
335
  const issued = metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued;
329
336
  expect(issued?.count).toBe(1);
330
- expect(issued?.bills[0].received_amount).toBe(1200);
331
- expect(issued?.bills[0].credit_note).toBe('CN-2026-09-30');
332
- expect(issued?.bills[0].settled_at).toEqual(new Date('2026-09-30T14:30:00.000Z')); // true collection timestamp (order_settled_at)
333
337
  expect(issued?.settled_count).toBe(1);
334
338
  expect(issued?.settled_amount).toBe(1200);
335
339
  expect(patched.iteration).toBe(2); // ledger changed → versioned write (history row appended by the caller)
340
+ expect(patched.updatedAt).toEqual(computedAt);
336
341
  // gross / order numbers stay untouched
337
342
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES].orders.gross_amount).toBe(1200);
338
343
  });
@@ -358,11 +363,9 @@ describe('credit-bill lifecycle (synthetic PAY_LATER orders)', () => {
358
363
  const settledRuleCompile = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(ISSUE_DAY, [paidButPending, settledButUnderpaid], {
359
364
  brandId: BRAND,
360
365
  }));
361
- const settledRuleDoc = settledRuleCompile.materializedReports.find((doc) => doc.scope_context === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE);
362
- const bills = getKeyMetrics(settledRuleDoc, 'COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued
363
- .bills;
364
- expect(bills?.find((bill) => bill.order_id === 'order-credit-2')?.settled_at).toEqual(new Date('2026-09-30T11:00:00.000Z'));
365
- expect(bills?.find((bill) => bill.order_id === 'order-credit-3')?.settled_at).toBeNull();
366
+ const rows = settledRuleCompile.credit_bill_issues;
367
+ expect(rows.find((row) => row.order_id === 'order-credit-2')?.settled_at).toEqual(new Date('2026-09-30T11:00:00.000Z'));
368
+ expect(rows.find((row) => row.order_id === 'order-credit-3')?.settled_at).toBeNull();
366
369
  });
367
370
  it('rejects un-keyable PAY_LATER payments (no payment_id and no subdocument _id)', () => {
368
371
  const unkeyable = makePayLaterOrder({
@@ -389,10 +392,7 @@ describe('credit-bill lifecycle (synthetic PAY_LATER orders)', () => {
389
392
  withSubdocId.payments[0].payment_id = null;
390
393
  withSubdocId.payments[0]._id = 'pay-subdoc-1';
391
394
  const withIdCompile = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(ISSUE_DAY, [withSubdocId], { brandId: BRAND }));
392
- const withIdDoc = withIdCompile.materializedReports.find((doc) => doc.scope_context === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE);
393
- const bill = getKeyMetrics(withIdDoc, 'COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued
394
- .bills[0];
395
- expect(bill?.payment_id).toBe('pay-subdoc-1');
395
+ expect(withIdCompile.credit_bill_issues[0]?.payment_id).toBe('pay-subdoc-1');
396
396
  });
397
397
  it('buckets collection events by the settlement hour, not the punch hour', () => {
398
398
  const collectOrder = makePayLaterOrder({
@@ -429,9 +429,7 @@ describe('credit-bill lifecycle (synthetic PAY_LATER orders)', () => {
429
429
  bare.order_settled_at_mins = undefined;
430
430
  const computedAt = new Date('2026-10-01T03:00:00.000Z');
431
431
  const bareCompile = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(ISSUE_DAY, [bare], { brandId: BRAND, computedAt }));
432
- const bareDoc = bareCompile.materializedReports.find((doc) => doc.scope_context === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE);
433
- const bill = getKeyMetrics(bareDoc, 'COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.bills[0];
434
- expect(bill?.issued_at).toEqual(computedAt);
432
+ expect(bareCompile.credit_bill_issues[0]?.issued_at).toEqual(computedAt);
435
433
  });
436
434
  it('converts the JSON document to a mongoose (BSON) document', () => {
437
435
  const hydrated = (0, tenant_sales_overview_helpers_1.convertMaterializedTenantSalesOverviewReportJsonToBson)(issueDateDoc);
@@ -439,24 +437,39 @@ describe('credit-bill lifecycle (synthetic PAY_LATER orders)', () => {
439
437
  expect(hydrated.get('sale_type_metrics')).toBeInstanceOf(Map);
440
438
  const metrics = hydrated.get('sale_type_metrics');
441
439
  const issued = metrics.get('COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued;
442
- expect(issued?.bills[0].received_amount).toBe(0);
443
- expect(issued?.bills[0].issued_at).toBeInstanceOf(Date);
440
+ expect(issued?.count).toBe(1);
441
+ expect(issued?.amount).toBe(1200);
444
442
  const hydratedCollect = (0, tenant_sales_overview_helpers_1.convertMaterializedTenantSalesOverviewReportJsonToBson)(collectDateDoc);
445
443
  const collectedMetrics = hydratedCollect.get('sale_type_metrics');
446
444
  const received = collectedMetrics.get('COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].received;
447
- expect(received?.bills[0].received_amount).toBe(1200);
448
- expect(received?.bills[0].credit_note).toBe('CN-2026-09-30');
445
+ expect(received?.count).toBe(1);
446
+ expect(received?.amount).toBe(0); // resolved by the close-day plan, not the order-pure compile
449
447
  });
450
448
  });
451
- describe('sumMaterializedTenantSalesOverviewReports', () => {
452
- const makeIssuedBill = (receivedAmount) => ({
453
- order_id: 'order-1',
454
- payment_id: 'pay-1',
455
- amount: 1000,
456
- received_amount: receivedAmount,
457
- issued_at: new Date('2026-09-28T10:00:00.000Z'),
458
- settled_at: null,
449
+ describe('credit-bill receipts stay out of the AMOUNT_COLLECTED slot (F7)', () => {
450
+ it('excludes PAY_LATER-collected money from the slot (backfill ≡ incremental)', () => {
451
+ const collectedLater = makePayLaterOrder({
452
+ orderId: 'bill-f7',
453
+ localDate: DAY,
454
+ amountDue: 1000,
455
+ amountPaid: 1000,
456
+ paymentStatus: constants_1.PAYMENT_STATUS_ENUM.SETTLED,
457
+ settledAt: '2026-10-01T09:00:00.000Z',
458
+ updatedAt: '2026-10-01T09:00:00.000Z',
459
+ });
460
+ const compile = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(DAY, [collectedLater], { brandId: BRAND }));
461
+ const dateDoc = compile.materializedReports.find((doc) => doc.scope_context === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE);
462
+ const metrics = getKeyMetrics(expectNonNull(dateDoc), 'COMPLETED:POS_WALK-IN');
463
+ // Sales still count, but the collected credit money must never appear in
464
+ // the collected slot — it is represented by the receipt events instead.
465
+ expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES].orders.count).toBe(1);
466
+ expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED]).toEqual({
467
+ orders: zeroOrderMetric(),
468
+ payments: [],
469
+ });
459
470
  });
471
+ });
472
+ describe('sumMaterializedTenantSalesOverviewReports', () => {
460
473
  const makeReport = (args) => ({
461
474
  _id: 'id',
462
475
  tenant_id: 'z2-isb',
@@ -483,14 +496,8 @@ describe('sumMaterializedTenantSalesOverviewReports', () => {
483
496
  },
484
497
  [constants_1.REPORT_SALE_TYPE_ENUM.AMOUNT_COLLECTED]: { orders: zeroOrderMetric(), payments: [] },
485
498
  [constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]: {
486
- issued: {
487
- count: 1,
488
- amount: 1000,
489
- settled_count: 0,
490
- settled_amount: args.issuedReceipt,
491
- bills: [makeIssuedBill(args.issuedReceipt)],
492
- },
493
- received: { count: 0, amount: 0, bills: [] },
499
+ issued: { count: 1, amount: 1000, settled_count: 0, settled_amount: 0 },
500
+ received: { count: 0, amount: 0 },
494
501
  },
495
502
  },
496
503
  },
@@ -531,9 +538,14 @@ describe('sumMaterializedTenantSalesOverviewReports', () => {
531
538
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES].orders.count).toBe(5);
532
539
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES].orders.gross_amount).toBe(5000);
533
540
  expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.TOTAL_SALES].payments[0].gross_amount).toBe(5000);
534
- // the same bill compiled by both days de-dupes; counters recompute from bills
535
- expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.count).toBe(1);
536
- expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.settled_amount).toBe(400);
541
+ // Credit counters SUM per key: reads select non-overlapping scope docs,
542
+ // so each document's counters contribute exactly once (the old bill-level
543
+ // de-dupe retired with the itemized arrays).
544
+ expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.count).toBe(2);
545
+ // F6 pin: settled counters count only FULLY settled bills — the fixtures
546
+ // carry unsettled bills (settled_at null) → zero.
547
+ expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.settled_count).toBe(0);
548
+ expect(metrics?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued.settled_amount).toBe(0);
537
549
  expect(merged.source_watermark).toEqual(new Date('2026-09-28T10:00:00.000Z'));
538
550
  });
539
551
  it('returns null for invalid sum inputs (never throws)', () => {
@@ -560,7 +572,8 @@ describe('empty-day compile + update additions', () => {
560
572
  brandId: BRAND,
561
573
  }));
562
574
  expect(result.materializedReports).toHaveLength(7);
563
- expect(result.received_payments).toEqual([]);
575
+ expect(result.credit_bill_issues).toEqual([]);
576
+ expect(result.credit_bill_events).toEqual([]);
564
577
  for (const doc of result.materializedReports) {
565
578
  expect(doc.sale_type_metrics).toEqual({});
566
579
  expect(doc.source_watermark).toBeInstanceOf(Date);
@@ -656,21 +669,9 @@ describe('subtract + versioned reconcile (iteration bump)', () => {
656
669
  count: args.billReceived != null ? 1 : 0,
657
670
  amount: args.billReceived != null ? 1000 : 0,
658
671
  settled_count: 0,
659
- settled_amount: args.billReceived ?? 0,
660
- bills: args.billReceived != null
661
- ? [
662
- {
663
- order_id: 'order-1',
664
- payment_id: 'pay-1',
665
- amount: 1000,
666
- received_amount: args.billReceived,
667
- issued_at: new Date('2026-09-28T10:00:00.000Z'),
668
- settled_at: null,
669
- },
670
- ]
671
- : [],
672
+ settled_amount: 0,
672
673
  },
673
- received: { count: 0, amount: 0, bills: [] },
674
+ received: { count: 0, amount: 0 },
674
675
  },
675
676
  },
676
677
  },
@@ -779,7 +780,7 @@ describe('subtract + versioned reconcile (iteration bump)', () => {
779
780
  expect(updated.scope_context).toBe(MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE);
780
781
  expect(updated.iteration).toBe(2);
781
782
  });
782
- it('versions a ledger-changing received-payment patch (and skips no-op replays)', () => {
783
+ it('versions a settled-counter patch — a DELTA the planner emits once per transition', () => {
783
784
  const existing = report({
784
785
  scopeContext: MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE,
785
786
  scopeField: '2026-09-28',
@@ -788,88 +789,20 @@ describe('subtract + versioned reconcile (iteration bump)', () => {
788
789
  billReceived: 0,
789
790
  });
790
791
  const computedAt = new Date('2026-09-30T23:00:00.000Z');
791
- const patched = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(existing, {
792
- received_payments: [
793
- {
794
- order_id: 'order-1',
795
- payment_id: 'pay-1',
796
- amount: 1000,
797
- received_amount: 1000,
798
- issued_local_date: '2026-09-28',
799
- },
800
- ],
801
- }, { computedAt }));
792
+ const patched = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(existing, { settled_credit_bills: [{ key: 'COMPLETED:POS_WALK-IN', amount: 1000 }] }, { computedAt }));
802
793
  const issued = getKeyMetrics(patched, 'COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS].issued;
803
- expect(issued?.bills[0].received_amount).toBe(1000);
804
794
  expect(issued?.settled_count).toBe(1);
805
- expect(issued?.bills[0].settled_at).toEqual(computedAt); // payload has no collection timestamp → falls back to computedAt
795
+ expect(issued?.settled_amount).toBe(1000);
806
796
  expect(patched.iteration).toBe(2); // ledger changed → versioned write
807
797
  expect(patched).not.toHaveProperty('previous_sale_type_metrics'); // history lives in materialized_tenant_reports_iterations
808
798
  expect(patched.updatedAt).toEqual(computedAt);
809
- // Replaying the same collection changes nothing → not versioned.
810
- const replay = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(patched, {
811
- received_payments: [
812
- {
813
- order_id: 'order-1',
814
- payment_id: 'pay-1',
815
- amount: 1000,
816
- received_amount: 1000,
817
- issued_local_date: '2026-09-28',
818
- settled_at: new Date('2026-09-30T13:00:00.000Z'),
819
- },
820
- ],
821
- }, { computedAt }));
799
+ // An EMPTY patch is a no-op (no bump). The list is a DELTA, not a state
800
+ // converge: replay protection lives in the planner (settled transitions
801
+ // are detected against the merged rows), so the planner must never emit
802
+ // the same transition twice.
803
+ const replay = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(patched, { settled_credit_bills: [] }, { computedAt }));
822
804
  expect(replay.iteration ?? 1).toBe(2);
823
805
  });
824
- it('keeps a partially collected bill unsettled until received_amount covers the amount', () => {
825
- const issueDay = '2026-09-29';
826
- const issueDateDoc = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(issueDay, [
827
- makePayLaterOrder({
828
- orderId: 'order-credit-1',
829
- localDate: issueDay,
830
- amountDue: 1200,
831
- amountPaid: 0,
832
- paymentStatus: constants_1.PAYMENT_STATUS_ENUM.PENDING,
833
- settledAt: '2026-09-29T20:10:00.000Z',
834
- updatedAt: '2026-09-29T20:10:00.000Z',
835
- }),
836
- ], { brandId: BRAND })).materializedReports.find((doc) => doc.scope_context === MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_DATE);
837
- const partial = makePayLaterOrder({
838
- orderId: 'order-credit-1',
839
- localDate: issueDay,
840
- amountDue: 1200,
841
- amountPaid: 500,
842
- paymentStatus: constants_1.PAYMENT_STATUS_ENUM.PENDING,
843
- settledAt: '2026-09-30T10:00:00.000Z',
844
- updatedAt: '2026-09-30T10:00:00.000Z',
845
- });
846
- const partialCompile = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(DAY, [partial], { brandId: BRAND }));
847
- expect(partialCompile.received_payments[0]).toMatchObject({ amount: 1200, received_amount: 500 });
848
- const partiallyPatched = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(issueDateDoc, { received_payments: partialCompile.received_payments }, { computedAt: new Date('2026-09-30T23:00:00.000Z') }));
849
- const issuedPartial = getKeyMetrics(partiallyPatched, 'COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]
850
- .issued;
851
- expect(issuedPartial?.bills[0].received_amount).toBe(500);
852
- expect(issuedPartial?.bills[0].settled_at).toBeNull(); // 500 < 1200 → not settled
853
- expect(issuedPartial?.settled_count).toBe(0);
854
- expect(issuedPartial?.settled_amount).toBe(500);
855
- // The final installment completes the bill → settled with its true collection timestamp.
856
- const finalPayment = makePayLaterOrder({
857
- orderId: 'order-credit-1',
858
- localDate: issueDay,
859
- amountDue: 1200,
860
- amountPaid: 1200,
861
- paymentStatus: constants_1.PAYMENT_STATUS_ENUM.SETTLED,
862
- settledAt: '2026-10-01T09:15:00.000Z',
863
- updatedAt: '2026-10-01T09:15:00.000Z',
864
- });
865
- const fullCompile = expectNonNull((0, tenant_sales_overview_helpers_1.convertOrdersToMaterializedTenantSalesOverviewReports)(DAY, [finalPayment], { brandId: BRAND }));
866
- const fullyPatched = expectNonNull((0, tenant_sales_overview_helpers_1.updateMaterializedTenantSalesOverviewReport)(partiallyPatched, { received_payments: fullCompile.received_payments }, { computedAt: new Date('2026-10-01T23:00:00.000Z') }));
867
- const issuedFull = getKeyMetrics(fullyPatched, 'COMPLETED:POS_WALK-IN')?.[constants_1.REPORT_SALE_TYPE_ENUM.CREDIT_BILLS]
868
- .issued;
869
- expect(issuedFull?.bills[0].received_amount).toBe(1200);
870
- expect(issuedFull?.bills[0].settled_at).toEqual(new Date('2026-10-01T09:15:00.000Z'));
871
- expect(issuedFull?.settled_count).toBe(1);
872
- });
873
806
  it('normalizes hydrated (mongoose-cast) sale_type_metrics instead of corrupting them', () => {
874
807
  const stored = report({
875
808
  scopeContext: MATERIALIZED_REPORTS_1.MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@managesome/eposmatic-toolkit",
3
- "version": "0.4.7",
3
+ "version": "0.4.8",
4
4
  "description": "A Toolkit Library for Eposmatic",
5
5
  "main": "lib/index.js",
6
6
  "module": "esm/index.js",