@webex/contact-center 3.13.0-next.1 → 3.13.0-next.11

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 (84) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1065 -339
  3. package/AGENTS.md +935 -60
  4. package/dist/webex.js +1 -1
  5. package/docs/adr/0001-spec-source-policy.md +97 -0
  6. package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
  7. package/docs/adr/0003-repo-standards-migration.md +104 -0
  8. package/docs/adr/index.md +35 -0
  9. package/docs/architecture.md +460 -0
  10. package/docs/getting-started.md +142 -0
  11. package/docs/index.md +53 -0
  12. package/docs/specs/README.md +98 -0
  13. package/package.json +10 -9
  14. package/schemas/repo-context.schema.json +796 -0
  15. package/src/docs/README.md +727 -0
  16. package/src/metrics/docs/README.md +710 -0
  17. package/src/services/agent/docs/README.md +673 -0
  18. package/src/services/config/docs/README.md +530 -0
  19. package/src/services/core/docs/README.md +993 -0
  20. package/src/services/docs/README.md +765 -0
  21. package/src/services/task/docs/README.md +1569 -0
  22. package/src/services/task/state-machine/docs/README.md +1388 -0
  23. package/src/utils/AGENTS.md +6 -4
  24. package/src/utils/docs/README.md +413 -0
  25. package/umd/contact-center.min.js +2 -2
  26. package/umd/contact-center.min.js.map +1 -1
  27. package/ai-docs/ARCHITECTURE.md +0 -168
  28. package/ai-docs/CONTRACTS.md +0 -64
  29. package/ai-docs/GETTING_STARTED.md +0 -168
  30. package/ai-docs/GLOSSARY.md +0 -43
  31. package/ai-docs/README.md +0 -138
  32. package/ai-docs/REVIEW_CHECKLIST.md +0 -41
  33. package/ai-docs/RULES.md +0 -444
  34. package/ai-docs/SECURITY.md +0 -52
  35. package/ai-docs/SERVICE_STATE.md +0 -52
  36. package/ai-docs/SPEC_INDEX.md +0 -65
  37. package/ai-docs/adr/0001-spec-source-policy.md +0 -55
  38. package/ai-docs/adr/README.md +0 -8
  39. package/ai-docs/adr/_adr-template.md +0 -31
  40. package/ai-docs/contact-center-spec.md +0 -388
  41. package/ai-docs/features/contact-owner-change-refactor.md +0 -78
  42. package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
  43. package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
  44. package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
  45. package/ai-docs/patterns/event-driven-patterns.md +0 -485
  46. package/ai-docs/patterns/testing-patterns.md +0 -480
  47. package/ai-docs/patterns/typescript-patterns.md +0 -365
  48. package/ai-docs/templates/README.md +0 -102
  49. package/ai-docs/templates/documentation/create-agents-md.md +0 -240
  50. package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
  51. package/ai-docs/templates/existing-service/bug-fix.md +0 -254
  52. package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
  53. package/ai-docs/templates/new-method/00-master.md +0 -80
  54. package/ai-docs/templates/new-method/01-requirements.md +0 -232
  55. package/ai-docs/templates/new-method/02-implementation.md +0 -295
  56. package/ai-docs/templates/new-method/03-tests.md +0 -201
  57. package/ai-docs/templates/new-method/04-validation.md +0 -141
  58. package/ai-docs/templates/new-service/00-master.md +0 -109
  59. package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
  60. package/ai-docs/templates/new-service/02-code-generation.md +0 -346
  61. package/ai-docs/templates/new-service/03-integration.md +0 -178
  62. package/ai-docs/templates/new-service/04-test-generation.md +0 -205
  63. package/ai-docs/templates/new-service/05-validation.md +0 -145
  64. package/src/metrics/ai-docs/AGENTS.md +0 -350
  65. package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
  66. package/src/metrics/ai-docs/metrics-spec.md +0 -971
  67. package/src/services/agent/ai-docs/AGENTS.md +0 -240
  68. package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
  69. package/src/services/agent/ai-docs/agent-spec.md +0 -505
  70. package/src/services/ai-docs/AGENTS.md +0 -386
  71. package/src/services/ai-docs/services-spec.md +0 -512
  72. package/src/services/config/ai-docs/AGENTS.md +0 -250
  73. package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
  74. package/src/services/config/ai-docs/config-spec.md +0 -669
  75. package/src/services/core/ai-docs/AGENTS.md +0 -381
  76. package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
  77. package/src/services/core/ai-docs/core-spec.md +0 -797
  78. package/src/services/task/ai-docs/AGENTS.md +0 -457
  79. package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
  80. package/src/services/task/ai-docs/task-spec.md +0 -1501
  81. package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
  82. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
  83. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
  84. package/src/utils/ai-docs/utils-spec.md +0 -391
@@ -1,6 +1,6 @@
1
1
  # Utils
2
2
 
3
- > **Legacy/reference-only.** Canonical SDD: [`ai-docs/utils-spec.md`](ai-docs/utils-spec.md). Use the package [manifest](../../.sdd/manifest.json) and [`SPEC_INDEX.md`](../../ai-docs/SPEC_INDEX.md) for routing; code and tests remain the behavioral referee.
3
+ > **Legacy/reference-only.** Canonical SDD: [`docs/README.md`](docs/README.md). Use the package [manifest](../../.sdd/manifest.json) and [module registry](../../docs/specs/README.md) for routing; code and tests remain the behavioral referee.
4
4
  >
5
5
  > **Legacy scope:** This guide covers shared pagination/cache contracts used by data services. For repository rules and cross-service conventions, see the [root orchestrator AGENTS.md](../../AGENTS.md).
6
6
 
@@ -29,7 +29,9 @@ The utils scope currently provides shared pagination and cache behavior for cont
29
29
  ```
30
30
  src/utils/
31
31
  ├── AGENTS.md # This file: utils scope guide
32
- └── PageCache.ts # Generic cache + pagination contracts/defaults
32
+ ├── PageCache.ts # Generic cache + pagination contracts/defaults
33
+ └── docs/
34
+ └── README.md # Canonical utils module spec
33
35
  ```
34
36
 
35
37
  ---
@@ -240,7 +242,7 @@ Current consumers of `PageCache` and defaults:
240
242
 
241
243
  Cross-scope mention:
242
244
 
243
- - Services-layer docs reference utils caching contracts at [`../services/ai-docs/AGENTS.md`](../services/ai-docs/AGENTS.md).
245
+ - Services-layer docs reference utils caching contracts at [`../services/docs/README.md`](../services/docs/README.md).
244
246
 
245
247
  ---
246
248
 
@@ -259,7 +261,7 @@ flowchart TD
259
261
  B -->|Contract change| C[Document expected API/type behavior]
260
262
  B -->|Runtime behavior change| D[Document cache behavior and TTL impact]
261
263
  B -->|Both| C
262
- C --> E[Update utils AGENTS.md contracts and consumer map]
264
+ C --> E[Update the utils spec docs/README.md contracts and consumer map]
263
265
  D --> F[Validate cache key schema and bypass conditions]
264
266
  E --> G[Run drift check against PageCache.ts and consumer services]
265
267
  F --> G
@@ -0,0 +1,413 @@
1
+ ---
2
+ type: Module Spec
3
+ title: 'Utils specification'
4
+ description: Responsibilities, boundaries, design, cache state, invariants, and verification for the Contact Center shared pagination contracts and the PageCache utility.
5
+ tags: [module, specification]
6
+ ---
7
+ <!-- sdd-generated-metadata
8
+ doc_kind: module-spec
9
+ generated_from: module-spec@0.3.0
10
+ generated_by: claude-code
11
+ approved_by: rarajes2@cisco.com
12
+ updated_at: 2026-11-17T03:03:58Z
13
+ validation_status: pass-with-warnings
14
+ -->
15
+
16
+ # Utils
17
+
18
+ This source-local document at `src/utils/docs/README.md` owns the stable specification for
19
+ **Utils**, the `src/utils` module of `@webex/contact-center`. It covers shared pagination/cache
20
+ contracts used by data services: the pagination types and defaults in `src/utils/PageCache.ts` and
21
+ the bounded in-memory `PageCache<T>` that AddressBook and Queue use. Ground every claim in package
22
+ evidence and link to the [package architecture](../../../docs/architecture.md) instead of repeating
23
+ broader facts. No service specification exists because this package is a library. The parent
24
+ specification is the [Contact Center SDK package spec](../../docs/README.md).
25
+
26
+ Related context: [documentation index](../../../docs/index.md) ·
27
+ [package agent instructions](../../../AGENTS.md)
28
+
29
+ ## Metadata
30
+
31
+ | Field | Value |
32
+ | --- | --- |
33
+ | Owner | @webex/web-sdk |
34
+ | Source path | `src/utils` |
35
+ | Resource kind | module |
36
+ | Status | Active |
37
+ | Last verified | 2026-11-16 at `0b8c34db7f` |
38
+ | Module id | `utils` |
39
+ | Parent spec | [Contact Center SDK package spec](../../docs/README.md) |
40
+ | Doc kind | Module spec |
41
+ | Coverage score | Pending coverage assessment |
42
+ | Validation status | pass-with-warnings — assessed 2026-11-17; validator runtime 01a1e76f-2293-79a0-9f8f-f060038448dd; 0 Blocking, 0 Important, 4 Minor findings. |
43
+
44
+ ## Applicability
45
+
46
+ | Condition ID | Status | Evidence or reason | Owned section |
47
+ | --- | --- | --- | --- |
48
+ | `module.has_tiers` | N/A | No tier policy exists in `package.json` or under src | Tier |
49
+ | `module.has_ui` | N/A | `src/utils/PageCache.ts` holds types, constants, and one class; nothing renders | UI use-case flow |
50
+ | `module.crosses_service_boundaries` | N/A | `src/utils/PageCache.ts` makes no request; the consuming services own the backend calls | Cross-boundary use-case flow |
51
+ | `module.holds_client_state` | Applicable | `src/utils/PageCache.ts` keeps a per-instance Map of cached pages with timestamps | Client state model |
52
+ | `module.enforces_domain_rules` | Applicable | Cache eligibility, the key format, and the five-minute expiry in `src/utils/PageCache.ts` | Business rules and invariants |
53
+ | `module.is_concurrent_async` | N/A | Every PageCache method in `src/utils/PageCache.ts` is synchronous | Concurrency and reactive flow |
54
+ | `module.owns_persistence` | N/A | The cache lives in memory only; `src/utils/PageCache.ts` writes no storage | Data, schema, and migration discipline |
55
+ | `module.stateful_transitions` | N/A | A cache entry is only present, fresh, or expired-and-deleted in `src/utils/PageCache.ts`; no state machine | State machine |
56
+ | `module.exposes_wire_protocol` | N/A | No serializer or parser in `src/utils/PageCache.ts`; query strings are built by the consumers | Protocol and wire format |
57
+ | `module.ui_multi_screen` | N/A | No UI | UI flow |
58
+ | `module.large_data_model` | N/A | Six small exports in `src/utils/PageCache.ts` | Data model |
59
+ | `module.returns_caller_errors` | N/A | No PageCache method throws or rejects in `src/utils/PageCache.ts`; a miss returns null | Caller-visible failure modes |
60
+ | `module.module_specific_conventions` | Applicable | Bypass, key, and logging conventions every consumer of `src/utils/PageCache.ts` must follow | Module-specific rules |
61
+ | `module.published_package` | N/A | `src/index.ts` does not re-export `src/utils/PageCache.ts`; the package-level export contract is owned by the parent spec | Export stability |
62
+ | `module.embedded_in_host` | N/A | No host embed or theme surface | Host integration and theming |
63
+ | `module.has_design_tradeoff` | Applicable | `src/utils/PageCache.ts` caches only simple page browsing and bypasses every variant query | Key design trade-off |
64
+ | `module.has_submodules` | N/A | The src/utils directory has no child module (module_tree.py reports none) | Sub-modules |
65
+
66
+ ## Evidence register
67
+
68
+ | Evidence | What it establishes |
69
+ | --- | --- |
70
+ | `src/utils/PageCache.ts` | The exports `PaginationMeta`, `PaginatedResponse<T>`, `BaseSearchParams`, `PAGINATION_DEFAULTS`, `PageCacheEntry<T>`, `CacheValidationParams`, and the `PageCache<T>` class (named and default export); the private `DEFAULT_CACHE_TTL_MINUTES = 5`; the JSDoc that states intent ("consistent caching behavior across all Contact Center APIs") |
71
+ | `src/services/AddressBook.ts` | Owns one `PageCache<AddressBookEntry>('AddressBook')`; keys pages by `bookId`; treats the default `name`/`asc` order as cacheable and passes `sortBy` to `canUseCache` only for a custom sort |
72
+ | `src/services/Queue.ts` | Owns one `PageCache<ContactServiceQueue>('Queue')`; keys pages by `orgId`; its default filter, `sortBy` `name`, and `desktopProfileFilter` `true` all make `canUseCache` return false |
73
+ | `src/services/EntryPoint.ts` | Imports only `PAGINATION_DEFAULTS`; owns no PageCache and fetches every request |
74
+ | `src/types.ts` | Builds `AddressBookEntriesResponse`, `EntryPointListResponse`, and `ContactServiceQueuesResponse` on `PaginatedResponse<T>`, and the three search-parameter types on `BaseSearchParams` |
75
+ | `src/index.ts` | Exports those response and search aliases at the package root, not the PageCache module itself |
76
+ | `src/logger-proxy.ts` | `LoggerProxy`, the only runtime dependency of `src/utils/PageCache.ts` |
77
+ | `test/unit/spec/services/AddressBook.ts` | Cache hit on a repeat simple call, cache miss on a new page, custom-sort bypass |
78
+ | `test/unit/spec/services/Queue.ts` | Default-policy bypass, sort-order-only bypass, explicit false flags still bypassed by the default filter, cache miss call shape |
79
+ | `test/unit/spec/services/EntryPoint.ts` | Every profile-scoped request is issued directly |
80
+ | `jest.config.js` | The 85% global coverage threshold that applies to `src/utils/PageCache.ts` through the consumer tests |
81
+ | `src/utils/PageCache.ts` | Justifies the extension subsections Cache lifecycle and Clear all entries under Data flow and sequence coverage: lookup-fetch-store (with expiry) and clearing are its two operation groups |
82
+
83
+ ## Purpose and boundary
84
+
85
+ - Responsibility: Own shared pagination contracts and the bounded in-memory page cache used by Contact Center data services.
86
+ - In scope: the pagination metadata, response, and search-parameter types; `PAGINATION_DEFAULTS`;
87
+ cache eligibility (`canUseCache`), key construction, TTL lookup, page insertion, clearing, and size.
88
+ - Out of scope: request execution, query-string building, metrics, and error handling (the
89
+ consuming services and Core); the package-root response aliases, which `src/types.ts` builds on
90
+ these types and the parent spec owns.
91
+ - Consumers: the AddressBook, EntryPoint, and Queue consumers listed below, plus `src/types.ts`.
92
+
93
+ The utils scope currently provides shared pagination and cache behavior for contact-center data services:
94
+
95
+ - **Typed Pagination Contracts**: Reusable interfaces for response metadata and query params
96
+ - **Generic In-Memory Page Caching**: `PageCache<T>` utility for simple pagination reuse
97
+ - **Cache Safety Rules**: Explicit bypass behavior for query variants and enabled result/response-shape flags
98
+
99
+ Current consumers of `PageCache` and defaults:
100
+
101
+ | Consumer | File | Usage |
102
+ | --- | --- | --- |
103
+ | `AddressBook` | [`../services/AddressBook.ts`](../../services/AddressBook.ts) | Caches paged address-book responses |
104
+ | `EntryPoint` | [`../services/EntryPoint.ts`](../../services/EntryPoint.ts) | Uses `PAGINATION_DEFAULTS` only; every profile-scoped entry-point request is fetched, never cached |
105
+ | `Queue` | [`../services/Queue.ts`](../../services/Queue.ts) | Owns a queue page cache keyed by `orgId`; its default queue policy (default filter, name sort, desktop-profile views) always bypasses it, so a page is reused only when the caller clears the filter and sort and disables desktop-profile filtering |
106
+ | `Public type contracts` | [`../types.ts`](../../types.ts) | Builds the SDK-facing response and search types on the pagination/search contracts |
107
+
108
+ Cross-scope mention: the Services-layer spec references utils caching contracts at
109
+ [Services module spec](../../services/docs/README.md).
110
+
111
+ ## Structure and key files
112
+
113
+ | Path | Responsibility |
114
+ | --- | --- |
115
+ | `src/utils/PageCache.ts` | Authoritative PageCache implementation plus pagination/cache contracts and defaults |
116
+ | `src/utils/docs/README.md` | This module specification |
117
+ | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts` | Consumer tests that exercise PageCache and the defaults; there is no dedicated PageCache test file |
118
+
119
+ ## Public surface
120
+
121
+ All public contracts for utils are defined in [`PageCache.ts`](../PageCache.ts). Every export is
122
+ module-internal: `src/index.ts` does not re-export the module, and package-root types reach callers
123
+ only through the aliases in `src/types.ts`.
124
+
125
+ | Contract ID | Surface | Consumer | Compatibility commitment | Source |
126
+ | --- | --- | --- | --- | --- |
127
+ | `contact-center-page-cache` | `PageCache<T>` (named and default export): `constructor(apiName)` creates a typed cache instance and stores `apiName` for `LoggerProxy` context; synchronous `canUseCache(params)` (boolean), `buildCacheKey(orgId, page, pageSize)` (string), `getCachedPage(cacheKey)` (entry or `null`), `cachePage(cacheKey, data, meta?)`, `clearCache()` clears all entries and logs cleared entry count, `getCacheSize()` returns current in-memory entry count | AddressBook, Queue | Internal; not re-exported by the package root | `src/utils/PageCache.ts` |
128
+ | `contact-center-page-cache` | `PaginationMeta`, `PaginatedResponse<T>` (required `data` array of `T` items and required `meta` of type `PaginationMeta`), and `BaseSearchParams` (optional `search`, `filter`, `attributes`, `page`, `pageSize`, `sortBy`, and `sortOrder` `'asc'` or `'desc'`) | `src/types.ts`, AddressBook, EntryPoint, Queue | Internal, but the package-root response and search aliases are built on them, so a field change is a package API change owned by the parent spec | `src/utils/PageCache.ts`, `src/types.ts`, `src/index.ts` |
129
+ | `contact-center-page-cache` | `PAGINATION_DEFAULTS` (`as const`): `PAGE: 0` and `PAGE_SIZE: 100` | AddressBook, EntryPoint, Queue | Internal; a change moves every list default | `src/utils/PageCache.ts` |
130
+ | `contact-center-page-cache` | `PageCacheEntry<T>` returned by `getCachedPage()`: `data: T[]`, `timestamp: number` (epoch milliseconds), and optional `totalMeta` with optional `totalPages` and `totalRecords` | AddressBook, Queue | Internal | `src/utils/PageCache.ts` |
131
+ | `contact-center-page-cache` | `CacheValidationParams` passed to `canUseCache()` (fields below) | AddressBook, Queue | Internal; a new field must also be added to the bypass rule | `src/utils/PageCache.ts` |
132
+
133
+ Note: `clearCache()` and `getCacheSize()` are available for future use and are not currently called by existing consumers.
134
+
135
+ `PaginationMeta`: Common pagination metadata used across list APIs. Every field is optional.
136
+
137
+ | Field | Type | Notes |
138
+ | --- | --- | --- |
139
+ | `orgid` | `string` | Organization identifier |
140
+ | `page` / `currentPage` | `number` | Current page aliases |
141
+ | `pageSize` | `number` | Items per page |
142
+ | `totalPages` | `number` | Total page count |
143
+ | `totalRecords` / `totalItems` | `number` | Total item aliases |
144
+ | `links` | `Record<string, string>` | Pagination link map |
145
+
146
+ `CacheValidationParams` fields, all optional:
147
+
148
+ - `search?: string`
149
+ - `filter?: string`
150
+ - `attributes?: string`
151
+ - `sortBy?: string`
152
+ - `desktopProfileFilter?: boolean`
153
+ - `provisioningView?: boolean`
154
+ - `singleObjectResponse?: boolean`
155
+
156
+ ## Dependencies
157
+
158
+ | Dependency | Why it is required | Failure behavior |
159
+ | --- | --- | --- |
160
+ | `LoggerProxy` (`src/logger-proxy.ts`) | Logs expiry, insertion, and clearing with `{module: apiName, method}` context | Logging only; no PageCache result depends on it |
161
+ | In-memory Map and wall clock | The Map holds entries per instance; `Date.now()` stamps entries and measures their age | None; a cleared or lost Map only causes misses |
162
+
163
+ ## Requirements
164
+
165
+ | ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
166
+ | --- | --- | --- | --- | --- | --- | --- |
167
+ | UTILS-R-001 | Use cache only for simple pagination requests without search, filter, attributes, sortBy, or enabled desktop-profile/provisioning/single-object flags. Explicit `false` flags remain cache-compatible because they do not change the base result or response shape. | Parameterized or enabled variant queries cannot safely reuse a page keyed only by scope/page/pageSize, while a disabled boolean is semantically the same as omission. | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts` | None. | PRESENT |
168
+ | UTILS-R-002 | Build cache keys from a caller-defined `scopeId` plus `page:pageSize`: `bookId` for AddressBook and `orgId` for Queue. EntryPoint builds no key because it never caches. | Consumer scope and page boundaries prevent cross-scope or cross-page reuse. | `src/utils/PageCache.ts`, `src/services/AddressBook.ts`, `src/services/Queue.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts` | `PageCache.buildCacheKey` names its first implementation parameter `orgId`, but runtime callers establish the broader `scopeId` semantics. | PRESENT |
169
+ | UTILS-R-003 | Expire entries after the configured five-minute TTL and delete them on stale lookup. | Bounded staleness prevents indefinite reuse of remote service data. | `src/utils/PageCache.ts` | None | Direct fake-clock expiration coverage is absent from current consumer tests. | PRESENT |
170
+ | UTILS-R-004 | Cache data with total-page/record metadata and allow owning consumers to clear the cache. | Paginated services need consistent metadata without transferring ownership of remote records to the SDK. | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts` | Cache hit/miss and metadata are exercised through consumers; `clearCache()` has no direct assertion. | PRESENT |
171
+ | UTILS-R-005 | Accept already-fetched page values from consuming services and never store or process credentials; use the consumer's scope value only as part of the in-memory key. | Authentication remains in Services/Core and scope-separated keys prevent unrelated pages from colliding. | `src/utils/PageCache.ts`, `src/services/core/WebexRequest.ts`, `src/services/AddressBook.ts`, `src/services/Queue.ts` | `test/unit/spec/services/AddressBook.ts` | None; security/auth ownership is explicit. | PRESENT |
172
+ | UTILS-R-006 | Keep PageCache free of rollout flags; consuming services decide whether to invoke it and query parameters determine cache eligibility. | Cache correctness must depend on request shape, not hidden deployment state. | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts` | None; rollout applicability is explicitly N/A. | PRESENT |
173
+ | UTILS-R-007 | Export `PAGINATION_DEFAULTS` with `PAGE` 0 and `PAGE_SIZE` 100; AddressBook, EntryPoint, and Queue use them when the caller omits `page` or `pageSize`. | The JSDoc names them the default pagination constants used across all APIs, so every list method starts from the same first page and size. | `src/utils/PageCache.ts`, `src/services/AddressBook.ts`, `src/services/EntryPoint.ts`, `src/services/Queue.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/Queue.ts` | None; the default-parameter cases assert page=0 and pageSize=100 in the request URL. | PRESENT |
174
+
175
+ ## Design overview
176
+
177
+ Utils separates its stable consumption boundary from collaborators so ownership and failure
178
+ behavior stay explicit: PageCache never issues a request, so a consumer decides when to look up,
179
+ fetch, and store. Each consumer constructs its own instance, so state is owned per service.
180
+
181
+ Builds deterministic cache key format:
182
+
183
+ ```text
184
+ ${scopeId}:${page}:${pageSize}
185
+ ```
186
+
187
+ `getCachedPage` behavior:
188
+
189
+ 1. Returns `null` if key not found
190
+ 2. Computes cache age in minutes
191
+ 3. If age is `>= 5`, logs expiry, deletes entry, returns `null`
192
+ 4. Otherwise returns cached entry
193
+
194
+ `cachePage` stores entry with:
195
+
196
+ - `data`
197
+ - `timestamp`
198
+ - `totalMeta.totalPages`
199
+ - `totalMeta.totalRecords` mapped from `meta.totalRecords || meta.totalItems`
200
+
201
+ When `meta` is absent, `totalMeta` is `undefined`. A consumer rebuilds the response `meta` from the
202
+ requested `page` and `pageSize` plus `totalMeta` on a hit (Queue also adds `orgid`).
203
+
204
+ Reference usage (the AddressBook and Queue pattern):
205
+
206
+ ```typescript
207
+ import PageCache, {PAGINATION_DEFAULTS} from '../utils/PageCache';
208
+
209
+ const cache = new PageCache<MyItem>('MyService');
210
+
211
+ const page = PAGINATION_DEFAULTS.PAGE;
212
+ const pageSize = PAGINATION_DEFAULTS.PAGE_SIZE;
213
+ const cacheKey = cache.buildCacheKey(scopeId, page, pageSize);
214
+
215
+ // Include every supported result- or shape-changing input.
216
+ const canUseCache = cache.canUseCache({
217
+ search,
218
+ filter,
219
+ attributes,
220
+ sortBy,
221
+ desktopProfileFilter,
222
+ provisioningView,
223
+ singleObjectResponse,
224
+ });
225
+
226
+ if (canUseCache) {
227
+ const cachedEntry = cache.getCachedPage(cacheKey);
228
+ if (cachedEntry) {
229
+ return {
230
+ data: cachedEntry.data,
231
+ meta: {
232
+ page,
233
+ pageSize,
234
+ ...cachedEntry.totalMeta,
235
+ },
236
+ };
237
+ }
238
+ }
239
+
240
+ const response = await fetchPageFromApi();
241
+
242
+ if (canUseCache && response.data) {
243
+ cache.cachePage(cacheKey, response.data, response.meta);
244
+ }
245
+
246
+ return response;
247
+ ```
248
+
249
+ ## Data flow and sequence coverage
250
+
251
+ Call style: synchronous in-process method calls on a consumer-owned `PageCache` instance; the
252
+ consumer's own HTTP call through `WebexRequest` sits between lookup and store.
253
+
254
+ | Operation group | Entry and outcome | Diagram or evidence | Failure and recovery coverage |
255
+ | --- | --- | --- | --- |
256
+ | Eligible lookup, fetch, and store | `canUseCache`, `buildCacheKey`, `getCachedPage`, then the consumer fetch and `cachePage`; returns a cached or fresh page | Cache lifecycle diagram; `src/utils/PageCache.ts` | Advanced queries bypass cache; misses and expired entries (deleted at five minutes or more) fetch from the backend; failed backend calls and responses without data never reach `cachePage`. |
257
+ | Explicit cache clearing | `clearCache()`; empties the instance | Clear all entries diagram; `src/utils/PageCache.ts` | `clearCache` removes all entries from that consumer-owned PageCache instance and logs the prior size; no consumer calls it today. |
258
+
259
+ ### Cache lifecycle
260
+
261
+ ```mermaid
262
+ sequenceDiagram
263
+ participant Service as Data service
264
+ participant Cache as PageCache
265
+ participant API as Backend API
266
+ Service->>Cache: canUseCache(params)
267
+ alt simple pagination
268
+ Note over Service,Cache: scopeId = bookId (AddressBook) or orgId (Queue)
269
+ Service->>Cache: buildCacheKey(scopeId, page, pageSize)
270
+ Service->>Cache: getCachedPage(key)
271
+ alt fresh hit
272
+ Cache-->>Service: PageCacheEntry
273
+ else expired (age >= 5 minutes)
274
+ Cache->>Cache: log expiry, delete entry
275
+ Cache-->>Service: null
276
+ Service->>API: fetch page
277
+ else miss
278
+ Cache-->>Service: null
279
+ Service->>API: fetch page
280
+ end
281
+ alt backend success with response data
282
+ API-->>Service: data + meta
283
+ Service->>Cache: cachePage(key, data, meta)
284
+ else backend rejection
285
+ API--xService: error
286
+ Note over Service,Cache: no cache write
287
+ else success without data
288
+ API-->>Service: response without data
289
+ Note over Service,Cache: return response without a cache write
290
+ end
291
+ else advanced query
292
+ Service->>API: fetch without cache
293
+ end
294
+ ```
295
+
296
+ ### Clear all entries
297
+
298
+ ```mermaid
299
+ sequenceDiagram
300
+ participant Owner as Consumer service
301
+ participant Cache as Its PageCache instance
302
+ participant Log as LoggerProxy
303
+ Owner->>Cache: clearCache()
304
+ Cache->>Cache: capture size, then Map.clear()
305
+ Cache->>Log: log cleared entry count
306
+ Cache-->>Owner: void
307
+ ```
308
+
309
+ ## Class and component relationships
310
+
311
+ ```mermaid
312
+ classDiagram
313
+ class PageCache~T~ {
314
+ +canUseCache(params) boolean
315
+ +buildCacheKey(scopeId, page, pageSize) string
316
+ +getCachedPage(key) PageCacheEntry
317
+ +cachePage(key, data, meta)
318
+ +clearCache()
319
+ +getCacheSize() number
320
+ }
321
+ class AddressBook
322
+ class EntryPoint
323
+ class Queue
324
+ class PAGINATION_DEFAULTS
325
+ AddressBook --> PageCache : consumes
326
+ Queue --> PageCache : consumes
327
+ AddressBook ..> PAGINATION_DEFAULTS : defaults
328
+ EntryPoint ..> PAGINATION_DEFAULTS : defaults only
329
+ Queue ..> PAGINATION_DEFAULTS : defaults
330
+ ```
331
+
332
+ ## Use cases and flows
333
+
334
+ | Use case | Actor or caller | Primary steps and outcome | Failure or boundary behavior | Evidence |
335
+ | --- | --- | --- | --- | --- |
336
+ | `UC-001` | AddressBook or Queue | Cache eligibility: the service asks `canUseCache` with every result- or shape-changing input before any lookup | A bypassed request goes straight to the backend; EntryPoint never asks | `src/utils/PageCache.ts`, `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts` |
337
+ | `UC-002` | AddressBook or Queue | Cache-key construction: a simple page lookup builds `scopeId:page:pageSize` from the consumer's own scope value | Different scope or page values never share an entry | `src/utils/PageCache.ts`, `src/services/AddressBook.ts`, `src/services/Queue.ts` |
338
+ | `UC-003` | Consuming service | TTL lookup/expiry: a fresh cached entry is returned; an expired entry is deleted and treated as a miss | No direct expiration test currently exists | `src/utils/PageCache.ts` |
339
+ | `UC-004` | Consuming service | Page insertion and clearing: successful page data and normalized totals are cached, while `clearCache()` removes all entries for that service instance | Consumer tests cover insertion/hit behavior, but not direct clearing | `src/utils/PageCache.ts`, `test/unit/spec/services/AddressBook.ts` |
340
+
341
+ ## Client state model
342
+
343
+ Utils retains only in-memory runtime state. Durable domain records remain owned by remote Webex
344
+ services. State changes are driven by explicit calls from the owning consumer.
345
+
346
+ | State or slice | Owner | Initial state | Transition triggers | Reset or persistence boundary |
347
+ | --- | --- | --- | --- | --- |
348
+ | Page entries (`Map<string, PageCacheEntry<T>>`) | Each `PageCache` instance, one per AddressBook or Queue | Empty Map | `cachePage` sets or replaces an entry; `getCachedPage` deletes an entry whose age is 5 minutes or more; `clearCache` empties the Map | Lost with the instance; the consumers are created once per SDK READY callback and never persisted |
349
+ | `apiName` | Each `PageCache` instance | Constructor argument (`'AddressBook'`, `'Queue'`) | None | Fixed for the instance lifetime |
350
+
351
+ ## Business rules and invariants
352
+
353
+ | ID | Invariant | WHY | Enforcement source | Test evidence |
354
+ | --- | --- | --- | --- | --- |
355
+ | `INV-001` | Don't add query dimensions without either extending the cache key or making `canUseCache` bypass them. | The key holds only scope, page, and page size, so any other result- or shape-changing input would return a wrong page | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/Queue.ts` |
356
+ | `INV-002` | Each consuming service owns a separate `PageCache` instance and passes its own stable scope value into `buildCacheKey`. | Separate Maps keep AddressBook and Queue pages apart even when a scope value repeats | `src/services/AddressBook.ts`, `src/services/Queue.ts` | `test/unit/spec/services/AddressBook.ts` |
357
+ | `INV-003` | `getCachedPage` returns only an entry a consumer stored with `cachePage` and still younger than five minutes; otherwise it returns `null`. | AddressBook and Queue return a hit's `data` and `totalMeta` to the caller as the backend page without refetching, so an entry older than `DEFAULT_CACHE_TTL_MINUTES` (5) is deleted rather than served | `src/utils/PageCache.ts` | `test/unit/spec/services/AddressBook.ts` |
358
+
359
+ `canUseCache` returns `true` only when all of these are absent:
360
+
361
+ - `search`
362
+ - `filter`
363
+ - `attributes`
364
+ - `sortBy`
365
+ - `desktopProfileFilter`, `provisioningView`, or `singleObjectResponse` when `true`
366
+
367
+ An explicit `false` boolean remains eligible because it is semantically identical to omitting that flag. Services must pass an effective `sortBy` whenever `sortOrder` changes the wire order; Queue normalizes a direction-only request to `sortBy=name` before cache validation. `sortOrder` is not a `CacheValidationParams` field, and AddressBook passes `sortBy` only when the order differs from its `name`/`asc` default, so its default order stays cacheable.
368
+
369
+ ## Pitfalls and constraints
370
+
371
+ - AddressBook looks up the cache before it validates `bookId`; with no address book id the key
372
+ begins with `undefined`, nothing was ever stored under it, so the lookup misses and the request
373
+ then fails with the missing-addressBookId error.
374
+
375
+ ## Module-specific rules
376
+
377
+ - Do: preserve the five-minute `>=` expiry boundary and the `totalRecords || totalItems` compatibility mapping.
378
+ - Do: keep credentials, request execution, and backend-error handling in the consuming service/Core layers.
379
+ - Don't: claim `clearCache()` or TTL expiry is directly unit-tested until dedicated assertions exist.
380
+
381
+ When changing `src/utils` behavior or contracts, verify cache TTL, bypass rules, and key schema, and confirm:
382
+
383
+ - Public types remain backward-compatible or migration is documented
384
+ - `PAGINATION_DEFAULTS` changes are intentional and propagated to consumers
385
+ - Cache TTL behavior remains explicit, and TTL tests are added or kept
386
+ - `canUseCache()` bypass conditions are unchanged or intentionally updated
387
+ - `totalRecords`/`totalItems` mapping behavior is preserved
388
+ - Logging still uses `LoggerProxy` with `module` and `method`
389
+ - AddressBook/Queue cache integration remains correct; EntryPoint remains explicitly uncached
390
+
391
+ ## Key design trade-off
392
+
393
+ | Chosen trade-off | Preserved invariant or benefit | Cost or limitation | Decision evidence |
394
+ | --- | --- | --- | --- |
395
+ | Caching is intentionally limited to simple page browsing; search/filter/sort requests bypass cache to prevent incorrect reuse. | A cached page is always the page the same simple request would return within five minutes | Variant queries, and Queue under its default policy, always pay a backend call; the cache cannot be invalidated by backend changes inside the TTL | `src/utils/PageCache.ts` |
396
+
397
+ ## Verification
398
+
399
+ PageCache has no dedicated unit file; current consumer tests in `test/unit/spec/services/AddressBook.ts`, `EntryPoint.ts`, and `Queue.ts` cover request shaping, and AddressBook also covers cache hit/miss behavior while Queue and EntryPoint cover bypass. Add direct PageCache tests for the five-minute expiry boundary, entry deletion, metadata normalization, clearing, and key construction with both `bookId` and `orgId` scope values.
400
+
401
+ | Requirement or invariant | Test level | Positive evidence | Negative or boundary evidence | Gap |
402
+ | --- | --- | --- | --- | --- |
403
+ | `UTILS-R-001`, `INV-001` | Unit (through consumers) | `test/unit/spec/services/AddressBook.ts` repeat simple-pagination hit; AddressBook, EntryPoint, and Queue consumer tests exercise advanced query parameters and simple pagination | `test/unit/spec/services/AddressBook.ts` custom-sort bypass; `test/unit/spec/services/Queue.ts` sort-order-only and default-policy bypass | Add a direct `canUseCache` table test for each bypass field and `sortOrder` alone. |
404
+ | `UTILS-R-002`, `INV-002` | Unit (through consumers) | `test/unit/spec/services/AddressBook.ts` repeat/miss tests exercise bookId-scoped caching | `test/unit/spec/services/Queue.ts` shows its default policy bypasses the orgId-keyed cache | Add direct key-string assertions for both runtime scope kinds; no test that two consumer instances stay separate. |
405
+ | `UTILS-R-003`, `INV-003` | None | None found | None found | Add fake-clock tests at just below and exactly five minutes, including deletion. |
406
+ | `UTILS-R-004` | Unit (through consumers) | `test/unit/spec/services/AddressBook.ts` verifies a repeat-call hit and response metadata | `test/unit/spec/services/AddressBook.ts` and `test/unit/spec/services/Queue.ts` verify misses | Add direct metadata fallback and `clearCache`/`getCacheSize` assertions. |
407
+ | `UTILS-R-005` | None | None found | None found | Static ownership check only: `src/utils/PageCache.ts` has no credential or request dependency; no runtime credential test is needed. |
408
+ | `UTILS-R-006` | None | None found | None found | Static check only: `src/utils/PageCache.ts` has no feature-flag dependency; consumer tests cover invocation choices; no direct rollout test is applicable. |
409
+ | `UTILS-R-007` | Unit | `test/unit/spec/services/AddressBook.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/Queue.ts` default-parameter cases | None found | None |
410
+
411
+ Run the consumer tests with `yarn workspace @webex/contact-center test:unit` from the workspace root. A module specification is
412
+ complete only when its public surface, invariants, failure modes, and test evidence agree with the
413
+ implementation.