@webex/contact-center 3.13.0-next.1 → 3.13.0-next.10
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.
- package/.repo-context.json +704 -0
- package/.sdd/manifest.json +1065 -339
- package/AGENTS.md +935 -60
- package/dist/webex.js +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
- package/docs/adr/0003-repo-standards-migration.md +104 -0
- package/docs/adr/index.md +35 -0
- package/docs/architecture.md +460 -0
- package/docs/getting-started.md +142 -0
- package/docs/index.md +53 -0
- package/docs/specs/README.md +98 -0
- package/package.json +10 -9
- package/schemas/repo-context.schema.json +796 -0
- package/src/docs/README.md +727 -0
- package/src/metrics/docs/README.md +710 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/docs/README.md +530 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/docs/README.md +765 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/utils/AGENTS.md +6 -4
- package/src/utils/docs/README.md +413 -0
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
- package/ai-docs/ARCHITECTURE.md +0 -168
- package/ai-docs/CONTRACTS.md +0 -64
- package/ai-docs/GETTING_STARTED.md +0 -168
- package/ai-docs/GLOSSARY.md +0 -43
- package/ai-docs/README.md +0 -138
- package/ai-docs/REVIEW_CHECKLIST.md +0 -41
- package/ai-docs/RULES.md +0 -444
- package/ai-docs/SECURITY.md +0 -52
- package/ai-docs/SERVICE_STATE.md +0 -52
- package/ai-docs/SPEC_INDEX.md +0 -65
- package/ai-docs/adr/0001-spec-source-policy.md +0 -55
- package/ai-docs/adr/README.md +0 -8
- package/ai-docs/adr/_adr-template.md +0 -31
- package/ai-docs/contact-center-spec.md +0 -388
- package/ai-docs/features/contact-owner-change-refactor.md +0 -78
- package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
- package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
- package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
- package/ai-docs/patterns/event-driven-patterns.md +0 -485
- package/ai-docs/patterns/testing-patterns.md +0 -480
- package/ai-docs/patterns/typescript-patterns.md +0 -365
- package/ai-docs/templates/README.md +0 -102
- package/ai-docs/templates/documentation/create-agents-md.md +0 -240
- package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
- package/ai-docs/templates/existing-service/bug-fix.md +0 -254
- package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
- package/ai-docs/templates/new-method/00-master.md +0 -80
- package/ai-docs/templates/new-method/01-requirements.md +0 -232
- package/ai-docs/templates/new-method/02-implementation.md +0 -295
- package/ai-docs/templates/new-method/03-tests.md +0 -201
- package/ai-docs/templates/new-method/04-validation.md +0 -141
- package/ai-docs/templates/new-service/00-master.md +0 -109
- package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
- package/ai-docs/templates/new-service/02-code-generation.md +0 -346
- package/ai-docs/templates/new-service/03-integration.md +0 -178
- package/ai-docs/templates/new-service/04-test-generation.md +0 -205
- package/ai-docs/templates/new-service/05-validation.md +0 -145
- package/src/metrics/ai-docs/AGENTS.md +0 -350
- package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
- package/src/metrics/ai-docs/metrics-spec.md +0 -971
- package/src/services/agent/ai-docs/AGENTS.md +0 -240
- package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
- package/src/services/agent/ai-docs/agent-spec.md +0 -505
- package/src/services/ai-docs/AGENTS.md +0 -386
- package/src/services/ai-docs/services-spec.md +0 -512
- package/src/services/config/ai-docs/AGENTS.md +0 -250
- package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
- package/src/services/config/ai-docs/config-spec.md +0 -669
- package/src/services/core/ai-docs/AGENTS.md +0 -381
- package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
- package/src/services/core/ai-docs/core-spec.md +0 -797
- package/src/services/task/ai-docs/AGENTS.md +0 -457
- package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
- package/src/services/task/ai-docs/task-spec.md +0 -1501
- package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
- package/src/utils/ai-docs/utils-spec.md +0 -391
package/src/utils/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Utils
|
|
2
2
|
|
|
3
|
-
> **Legacy/reference-only.** Canonical SDD: [`
|
|
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
|
-
|
|
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/
|
|
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
|
|
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.
|