@webex/internal-plugin-metrics 3.12.0-next.54 → 3.12.0-next.56

package/docs/getting-started.md

@@ -0,0 +1,131 @@
+---
+type: Getting Started
+title: Getting started
+description: Local setup, build, run, and test routing for @webex/internal-plugin-metrics.
+tags: [onboarding]
+---
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: getting-started@0.3.0
+generated_by: claude-code
+approved_by: rarajes2@cisco.com
+updated_at: 2026-10-07T04:50:31Z
+validation_status: pass
+-->
+
+# Getting started
+
+Onboarding for **@webex/internal-plugin-metrics**, a workspace package of the `webex-js-sdk`
+monorepo. Every command below is run from the monorepo root.
+
+## Prerequisites
+
+| Tool or access                         | Version or requirement                                                        |
+| -------------------------------------- | ----------------------------------------------------------------------------- |
+| Node.js                                | `22.14` for building and testing, as declared by the repository owner in `.sdd/manifest.json` `toolchain`; `>=18` from `engines` in `package.json` is the consumer runtime floor |
+| Yarn                                   | The monorepo's Yarn workspaces; dependencies use the `workspace:*` protocol    |
+| Registry or VPN access                 | Public npm only. The package declares no `.npmrc` and no authenticated registry |
+
+## Install
+
+```bash
+git clone https://github.com/webex/webex-js-sdk.git
+yarn install
+```
+
+Consumers outside the monorepo install the published package with:
+
+```bash
+npm install --save @webex/internal-plugin-metrics
+```
+
+## Build
+
+```bash
+yarn workspace @webex/internal-plugin-metrics build:src
+```
+
+`build:src` transpiles `src/` to `dist/` and then runs `build`, which emits type declarations to
+`dist/types`. Run `yarn workspace @webex/internal-plugin-metrics build` alone for declarations only.
+
+## Run
+
+Not applicable. This package is a library plugin with no runnable entry point. It becomes active by
+being imported before a `WebexCore` instance is constructed, which registers
+`webex.internal.metrics` and `webex.internal.newMetrics`:
+
+```js
+import '@webex/internal-plugin-metrics';
+
+import WebexCore from '@webex/webex-core';
+
+const webex = new WebexCore();
+```
+
+## Tests
+
+```bash
+yarn workspace @webex/internal-plugin-metrics test:unit
+```
+
+Use the table as the repository-level test router. List only tiers that
+actually exist; behavioral intent belongs in the owning module specifications and exact
+cases remain in the repository's native test sources.
+
+| Tier         | Command                                                            | Test location     | Framework | External dependencies |
+| ------------ | ------------------------------------------------------------------ | ----------------- | --------- | --------------------- |
+| Unit         | `yarn workspace @webex/internal-plugin-metrics test:unit`           | `test/unit/spec`  | Mocha     | None                  |
+| Integration  | Not applicable — the package defines no `test:integration` script and has no `test/integration` directory | — | — | — |
+| System / E2E | Not applicable — the package defines no `test:browser` script       | —                 | —         | —                     |
+
+Run one spec with `--targets`, relative to `test/unit/spec/`. Run the focused unit tests with
+Node.js 22.14, the declared toolchain version; with nvm, switch first using `nvm use 22.14`:
+
+```bash
+yarn workspace @webex/internal-plugin-metrics test:unit --targets network-telemetry.ts
+```
+
+- Coverage or quality gate: none. The package's Mocha run enforces no threshold and defines no
+  `test:coverage` script, so the monorepo CI coverage job never reaches this workspace.
+  `.sdd/manifest.json` records this as `quality_gates.code_coverage.origin: none`.
+- Enforcement source: lint only, through `test:style` (`eslint ./src/**/*.*`) configured by
+  `.eslintrc.js`.
+- Test environment or QA dependencies: none. Every spec runs in-process against
+  `@webex/test-helper-mock-webex`.
+
+The `test` script in `package.json` is not a working gate: it chains `test:integration` and
+`test:browser`, which this package does not define. `.sdd/manifest.json` records `commands.build`
+as an unresolved owner decision for that reason.
+
+## Configuration and secrets
+
+- Required configuration: none to build or test. At runtime the plugin reads its own defaults from
+  `src/config.js`; both telemetry features it gates (`metrics.unhandledExceptionTelemetry.enabled`
+  and `metrics.networkTelemetry.enabled`) default to `false`.
+- Secret source: none. The package holds no credentials and reads only
+  `process.env.METRICS_SERVICE_URL`, an optional pre-discovery service override in `src/config.js`.
+- Package or artifact access: public npm. `@webex/event-dictionary-ts` is the one external runtime
+  dependency pinned in `package.json`.
+- Required neighboring repositories or workspace layout: none beyond the monorepo itself. The
+  package depends on the `@webex/webex-core`, `@webex/common` and `@webex/common-timers` workspace
+  siblings, which `yarn install` links.
+- Platform, simulator, device, or SDK setup: none. Browser-only behavior is guarded at runtime, so
+  the unit suite runs under Node.js.
+- Never commit credentials or copy production secrets into a local config.
+
+## First-run verification
+
+1. Run `yarn workspace @webex/internal-plugin-metrics build:src`.
+2. Check that `dist/index.js` and `dist/types/index.d.ts` exist, matching the `main` and `types`
+   fields in `package.json`.
+3. Run `yarn workspace @webex/internal-plugin-metrics test:unit --targets network-telemetry.ts`.
+
+Expected result: the build emits `dist/` without errors and the focused spec passes, exercising the
+request-outcome collector end to end against the mocked SDK.
+
+## Next steps
+
+- [Repository architecture](architecture.md)
+- Service specification — not applicable for this package
+- [Specification registry](specs/README.md)
+- [Documentation index](index.md)

package/docs/index.md

@@ -0,0 +1,52 @@
+---
+okf_version: '0.1'
+---
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: docs-index@0.3.0
+generated_by: claude-code
+approved_by: rarajes2@cisco.com
+updated_at: 2026-10-07T04:50:31Z
+validation_status: pass
+-->
+
+# @webex/internal-plugin-metrics documentation
+
+Doc map for developers and agents working on the Webex JS SDK metrics plugin: the package that
+collects, enriches, batches and submits every SDK-owned telemetry family to the Webex metrics and
+unified telemetry services.
+
+## Start here
+
+- [Getting started](getting-started.md)
+- [Repository architecture](architecture.md)
+- Service specification — not applicable; this package is a library plugin with no deployable
+  service, recorded as `docs/service.md: omit` in `.sdd/manifest.json`.
+- API specification — not applicable; the package owns no HTTP surface, recorded as
+  `api-specs/openapi.yaml: omit` in `.sdd/manifest.json`.
+
+## Decisions
+
+- [adr/](adr/) — architectural decision records
+
+## Specifications and contracts
+
+- [architecture.md](architecture.md) — canonical repository-wide architecture and the contract index
+- [specs/README.md](specs/README.md) — manifest-backed module and contract registry
+- `<module-path>/docs/README.md` — the owning specification beside each module's code, one per
+  module in the registry
+- [adr/](adr/) — concrete architectural decisions; blank ADR templates remain under `.sdd/`
+
+Use the manifest-linked native source for exact contract details: the ecosystem-native SDK exports
+in `package.json` and `src/index.ts` for the published package surface, the TypeScript declarations
+in `src/metrics.types.ts` for every event envelope, and the externally owned
+`@webex/event-dictionary-ts` schema for Call Analyzer event names and payload fields. Register and
+link those sources from the architecture index and the owning module spec instead of copying them
+into Markdown.
+
+## Related repository resources
+
+- [README.md](../README.md) — the published npm landing page for this package. It is owner-authored
+  and retained in place; it is not generated and is not a canonical specification.
+- Monorepo-level contribution, security and release governance lives at the `webex-js-sdk`
+  repository root rather than in this package.

package/docs/specs/README.md

@@ -0,0 +1,88 @@
+---
+type: Reference
+title: Specification registry
+description: Canonical specification registry and change-routing guide.
+tags: [specifications, registry]
+---
+<!-- sdd-generated-metadata
+doc_kind: standing-doc
+generated_from: spec-index@0.3.0
+generated_by: claude-code
+approved_by: rarajes2@cisco.com
+updated_at: 2026-10-07T04:50:31Z
+validation_status: pass
+-->
+
+# Specification registry
+
+Use this page to find the canonical repository architecture and every
+instantiated module specification plus native contract. Keep technical facts
+in one owning document and use this page only for navigation, ownership,
+status, and change/test routing.
+
+Start with the [repository architecture](../architecture.md). No service
+specification exists: this package is a library plugin with no deployable
+service, recorded as `docs/service.md: omit` in `.sdd/manifest.json`.
+
+## Document roles
+
+| Document                                            | Canonical ownership                                                                                          |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| [Repository architecture](../architecture.md)       | Repository boundaries, resource inventory, interactions, dependency topology, and cross-cutting architecture |
+| Service specification                                | Not applicable — no deployable service in this package                                                       |
+| Module specifications                                | Stable behavior and design at each manifest-routed `<module-path>/docs/README.md`                              |
+| [ADR](../adr/)                                      | A durable decision, its deciders, rationale, consequences, and supersession lineage                          |
+
+## Instantiated specification registry
+
+| Resource                                     | Role         | Canonical path                                                  | Owner                             | Status | Last verified |
+| -------------------------------------------- | ------------ | --------------------------------------------------------------- | --------------------------------- | ------ | ------------- |
+| Repository                                   | Architecture | `docs/architecture.md`                                           | Cisco Webex JS SDK — telemetry    | Active | 2026-10-05    |
+| Metrics plugin root                          | Module       | `src/docs/README.md`                                             | Cisco Webex JS SDK — telemetry    | Active | 2026-10-05    |
+| Call Analyzer diagnostics                    | Module       | `src/call-diagnostic/docs/README.md`                             | Cisco Webex JS SDK — telemetry    | Active | 2026-10-05    |
+| Privacy and security permission enrichment   | Module       | `src/privacy-and-security-permission-enricher/docs/README.md`     | Cisco Webex JS SDK — telemetry    | Active | 2026-10-05    |
+| WebRTC stats telemetry                       | Module       | `src/rtcMetrics/docs/README.md`                                  | Cisco Webex JS SDK — telemetry    | Active | 2026-10-05    |
+| Unhandled exception telemetry                | Module       | `src/unhandled-exception-telemetry/docs/README.md`                | Cisco Webex JS SDK — telemetry    | Active | 2026-10-05    |
+| Published SDK surface                        | Contract     | `src/index.ts`                                                   | Cisco Webex JS SDK — telemetry    | Active | 2026-10-05    |
+| Call Analyzer event schema                   | Contract     | `@webex/event-dictionary-ts`, pinned in `package.json`            | Webex Call Analyzer (external)    | Active | 2026-10-05    |
+
+### Module registry
+
+One row per module in `.sdd/manifest.json`, which stays authoritative; this table is its
+human-readable mirror and the reconciliation surface for `scripts/check_spec_index.py`.
+
+| Module | Responsibility | Manifest coverage state | Start here |
+| --- | --- | --- | --- |
+| `src/` | Plugin registration, the legacy `metrics` and current `newMetrics` façades, the batcher family, tagged-event metrics and SDK network telemetry | Partial | `src/docs/README.md` |
+| ↳ `src/call-diagnostic/` | Call Analyzer client, feature and media-quality events, the latency ledger, error-code mapping and its own batcher | Partial | `src/call-diagnostic/docs/README.md` |
+| ↳ `src/privacy-and-security-permission-enricher/` | Permission-change enrichment policy applied to Call Analyzer client events | Partial | `src/privacy-and-security-permission-enricher/docs/README.md` |
+| ↳ `src/rtcMetrics/` | WebRTC stats telemetry submitted to the unified telemetry service | Partial | `src/rtcMetrics/docs/README.md` |
+| ↳ `src/unhandled-exception-telemetry/` | Browser uncaught error and promise-rejection reporter | Partial | `src/unhandled-exception-telemetry/docs/README.md` |
+
+Every module carries a generated canonical spec. All five are held at `Partial` because the first
+generator-side coverage measurement has not yet produced a score; promotion to `Specced` is a
+coverage-review decision recorded in `.sdd/manifest.json`, not a generation decision. Independent
+semantic validation is a separate gate and is deferred to another runtime by explicit owner
+instruction.
+
+## Change and verification routing
+
+| Change affects                                          | Load and update                                                                   | Verification route                               |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Repository boundaries or cross-cutting architecture     | `docs/architecture.md` and applicable ADRs                                        | `test:unit` plus the affected owner specs        |
+| A submitted payload, metric name or event name          | The owning module spec's `Protocol and wire format`, plus `src/metrics.types.ts`  | `test:unit` for the owning module's spec file    |
+| A stable code, package, or component boundary           | Its module spec                                                                   | Module tests plus affected contracts             |
+| A public API, event, command, package, or file contract | The owning architecture/module section plus the native declaration                | `test:unit` and `build` for declaration output   |
+
+## Module and contract registration
+
+Generate each module specification directly at the exact `modules[].canonical_spec` path recorded in
+`.sdd/manifest.json` (default `<module-path>/docs/README.md`). Never copy a visible module starter or
+reconstruct a path from an example. Register every module and submodule in the Module registry above
+in manifest tree order.
+
+Register each contract with a stable identity, `published` or `internal` publication state, canonical
+native source, and owning-module link. This package owns no HTTP surface, so no OpenAPI document is
+selected; its published surface is the ecosystem-native SDK export declared in `package.json` and
+`src/index.ts`, and the upstream Webex metrics and unified telemetry HTTP contracts are externally
+owned. This page provides navigation and ownership rather than a copied contract.

package/package.json

@@ -40,7 +40,7 @@
     "@webex/event-dictionary-ts": "^1.0.2220",
     "@webex/test-helper-chai": "3.12.0-next.9",
     "@webex/test-helper-mock-webex": "3.12.0-next.9",
-    "@webex/webex-core": "3.12.0-next.54",
+    "@webex/webex-core": "3.12.0-next.60",
     "ip-anonymize": "^0.1.0",
     "isbot": "5.2.1",
     "lodash": "^4.17.21",
@@ -54,5 +54,5 @@
     "test:style": "eslint ./src/**/*.*",
     "test:unit": "webex-legacy-tools test --unit --runner mocha"
   },
-  "version": "3.12.0-next.54"
+  "version": "3.12.0-next.56"
 }