@managesome/eposmatic-toolkit 0.4.55 → 0.4.57

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 (78) hide show
  1. package/esm/constants/MATERIALIZED_REPORTS.js +91 -0
  2. package/esm/helpers/materialized-reports/index.js +7 -0
  3. package/esm/helpers/materialized-reports/materialized-dialer-accumulator-helpers.js +100 -0
  4. package/esm/helpers/materialized-reports/materialized-dialer-close-day-helpers.js +328 -0
  5. package/esm/helpers/materialized-reports/materialized-dialer-compile-helpers.js +180 -0
  6. package/esm/helpers/materialized-reports/materialized-dialer-entry-pages.js +222 -0
  7. package/esm/helpers/materialized-reports/materialized-dialer-key-helpers.js +82 -0
  8. package/esm/helpers/materialized-reports/materialized-dialer-masking.js +54 -0
  9. package/esm/helpers/materialized-reports/materialized-index-bootstrap.js +4 -0
  10. package/esm/helpers/materialized-reports/materialized-report-drilldown-rows.js +13 -1
  11. package/esm/helpers/materialized-reports/report-platform/definition.js +87 -3
  12. package/esm/helpers/materialized-reports/tenant-dialer-formatter.js +95 -0
  13. package/esm/helpers/reporting-contract/report-contract.js +3 -0
  14. package/esm/schemas/models/index.js +2 -0
  15. package/esm/schemas/models/materialized_report_drilldown_rows.js +1 -0
  16. package/esm/schemas/models/materialized_tenant_delivery_entries.js +5 -5
  17. package/esm/schemas/models/materialized_tenant_delivery_reports.js +7 -7
  18. package/esm/schemas/models/materialized_tenant_dialer_entries.js +65 -0
  19. package/esm/schemas/models/materialized_tenant_dialer_reports.js +66 -0
  20. package/esm/schemas/types/index.js +2 -0
  21. package/esm/schemas/types/materialized_report_drilldown_rows.js +1 -0
  22. package/esm/schemas/types/materialized_tenant_dialer_entries.js +1 -0
  23. package/esm/schemas/types/materialized_tenant_dialer_reports.js +7 -0
  24. package/lib/constants/MATERIALIZED_REPORTS.d.ts +72 -2
  25. package/lib/constants/MATERIALIZED_REPORTS.js +93 -1
  26. package/lib/helpers/materialized-reports/index.d.ts +7 -0
  27. package/lib/helpers/materialized-reports/index.js +7 -0
  28. package/lib/helpers/materialized-reports/materialized-dialer-accumulator-helpers.d.ts +39 -0
  29. package/lib/helpers/materialized-reports/materialized-dialer-accumulator-helpers.js +110 -0
  30. package/lib/helpers/materialized-reports/materialized-dialer-close-day-helpers.d.ts +90 -0
  31. package/lib/helpers/materialized-reports/materialized-dialer-close-day-helpers.js +340 -0
  32. package/lib/helpers/materialized-reports/materialized-dialer-compile-helpers.d.ts +67 -0
  33. package/lib/helpers/materialized-reports/materialized-dialer-compile-helpers.js +183 -0
  34. package/lib/helpers/materialized-reports/materialized-dialer-entry-pages.d.ts +97 -0
  35. package/lib/helpers/materialized-reports/materialized-dialer-entry-pages.js +235 -0
  36. package/lib/helpers/materialized-reports/materialized-dialer-key-helpers.d.ts +51 -0
  37. package/lib/helpers/materialized-reports/materialized-dialer-key-helpers.js +90 -0
  38. package/lib/helpers/materialized-reports/materialized-dialer-masking.d.ts +35 -0
  39. package/lib/helpers/materialized-reports/materialized-dialer-masking.js +57 -0
  40. package/lib/helpers/materialized-reports/materialized-index-bootstrap.js +4 -0
  41. package/lib/helpers/materialized-reports/materialized-report-drilldown-rows.js +13 -1
  42. package/lib/helpers/materialized-reports/report-platform/definition.js +86 -2
  43. package/lib/helpers/materialized-reports/tenant-dialer-formatter.d.ts +91 -0
  44. package/lib/helpers/materialized-reports/tenant-dialer-formatter.js +98 -0
  45. package/lib/helpers/reporting-contract/report-contract.d.ts +1 -0
  46. package/lib/helpers/reporting-contract/report-contract.js +3 -0
  47. package/lib/schemas/models/index.d.ts +2 -0
  48. package/lib/schemas/models/index.js +2 -0
  49. package/lib/schemas/models/materialized_report_drilldown_rows.js +1 -0
  50. package/lib/schemas/models/materialized_tenant_delivery_entries.d.ts +5 -5
  51. package/lib/schemas/models/materialized_tenant_delivery_entries.js +5 -5
  52. package/lib/schemas/models/materialized_tenant_delivery_reports.d.ts +7 -7
  53. package/lib/schemas/models/materialized_tenant_delivery_reports.js +7 -7
  54. package/lib/schemas/models/materialized_tenant_dialer_entries.d.ts +107 -0
  55. package/lib/schemas/models/materialized_tenant_dialer_entries.js +68 -0
  56. package/lib/schemas/models/materialized_tenant_dialer_reports.d.ts +100 -0
  57. package/lib/schemas/models/materialized_tenant_dialer_reports.js +69 -0
  58. package/lib/schemas/models/tenant_dialer_events.d.ts +3 -3
  59. package/lib/schemas/types/index.d.ts +2 -0
  60. package/lib/schemas/types/index.js +2 -0
  61. package/lib/schemas/types/materialized_report_drilldown_rows.d.ts +1 -1
  62. package/lib/schemas/types/materialized_report_drilldown_rows.js +1 -0
  63. package/lib/schemas/types/materialized_tenant_dialer_entries.d.ts +83 -0
  64. package/lib/schemas/types/materialized_tenant_dialer_entries.js +2 -0
  65. package/lib/schemas/types/materialized_tenant_dialer_reports.d.ts +77 -0
  66. package/lib/schemas/types/materialized_tenant_dialer_reports.js +10 -0
  67. package/lib/tests/materialized-reports/materialized-delivery-plan.test.js +1 -1
  68. package/lib/tests/materialized-reports/materialized-delivery-practical.test.js +1 -1
  69. package/lib/tests/materialized-reports/materialized-dialer-compile.test.d.ts +1 -0
  70. package/lib/tests/materialized-reports/materialized-dialer-compile.test.js +213 -0
  71. package/lib/tests/materialized-reports/materialized-dialer-formatter.test.d.ts +1 -0
  72. package/lib/tests/materialized-reports/materialized-dialer-formatter.test.js +159 -0
  73. package/lib/tests/materialized-reports/materialized-dialer-plan.test.d.ts +1 -0
  74. package/lib/tests/materialized-reports/materialized-dialer-plan.test.js +223 -0
  75. package/lib/tests/materialized-reports/materialized-tenant-dialer-schema.test.d.ts +1 -0
  76. package/lib/tests/materialized-reports/materialized-tenant-dialer-schema.test.js +183 -0
  77. package/lib/tests/materialized-reports/report-platform/registry-conformance.test.js +16 -3
  78. package/package.json +1 -1
@@ -1,4 +1,4 @@
1
- import { MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_ENTRY_SCOPES, MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_SCOPES, MATERIALIZED_DISCOUNT_REPORT_SCOPES, MATERIALIZED_PREP_TIME_ITEM_SCOPES, MATERIALIZED_PREP_TIME_REPORT_SCOPES, MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_TYPE_ENUM, ALL_MATERIALIZED_REPORT_SCOPES, } from '../../../constants/MATERIALIZED_REPORTS';
1
+ import { MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_ENTRY_SCOPES, MATERIALIZED_DELIVERY_GEO_CELL_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES, MATERIALIZED_DELIVERY_REPORT_SCOPES, MATERIALIZED_DIALER_ENTRY_MAX_BSON_BYTES, MATERIALIZED_DIALER_ENTRY_SCOPES, MATERIALIZED_DIALER_REPORT_MAX_BSON_BYTES, MATERIALIZED_DIALER_REPORT_SCOPES, MATERIALIZED_DISCOUNT_REPORT_SCOPES, MATERIALIZED_PREP_TIME_ITEM_SCOPES, MATERIALIZED_PREP_TIME_REPORT_SCOPES, MATERIALIZED_REPORT_KEY_FILTER_ENUM, MATERIALIZED_REPORT_SCOPE_ENUM, MATERIALIZED_REPORT_TYPE_ENUM, ALL_MATERIALIZED_REPORT_SCOPES, } from '../../../constants/MATERIALIZED_REPORTS';
2
2
  import { REPORT_KEY_ENUM } from '../../reporting-contract/report-contract';
3
3
  /**
4
4
  * PHASE 2 — DECLARATIVE REPORT DEFINITIONS.
@@ -321,7 +321,7 @@ const DELIVERY_DEFINITION = {
321
321
  status: REPORT_DEFINITION_STATUS.PRODUCTION,
322
322
  report: {
323
323
  name: 'materialized_tenant_delivery_reports',
324
- schemaVersion: 2,
324
+ schemaVersion: 1,
325
325
  budgetBytes: MATERIALIZED_DELIVERY_REPORT_MAX_BSON_BYTES,
326
326
  enforced: true,
327
327
  validatorFile: 'materialized_tenant_delivery_reports.bson',
@@ -330,7 +330,7 @@ const DELIVERY_DEFINITION = {
330
330
  },
331
331
  entries: {
332
332
  name: 'materialized_tenant_delivery_entries',
333
- schemaVersion: 3,
333
+ schemaVersion: 1,
334
334
  budgetBytes: MATERIALIZED_DELIVERY_ENTRY_MAX_BSON_BYTES,
335
335
  enforced: true,
336
336
  validatorFile: 'materialized_tenant_delivery_entries.bson',
@@ -427,17 +427,101 @@ const DELIVERY_DEFINITION = {
427
427
  'Historical totals do not pin schema_version today (baseline debt).',
428
428
  ],
429
429
  };
430
+ const DIALER_DEFINITION = {
431
+ key: REPORT_KEY_ENUM.DIALER,
432
+ segment: 'dialer',
433
+ reportType: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DIALER_REPORTS,
434
+ capabilities: { live: true, historical: true, details: true },
435
+ status: REPORT_DEFINITION_STATUS.PRODUCTION,
436
+ report: {
437
+ name: 'materialized_tenant_dialer_reports',
438
+ schemaVersion: 1,
439
+ budgetBytes: MATERIALIZED_DIALER_REPORT_MAX_BSON_BYTES,
440
+ enforced: true,
441
+ validatorFile: null,
442
+ validatorDebt: 'No schema validator exists for the dialer report collection yet.',
443
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DIALER_REPORTS_INDEX_OPTIONS',
444
+ migrationId: null,
445
+ },
446
+ entries: {
447
+ name: 'materialized_tenant_dialer_entries',
448
+ schemaVersion: 1,
449
+ budgetBytes: MATERIALIZED_DIALER_ENTRY_MAX_BSON_BYTES,
450
+ enforced: true,
451
+ validatorFile: null,
452
+ validatorDebt: 'No schema validator exists for the dialer entry collection yet.',
453
+ indexOwner: 'toolkit:MATERIALIZED_TENANT_DIALER_ENTRIES_INDEX_OPTIONS',
454
+ migrationId: null,
455
+ },
456
+ sideCollections: [FLAT_ROWS, FLAT_SCOPES],
457
+ reportScopes: [...MATERIALIZED_DIALER_REPORT_SCOPES],
458
+ entryScopes: [...MATERIALIZED_DIALER_ENTRY_SCOPES],
459
+ entryStorage: REPORT_ENTRY_STORAGE.PAGE_PER_SOURCE_DAY,
460
+ entrySplit: REPORT_ENTRY_SPLIT.DETERMINISTIC_SUBPAGES,
461
+ maxReportScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_YEAR,
462
+ maxEntryScope: MATERIALIZED_REPORT_SCOPE_ENUM.LOCAL_MONTH,
463
+ projections: [REPORT_PROJECTION.FLAT_DRILLDOWN],
464
+ budgets: {
465
+ materialized_tenant_dialer_reports: MATERIALIZED_DIALER_REPORT_MAX_BSON_BYTES,
466
+ materialized_tenant_dialer_entries: MATERIALIZED_DIALER_ENTRY_MAX_BSON_BYTES,
467
+ materialized_report_drilldown_rows: DOCUMENT_BUDGET,
468
+ materialized_report_drilldown_scopes: DOCUMENT_BUDGET,
469
+ },
470
+ retention: [],
471
+ writeGuard: REPORT_WRITE_GUARD.WATERMARK,
472
+ liveSource: REPORT_LIVE_SOURCE.RAW,
473
+ historicalLens: REPORT_HISTORICAL_LENS.DOCUMENT_FOLD,
474
+ completeness: { summary: 'NONE', details: 'FLAT_PROJECTION' },
475
+ filters: [
476
+ {
477
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.ACTION,
478
+ kind: 'KEY_COMPONENT',
479
+ mode: 'SERVER',
480
+ appliesTo: 'BOTH',
481
+ },
482
+ {
483
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.POS_ID,
484
+ kind: 'KEY_COMPONENT',
485
+ mode: 'SERVER',
486
+ appliesTo: 'BOTH',
487
+ },
488
+ {
489
+ id: MATERIALIZED_REPORT_KEY_FILTER_ENUM.STAFF_ID,
490
+ kind: 'KEY_COMPONENT',
491
+ mode: 'SERVER',
492
+ appliesTo: 'BOTH',
493
+ },
494
+ { id: 'DETAILS_VIEW', kind: 'REQUEST', mode: 'SERVER', appliesTo: 'DETAILS' },
495
+ ],
496
+ cursor: REPORT_CURSOR_KIND.KEYSET_STRUCTURED,
497
+ adapters: {
498
+ writer: 'materializeDialerReport',
499
+ live: 'getLiveTenantDialerReports',
500
+ historical: 'getMaterializedTenantDialerReports',
501
+ details: 'getMaterializedDialerDetailsPage',
502
+ },
503
+ owner: 'reporting-platform',
504
+ notes: [
505
+ 'Append-only event source: unattributed events (no localDate) are never assigned to a day.',
506
+ 'No duration and no order attribution exist; the page derives every rate.',
507
+ 'Counters are filtered by ACTION / POS_ID / STAFF_ID key components server-side.',
508
+ 'Page entries split deterministically into #N sub-pages when over the 15 MiB budget.',
509
+ 'Late events are not included until the day is re-closed.',
510
+ ],
511
+ };
430
512
  export const REPORT_DEFINITIONS = {
431
513
  [OVERVIEW_DEFINITION.key]: OVERVIEW_DEFINITION,
432
514
  [DISCOUNTS_DEFINITION.key]: DISCOUNTS_DEFINITION,
433
515
  [PREP_TIME_DEFINITION.key]: PREP_TIME_DEFINITION,
434
516
  [DELIVERY_DEFINITION.key]: DELIVERY_DEFINITION,
517
+ [DIALER_DEFINITION.key]: DIALER_DEFINITION,
435
518
  };
436
519
  export const PRODUCTION_REPORT_DEFINITIONS = [
437
520
  OVERVIEW_DEFINITION,
438
521
  DISCOUNTS_DEFINITION,
439
522
  PREP_TIME_DEFINITION,
440
523
  DELIVERY_DEFINITION,
524
+ DIALER_DEFINITION,
441
525
  ];
442
526
  export const REPORT_REGISTRY_EXEMPTIONS = {
443
527
  [REPORT_KEY_ENUM.CASH_IN_OUT]: {
@@ -0,0 +1,95 @@
1
+ import { MATERIALIZED_DIALER_HOUR_KEYS } from '../../constants/MATERIALIZED_REPORTS';
2
+ import { freshDialerCounters, mergeDialerCounters } from './materialized-dialer-accumulator-helpers';
3
+ import { dialerKeyPassesFilters, parseMaterializedDialerKey, } from './materialized-dialer-key-helpers';
4
+ const percent = (numerator, denominator) => {
5
+ if (!Number.isFinite(denominator) || denominator <= 0)
6
+ return null;
7
+ return Math.round((numerator / denominator) * 10000) / 100;
8
+ };
9
+ /**
10
+ * The ONLY rate denominator of the Dialer contract:
11
+ * `answered + missed + declined`. Every other event (incoming/outgoing/ended/
12
+ * ping) is activity, not an outcome, and must not dilute the rate.
13
+ */
14
+ const outcomeDenominator = (answered, missed, declined) => (Number(answered) || 0) + (Number(missed) || 0) + (Number(declined) || 0);
15
+ const summaryOf = (counters) => ({
16
+ events: counters.events,
17
+ incoming_calls: counters.incoming_calls,
18
+ outgoing_calls: counters.outgoing_calls,
19
+ answered: counters.answered,
20
+ missed: counters.missed,
21
+ declined: counters.declined,
22
+ ended: counters.ended,
23
+ pos_pings: counters.pos_pings,
24
+ answer_rate: percent(counters.answered, outcomeDenominator(counters.answered, counters.missed, counters.declined)),
25
+ missed_rate: percent(counters.missed, outcomeDenominator(counters.answered, counters.missed, counters.declined)),
26
+ });
27
+ const addBreakdown = (target, counters) => {
28
+ target.events += counters.events;
29
+ target.answered += counters.answered;
30
+ target.missed += counters.missed;
31
+ target.declined += counters.declined;
32
+ };
33
+ const breakdownRows = (map) => [...map.entries()]
34
+ .map(([key, value]) => ({
35
+ key,
36
+ events: value.events,
37
+ answered: value.answered,
38
+ missed: value.missed,
39
+ declined: value.declined,
40
+ answer_rate: percent(value.answered, outcomeDenominator(value.answered, value.missed, value.declined)),
41
+ }))
42
+ .sort((a, b) => b.events - a.events || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
43
+ /**
44
+ * Formats the report documents of one scope level into the page payload.
45
+ *
46
+ * `documents` may also be the single record returned by a live/historical read
47
+ * for one tenant. Key filters are applied here as well, so a client that only
48
+ * has unfiltered documents can still narrow them consistently with the server.
49
+ */
50
+ export function formatMaterializedDialerReport(documents, options = {}) {
51
+ const docs = (documents ?? []).filter((doc) => doc != null);
52
+ const filters = options.filters ?? null;
53
+ const total = freshDialerCounters();
54
+ const byAction = new Map();
55
+ const byPos = new Map();
56
+ const byStaff = new Map();
57
+ const tenantIds = new Set();
58
+ const scopes = new Set();
59
+ const bump = (map, key, counters) => {
60
+ const target = map.get(key) ?? { events: 0, answered: 0, missed: 0, declined: 0 };
61
+ addBreakdown(target, counters);
62
+ map.set(key, target);
63
+ };
64
+ for (const doc of docs) {
65
+ if (doc.tenant_id != null)
66
+ tenantIds.add(String(doc.tenant_id));
67
+ scopes.add(`${String(doc.scope_context)}|${String(doc.scope_field)}`);
68
+ for (const [key, block] of Object.entries(doc.dialer_counters ?? {})) {
69
+ if (!dialerKeyPassesFilters(key, filters))
70
+ continue;
71
+ mergeDialerCounters(total, block);
72
+ const parsed = parseMaterializedDialerKey(key);
73
+ bump(byAction, parsed?.action ?? key, block);
74
+ bump(byPos, parsed?.pos_id ?? key, block);
75
+ bump(byStaff, parsed?.staff_id ?? key, block);
76
+ }
77
+ }
78
+ const byHour = MATERIALIZED_DIALER_HOUR_KEYS.map((label) => ({
79
+ hour: Number(label),
80
+ label,
81
+ events: Number(total.by_hour?.[label]) || 0,
82
+ }));
83
+ return {
84
+ tenant_ids: [...tenantIds].sort(),
85
+ summary: summaryOf(total),
86
+ by_hour: byHour,
87
+ by_action: breakdownRows(byAction),
88
+ by_pos: breakdownRows(byPos),
89
+ by_staff: breakdownRows(byStaff),
90
+ scopes: [...scopes].sort().map((identity) => {
91
+ const [scope_context, scope_field] = identity.split('|');
92
+ return { scope_context, scope_field };
93
+ }),
94
+ };
95
+ }
@@ -30,6 +30,7 @@ export var REPORT_KEY_ENUM;
30
30
  REPORT_KEY_ENUM["PREP_TIME"] = "PREP_TIME";
31
31
  REPORT_KEY_ENUM["CASH_IN_OUT"] = "CASH_IN_OUT";
32
32
  REPORT_KEY_ENUM["DELIVERY"] = "DELIVERY";
33
+ REPORT_KEY_ENUM["DIALER"] = "DIALER";
33
34
  REPORT_KEY_ENUM["SALES_COMPARISON"] = "SALES_COMPARISON";
34
35
  REPORT_KEY_ENUM["HOURLY_COMPARISON"] = "HOURLY_COMPARISON";
35
36
  REPORT_KEY_ENUM["PAYMENTS_COMPARISON"] = "PAYMENTS_COMPARISON";
@@ -51,6 +52,7 @@ export const REPORT_ROUTE_SEGMENTS = {
51
52
  [REPORT_KEY_ENUM.PREP_TIME]: 'prep-time',
52
53
  [REPORT_KEY_ENUM.CASH_IN_OUT]: 'cash-in-out',
53
54
  [REPORT_KEY_ENUM.DELIVERY]: 'delivery',
55
+ [REPORT_KEY_ENUM.DIALER]: 'dialer',
54
56
  [REPORT_KEY_ENUM.SALES_COMPARISON]: 'sales-comparison',
55
57
  [REPORT_KEY_ENUM.HOURLY_COMPARISON]: 'hourly-comparison',
56
58
  [REPORT_KEY_ENUM.PAYMENTS_COMPARISON]: 'payments-comparison',
@@ -81,6 +83,7 @@ export const REPORT_CAPABILITIES = {
81
83
  [REPORT_KEY_ENUM.PREP_TIME]: { live: true, historical: true, details: true },
82
84
  [REPORT_KEY_ENUM.CASH_IN_OUT]: { live: true, historical: true, details: true },
83
85
  [REPORT_KEY_ENUM.DELIVERY]: { live: true, historical: true, details: true },
86
+ [REPORT_KEY_ENUM.DIALER]: { live: true, historical: true, details: true },
84
87
  [REPORT_KEY_ENUM.HOURLY_COMPARISON]: { live: true, historical: true, details: true },
85
88
  [REPORT_KEY_ENUM.PAYMENTS_COMPARISON]: { live: true, historical: true, details: true },
86
89
  [REPORT_KEY_ENUM.CREDIT_BILLS]: { live: false, historical: true, details: true },
@@ -37,6 +37,8 @@ export * from './materialized_tenant_delivery_geo_scopes';
37
37
  export * from './materialized_tenant_delivery_reports';
38
38
  export * from './materialized_tenant_discount_entries';
39
39
  export * from './materialized_tenant_discount_reports';
40
+ export * from './materialized_tenant_dialer_entries';
41
+ export * from './materialized_tenant_dialer_reports';
40
42
  export * from './materialized_tenant_discount_sources';
41
43
  export * from './materialized_tenant_hourly_comparison_entries';
42
44
  export * from './materialized_tenant_hourly_comparison_reports';
@@ -179,4 +179,5 @@ export const DRILLDOWN_REPORT_TYPE_BY_ENTRY_COLLECTION = {
179
179
  materialized_tenant_sales_comparison_entries: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_SALES_COMPARISON_ENTRIES,
180
180
  materialized_tenant_hourly_comparison_entries: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_HOURLY_COMPARISON_ENTRIES,
181
181
  materialized_tenant_payments_comparison_entries: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_PAYMENTS_COMPARISON_ENTRIES,
182
+ materialized_tenant_dialer_entries: MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DIALER_ENTRIES,
182
183
  };
@@ -14,12 +14,12 @@ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED
14
14
  * a fixed key set - the keys ARE the data.
15
15
  */
16
16
  /**
17
- * v3 - PAGE-PARTITIONED entry documents (one page per source day, max scope
18
- * `localMonth`). v2 was one document per period scope, which made a month an unbounded
19
- * document. Historical v2 documents are not readable by the page-aware read layer and
20
- * must be re-materialized (re-close the days); the writer deletes the pages it owns.
17
+ * v1 - PAGE-PARTITIONED entry documents (one page per source day, max scope
18
+ * `localMonth`). All materialized collections use schema_version 1 for this
19
+ * pre-launch contract. Schema versioning will be reintroduced only when a
20
+ * future stored-shape change requires an explicit migration.
21
21
  */
22
- export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_SCHEMA_VERSION = 3;
22
+ export const MATERIALIZED_TENANT_DELIVERY_ENTRIES_SCHEMA_VERSION = 1;
23
23
  export const MaterializedTenantDeliveryEntriesSchema = new Schema({
24
24
  tenant_id: { type: String, required: true },
25
25
  brand_id: { type: String, required: true },
@@ -9,15 +9,15 @@ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DELIVERY_KEY_FILTERS, MATERIALIZED
9
9
  * cannot type precisely without a fixed key set - the keys ARE the data.
10
10
  */
11
11
  /**
12
- * v2 - the production day-close writer.
12
+ * v1 - the current production day-close writer.
13
13
  *
14
- * v1 was the pre-production shape. v2 splits the AREA row into the ORDER-side
15
- * (`delivery_orders`, net sale, fees) and the APP-side (`delivery_records`, payout)
16
- * populations, keys the demand heat on the joined ORDER's `localHour`, and fixes the
17
- * refund source to the payment rows. A v1 document is still readable: the formatter
18
- * falls back to the old `count` field for the record total.
14
+ * The stored shape splits the AREA row into the ORDER-side (`delivery_orders`,
15
+ * net sale, fees) and the APP-side (`delivery_records`, payout) populations,
16
+ * keys the demand heat on the joined ORDER's `localHour`, and uses the payment
17
+ * rows as the refund source. Schema versioning is reset to 1 across all
18
+ * materialized collections for this pre-launch contract.
19
19
  */
20
- export const MATERIALIZED_TENANT_DELIVERY_REPORTS_SCHEMA_VERSION = 2;
20
+ export const MATERIALIZED_TENANT_DELIVERY_REPORTS_SCHEMA_VERSION = 1;
21
21
  export const MaterializedTenantDeliveryReportSchema = new Schema({
22
22
  tenant_id: { type: String, required: true },
23
23
  brand_id: { type: String, required: true },
@@ -0,0 +1,65 @@
1
+ import { Schema } from 'mongoose';
2
+ import { ALL_DAY_INDEX } from '../../constants/ENUMS';
3
+ import { MATERIALIZED_DIALER_ENTRY_SCOPES } from '../../constants/MATERIALIZED_REPORTS';
4
+ /**
5
+ * Mongoose schema for `materialized_tenant_dialer_entries`.
6
+ *
7
+ * PAGE-PARTITIONED by source day, exactly like discounts/delivery entries: the
8
+ * day scope uses `page='all'` and every period entry scope (week / ISO week /
9
+ * month) uses `page=<source localDate>`, so a document is bounded by ONE day's
10
+ * event rows. There is no quarter / semester / year entry document.
11
+ *
12
+ * `dialer_entries` is `Mixed` on purpose: it is a key-addressed map of row
13
+ * sections whose keys are the report's `<ACTION>:<POS_ID>:<STAFF_ID>` grammar.
14
+ */
15
+ /** Document shape version. Bump with a migration for already-stored pages. */
16
+ export const MATERIALIZED_TENANT_DIALER_ENTRIES_SCHEMA_VERSION = 1;
17
+ export const MaterializedTenantDialerEntriesSchema = new Schema({
18
+ tenant_id: { type: String, required: true },
19
+ brand_id: { type: String, required: true },
20
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DIALER_ENTRY_SCOPES },
21
+ scope_field: { type: String, required: true },
22
+ /** `'all'` for the day scope; the source `YYYY-MM-DD` for a period scope. */
23
+ page: { type: String, required: true, immutable: true },
24
+ day_index: { type: String, default: null, enum: [...ALL_DAY_INDEX, null] },
25
+ dialer_entries: { type: Schema.Types.Mixed, required: false, default: null },
26
+ iteration: { type: Number, required: true, min: 1, default: 1 },
27
+ schema_version: {
28
+ type: Number,
29
+ required: true,
30
+ immutable: true,
31
+ default: MATERIALIZED_TENANT_DIALER_ENTRIES_SCHEMA_VERSION,
32
+ },
33
+ source_watermark: { type: Schema.Types.Date, required: true },
34
+ computed_at: { type: Schema.Types.Date, required: true },
35
+ createdAt: { type: Schema.Types.Date, required: true, default: () => new Date(), immutable: true },
36
+ updatedAt: { type: Schema.Types.Date, required: true, default: () => new Date() },
37
+ }, { timestamps: true, versionKey: false, minimize: false });
38
+ export const MATERIALIZED_TENANT_DIALER_ENTRIES_COLLECTION_NAME = 'materialized_tenant_dialer_entries';
39
+ /**
40
+ * ONE unique index per PAGE: `tenant_id + scope_context + scope_field + page`.
41
+ *
42
+ * Do NOT use the scope-only index here: every period page carries
43
+ * `day_index: null`, so `(tenant, scope, field, day_index)` would reject the
44
+ * second page of a month. The same key also serves the multi-page read (tenant
45
+ * + scope prefix, then pages).
46
+ *
47
+ * Declared ONLY — applying it is an owner deploy step; nothing calls
48
+ * `ensureIndexes` from a service.
49
+ */
50
+ export const MATERIALIZED_TENANT_DIALER_ENTRIES_COLLECTION_INDEXES = {
51
+ _id: { _id: 1 },
52
+ tenant_id__scope_context__scope_field__page: {
53
+ tenant_id: 1,
54
+ scope_context: 1,
55
+ scope_field: 1,
56
+ page: 1,
57
+ },
58
+ };
59
+ export const MATERIALIZED_TENANT_DIALER_ENTRIES_INDEX_OPTIONS = [
60
+ {
61
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, page: 1 },
62
+ name: 'tenant_id__scope_context__scope_field__page',
63
+ unique: true,
64
+ },
65
+ ];
@@ -0,0 +1,66 @@
1
+ import { Schema } from 'mongoose';
2
+ import { ALL_DAY_INDEX } from '../../constants/ENUMS';
3
+ import { ALL_MATERIALIZED_REPORT_KEY_FILTERS, DIALER_KEY_FILTERS, MATERIALIZED_DIALER_REPORT_SCOPES, } from '../../constants/MATERIALIZED_REPORTS';
4
+ /**
5
+ * Mongoose schema for `materialized_tenant_dialer_reports`.
6
+ *
7
+ * `dialer_counters` is `Mixed` on purpose: it is a key-addressed map of bounded
8
+ * counter blocks (`<ACTION>:<POS_ID>:<STAFF_ID>` → counters + `by_hour`), and
9
+ * the keys ARE the data — Mongoose cannot type them without a fixed key set.
10
+ *
11
+ * The collection holds COUNTERS only. Itemized event rows live in the sibling
12
+ * `materialized_tenant_dialer_entries` collection (one page per source day).
13
+ */
14
+ /** Document shape version. Bump on a key-grammar/metric change + backfill. */
15
+ export const MATERIALIZED_TENANT_DIALER_REPORTS_SCHEMA_VERSION = 1;
16
+ export const MaterializedTenantDialerReportSchema = new Schema({
17
+ tenant_id: { type: String, required: true },
18
+ brand_id: { type: String, required: true },
19
+ scope_context: { type: String, required: true, enum: MATERIALIZED_DIALER_REPORT_SCOPES },
20
+ scope_field: { type: String, required: true },
21
+ day_index: { type: String, default: null, enum: [...ALL_DAY_INDEX, null] },
22
+ sale_type_key_filters: {
23
+ type: [String],
24
+ required: true,
25
+ default: () => [...DIALER_KEY_FILTERS],
26
+ validate: {
27
+ validator: (value) => value.length > 0 &&
28
+ value.every((entry) => ALL_MATERIALIZED_REPORT_KEY_FILTERS.includes(entry)),
29
+ message: 'sale_type_key_filters must be a non-empty subset of the known key filters',
30
+ },
31
+ },
32
+ dialer_counters: { type: Schema.Types.Mixed, required: true, default: null },
33
+ iteration: { type: Number, required: true, min: 1, default: 1 },
34
+ schema_version: {
35
+ type: Number,
36
+ required: true,
37
+ immutable: true,
38
+ default: MATERIALIZED_TENANT_DIALER_REPORTS_SCHEMA_VERSION,
39
+ },
40
+ source_watermark: { type: Schema.Types.Date, required: true },
41
+ computed_at: { type: Schema.Types.Date, required: true },
42
+ createdAt: { type: Schema.Types.Date, required: true, default: () => new Date(), immutable: true },
43
+ updatedAt: { type: Schema.Types.Date, required: true, default: () => new Date() },
44
+ }, { timestamps: true, versionKey: false, minimize: false });
45
+ export const MATERIALIZED_TENANT_DIALER_REPORTS_COLLECTION_NAME = 'materialized_tenant_dialer_reports';
46
+ /**
47
+ * The single UNIQUE compound identity index, like every materialized report
48
+ * collection. Declared ONLY — no service calls `index()` or `ensureIndexes`, and
49
+ * the services run with `autoIndex: false`. Applying it is an owner deploy step.
50
+ */
51
+ export const MATERIALIZED_TENANT_DIALER_REPORTS_COLLECTION_INDEXES = {
52
+ _id: { _id: 1 },
53
+ tenant_id__scope_context__scope_field__day_index: {
54
+ tenant_id: 1,
55
+ scope_context: 1,
56
+ scope_field: 1,
57
+ day_index: 1,
58
+ },
59
+ };
60
+ export const MATERIALIZED_TENANT_DIALER_REPORTS_INDEX_OPTIONS = [
61
+ {
62
+ key: { tenant_id: 1, scope_context: 1, scope_field: 1, day_index: 1 },
63
+ name: 'tenant_id__scope_context__scope_field__day_index',
64
+ unique: true,
65
+ },
66
+ ];
@@ -41,6 +41,8 @@ export * from './materialized_tenant_delivery_geo_scopes';
41
41
  export * from './materialized_tenant_delivery_reports';
42
42
  export * from './materialized_tenant_discount_entries';
43
43
  export * from './materialized_tenant_discount_reports';
44
+ export * from './materialized_tenant_dialer_entries';
45
+ export * from './materialized_tenant_dialer_reports';
44
46
  export * from './materialized_tenant_discount_sources';
45
47
  export * from './materialized_tenant_hourly_comparison_entries';
46
48
  export * from './materialized_tenant_hourly_comparison_reports';
@@ -7,4 +7,5 @@ export const ALL_DRILLDOWN_REPORT_TYPES = [
7
7
  MATERIALIZED_REPORT_TYPE_ENUM.TENANT_SALES_COMPARISON_ENTRIES,
8
8
  MATERIALIZED_REPORT_TYPE_ENUM.TENANT_HOURLY_COMPARISON_ENTRIES,
9
9
  MATERIALIZED_REPORT_TYPE_ENUM.TENANT_PAYMENTS_COMPARISON_ENTRIES,
10
+ MATERIALIZED_REPORT_TYPE_ENUM.TENANT_DIALER_ENTRIES,
10
11
  ];
@@ -0,0 +1,7 @@
1
+ import { DIALER_KEY_FILTERS, } from '../../constants/MATERIALIZED_REPORTS';
2
+ /** The default key-filter declaration of a dialer document. */
3
+ export const MATERIALIZED_DIALER_REPORT_KEY_FILTERS = [
4
+ DIALER_KEY_FILTERS[0],
5
+ DIALER_KEY_FILTERS[1],
6
+ DIALER_KEY_FILTERS[2],
7
+ ];
@@ -87,7 +87,10 @@ export declare enum MATERIALIZED_REPORT_KEY_FILTER_ENUM {
87
87
  DRAWER_ID = "DRAWER_ID",
88
88
  REF_TYPE = "REF_TYPE",
89
89
  CITY = "CITY",
90
- PAYMENT_METHOD = "PAYMENT_METHOD"
90
+ PAYMENT_METHOD = "PAYMENT_METHOD",
91
+ ACTION = "ACTION",
92
+ POS_ID = "POS_ID",
93
+ STAFF_ID = "STAFF_ID"
91
94
  }
92
95
  export declare const ALL_MATERIALIZED_REPORT_KEY_FILTERS: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
93
96
  /** Ordered key filters of the tenant sales overview report (`PLACED:POS_WALK-IN`). */
@@ -560,7 +563,9 @@ export declare enum MATERIALIZED_REPORT_TYPE_ENUM {
560
563
  TENANT_HOURLY_COMPARISON_REPORTS = "TENANT_HOURLY_COMPARISON_REPORTS",
561
564
  TENANT_HOURLY_COMPARISON_ENTRIES = "TENANT_HOURLY_COMPARISON_ENTRIES",
562
565
  TENANT_PAYMENTS_COMPARISON_REPORTS = "TENANT_PAYMENTS_COMPARISON_REPORTS",
563
- TENANT_PAYMENTS_COMPARISON_ENTRIES = "TENANT_PAYMENTS_COMPARISON_ENTRIES"
566
+ TENANT_PAYMENTS_COMPARISON_ENTRIES = "TENANT_PAYMENTS_COMPARISON_ENTRIES",
567
+ TENANT_DIALER_REPORTS = "TENANT_DIALER_REPORTS",
568
+ TENANT_DIALER_ENTRIES = "TENANT_DIALER_ENTRIES"
564
569
  }
565
570
  export declare const ALL_MATERIALIZED_REPORT_TYPES: MATERIALIZED_REPORT_TYPE_ENUM[];
566
571
  /**
@@ -663,3 +668,68 @@ export declare enum PAYMENTS_COMPARISON_METRIC_ENUM {
663
668
  AMOUNT_DUE = "AMOUNT_DUE"
664
669
  }
665
670
  export declare const ALL_PAYMENTS_COMPARISON_METRICS: PAYMENTS_COMPARISON_METRIC_ENUM[];
671
+ /**
672
+ * Dialer report — the FIRST report whose source is an append-only EVENT stream
673
+ * (`tenant_dialer_events`) rather than order-shaped documents.
674
+ *
675
+ * ## No local date is ever invented
676
+ *
677
+ * A dialer event carries its tenant-local fields only when the POS dialer could
678
+ * resolve the running business day at write time. An event with no `localDate`
679
+ * is UNATTRIBUTED: it is never counted into a day (and never assigned to the
680
+ * close's day), so it cannot be double-counted by a later re-close. The
681
+ * materializer reports the day-window unattributed count instead.
682
+ *
683
+ * ## Counters only — no duration, no order attribution
684
+ *
685
+ * The source stores no duration and the report derives none: a call is a set of
686
+ * EVENTS (`CALL_ANSWERED`, `CALL_ENDED`, …), not one row with a duration. The
687
+ * page derives every rate itself from the counters
688
+ * (`outcome_denominator = answered + missed + declined`); nothing derived is
689
+ * stored.
690
+ *
691
+ * ## Key grammar
692
+ *
693
+ * `<ACTION>:<POS_ID>:<STAFF_ID>` — the three key filters. `STAFF_ID` is
694
+ * nullable in the source, so a missing component is encoded as `UNKNOWN`; the
695
+ * event is never dropped for a missing dimension.
696
+ */
697
+ /**
698
+ * Pointer scopes. Like every counters report, the period documents are FOLDED
699
+ * from the sibling DAY documents (the writer never reads another day's rows).
700
+ * No `localHour` scope: the hour dimension is a `by_hour` map INSIDE each
701
+ * counter key, which is the shape the Dialer page renders.
702
+ */
703
+ export declare const MATERIALIZED_DIALER_REPORT_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
704
+ /**
705
+ * Entry scopes: the day page plus the three PERIOD pages. Every period scope is
706
+ * PAGE-PARTITIONED by source day, so an entry document is bounded by one day's
707
+ * events. There is no quarter / semester / year entry document.
708
+ */
709
+ export declare const MATERIALIZED_DIALER_ENTRY_SCOPES: MATERIALIZED_REPORT_SCOPE_ENUM[];
710
+ /**
711
+ * Page key of the DAY-scoped entry document. The day scope is already one day,
712
+ * so it needs no per-source-day partition; the three period scopes use the
713
+ * source `localDate` as their page (`page=<source localDate>`).
714
+ */
715
+ export declare const MATERIALIZED_DIALER_ENTRY_PAGE_ALL = "all";
716
+ /** Ordered key filters: `<ACTION>:<POS_ID>:<STAFF_ID>`. */
717
+ export declare const DIALER_KEY_FILTERS: MATERIALIZED_REPORT_KEY_FILTER_ENUM[];
718
+ /** Token used when a key component is missing (`UNKNOWN`). */
719
+ export declare const MATERIALIZED_DIALER_UNKNOWN_TOKEN = "UNKNOWN";
720
+ /** Key component delimiter. Enum/ids cannot contain it; a raw value is sanitized. */
721
+ export declare const MATERIALIZED_DIALER_KEY_SEPARATOR = ":";
722
+ /**
723
+ * The 24 `by_hour` bucket labels — `"0".."23"` (NOT zero-padded; this is the
724
+ * contract the page renders and the stored documents carry). Every counters
725
+ * block initializes all 24 keys, so a missing bucket is unambiguously zero.
726
+ */
727
+ export declare const MATERIALIZED_DIALER_HOUR_KEYS: string[];
728
+ /**
729
+ * Per-collection BSON budgets. MongoDB's hard limit is 16 MiB per document;
730
+ * 15 MiB is the owner-approved practical ceiling, leaving 1 MiB of headroom.
731
+ * A document that exceeds its budget fails at COMPILE/PLAN time, naming the
732
+ * collection + source day + scope — never midway through the close transaction.
733
+ */
734
+ export declare const MATERIALIZED_DIALER_REPORT_MAX_BSON_BYTES: number;
735
+ export declare const MATERIALIZED_DIALER_ENTRY_MAX_BSON_BYTES: number;