feat(insights): voice usage monitors (minutes, calls, connection rates, durations) - #45
Merged
Conversation
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
joshraub-bw
previously approved these changes
Aug 25, 2026
achandras
previously approved these changes
Aug 25, 2026
kshahbw
disabled auto-merge
August 25, 2026 15:18
kshahbw
dismissed stale reviews from achandras and joshraub-bw
August 25, 2026 15:21
The base branch was changed.
…s, durations) Add band insights — read-only usage/quality aggregates from the Insights Monitoring API, answering 'how much traffic does this number carry?': - insights minutes-of-use | completed-calls | failed-calls | connection-rates | average-durations, all sharing the same filters: --to/--from (comma-separated E.164), --direction, --call-type (dash or underscore forms accepted, e.g. TOLLFREE-IN), --subaccount, and --since/--until (RFC3339 or relative shorthand: 30d, 24h, 90m) - new InsightsClient against insights.bandwidth.com (single prod host, BW_INSIGHTS_URL override); the standard OAuth Bearer token is accepted (verified live) - deepObject query encoding per the API spec (accountId[eq], timestamp[gte/lte], toPhoneNumber[eq], ...) - the Monitoring-feature 403 maps to an actionable message (exit 2), same pattern as the toll-free template gate Live-probed against production: token acceptance, query encoding, the feature-gate 403 mapping, and flag validation (exit 6). Happy path needs a Monitoring-enabled account; envelope unwrapping is unit-tested against spec examples and passes unexpected shapes through raw.
…lidate-before-auth, relative-time bounds Review findings from an independent pass: - Insights is production-only, but the token was minted per --environment: an active test profile produced a test-realm token that the prod Insights host rejects with 401. Mint against prod and warn on non-prod environments, mirroring MessagingClient. - --call-type now validates against the API enum after normalization (--call-type banana was reaching the server as BANANA and returning a 400 instead of a local flag error). - Flag validation moved before authentication so misuse exits 6 deterministically regardless of login state (repo pattern). - Relative time shorthand is bounded at 400d: the API keeps one year of history, and unbounded values overflowed time.Duration into future timestamps (e.g. 106752d).
kshahbw
force-pushed
the
feat/insights-monitors
branch
from
August 25, 2026 15:26
988365a to
0bb6f81
Compare
joshraub-bw
previously approved these changes
Aug 25, 2026
ckoegel
previously approved these changes
Aug 25, 2026
Merging main brought in the context.Context client migration; pass cmd.Context() at the insights call site like the rest of the tree.
joshraub-bw
approved these changes
Aug 25, 2026
ckoegel
approved these changes
Aug 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
New
band insightsgroup: read-only voice usage/quality aggregates from the Insights Monitoring API (insights.bandwidth.com).insights minutes-of-use/v1/monitors/voice/minutes-of-useinsights completed-calls/v1/monitors/voice/completed-callsinsights failed-calls/v1/monitors/voice/failed-callsinsights connection-rates/v1/monitors/voice/connection-ratesinsights average-durations/v1/monitors/voice/average-durationsShared filters:
--to/--from(comma-separated E.164),--direction,--call-type(acceptsTOLLFREE-INorTOLLFREE_IN),--subaccount,--since/--until(RFC3339 or relative30d/24h/90m; API defaults to the last 7 days). Results are time slices whose granularity the API scales with the window.Why
Completes the usage half of the number-inspection story: PR #44 answers "how is this number configured/routed", this answers "how much traffic does it carry" — per-number minutes, call counts, answer rates, and ACD, isolatable to toll-free ingress via
--call-type TOLLFREE-IN.Design notes
cmdutil.InsightsClient— single prod host,BW_INSIGHTS_URLoverride, standard OAuth Bearer (accepted, verified live).accountId[eq],timestamp[gte/lte], …).tollfree templateand portin TF automation.Validation
go test ./...green; live prod probes: Bearer token accepted by the Insights host, query encoding accepted (no 400), feature-gate 403 → exit 2 with mapped message, flag validation → exit 6 pre-HTTP. Happy path needs a Monitoring-enabled account (none available to this credential); envelope unwrap is unit-tested against spec examples and passes unexpected shapes through raw.Stacking
Based on#44 merged; rebased ontofeat/number-reads-tollfree(PR #44) — retarget tomainafter #44 lands.main.This PR was substantially AI-generated (Claude Code), reviewed and directed by @kshahbw.
🤖 Generated with Claude Code