wxcli 1.2.0__py3-none-any.whl

wxcli/_playbook/.claude/skills/reporting-cc/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: reporting-cc
+description: |
+  Query and analyze Webex Contact Center analytics: CC queue statistics, CC agent statistics,
+  estimated wait time, agent summaries, task search, and real-time CC monitoring.
+  Requires CC-scoped OAuth (cjp:config_read).
+  NOT for: Webex Calling CDR/queue/AA stats (use reporting skill) or
+  meetings/workspace analytics (use reporting-meetings skill).
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: [cc-report-type]
+---
+
+# Contact Center Analytics Workflow
+
+**Checkpoint — do NOT proceed until you can answer these:**
+1. What OAuth scope do CC analytics require? (Answer: `cjp:config_read` / `cjp:config_write` — standard admin tokens will NOT work.)
+2. How is the CC region configured? (Answer: `wxcli set-cc-region <region>` — defaults to us1.)
+
+If you cannot answer both, read `docs/reference/contact-center-analytics.md` before proceeding.
+
+## Step 1: Load references
+
+1. Read `docs/reference/contact-center-analytics.md` for CC analytics API details
+
+**Mandatory --help verification:** Before constructing any wxcli command, run `wxcli <group> --help` to verify the subcommand exists, then `wxcli <group> <subcommand> --help` to verify the exact flags (e.g. `wxcli cc-queue-stats --help` and `wxcli cc-agents --help` — CC analytics groups carry the `cc-` prefix and are distinct from the Calling `reporting` skill's groups). Do NOT rely on examples in this skill or reference docs — the CLI is auto-generated and flag names may differ from what documentation suggests.
+
+## Step 2: Verify auth and region
+
+```bash
+wxcli whoami
+```
+
+CC APIs require CJP scopes (`cjp:config_read` / `cjp:config_write`). Two options: **OAuth Integration** (user-facing apps, interactive login) or **Service App** (production automation, no interactive login needed). If the token lacks CC scopes, the user needs to re-authenticate with one of these.
+
+Verify region is set. There is no getter command — region is stored in the wxcli
+config file (`~/.wxcli/config.json`, `cc_region` key), set via `wxcli set-cc-region`.
+Inspect the config file directly, or just call `set-cc-region` to (re)set it:
+
+If not set, configure it:
+```bash
+wxcli set-cc-region us1
+```
+
+Available regions: us1, eu1, eu2, anz1, ca1, jp1, sg1.
+
+## Step 3: Identify the CC reporting need
+
+| Need | CLI Group | Command |
+|------|-----------|---------|
+| Queue volume, wait times, service level | `cc-queue-stats` | `list` |
+| Agent handle time, calls handled | `cc-agents` | `list-statistics` |
+| Current estimated wait time | `cc-ewt` | `show` |
+| AI-generated interaction summaries | `cc-agent-summaries` | `create`, `create-list` |
+| Historical task/contact search | `cc-search` | `create` |
+| Real-time queue/agent state | `cc-realtime` | `create` |
+| Call monitoring | `cc-call-monitoring` | 7 commands |
+
+## Step 4: Execute and analyze
+
+### Queue Statistics
+
+```bash
+wxcli cc-queue-stats list -o json
+```
+
+#### Recipe CC-1 — Queue volume ranking
+Question: "Which queue gets the most calls?"
+```bash
+wxcli cc-queue-stats list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for q in sorted(items, key=lambda x: x.get('totalCalls', x.get('callsOffered', 0)), reverse=True):
+    name = q.get('queueName', q.get('name', '?'))
+    calls = q.get('totalCalls', q.get('callsOffered', 0))
+    print(f'{name}: {calls} calls')
+"
+```
+
+#### Recipe CC-2 — Queue abandonment rate
+Question: "What's our abandonment rate per queue?"
+```bash
+wxcli cc-queue-stats list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for q in items:
+    name = q.get('queueName', q.get('name', '?'))
+    total = q.get('totalCalls', q.get('callsOffered', 0))
+    abandoned = q.get('callsAbandoned', 0)
+    rate = abandoned/total*100 if total else 0
+    print(f'{name}: {rate:.1f}% abandoned ({abandoned}/{total})')
+"
+```
+
+#### Recipe CC-3 — Average wait time per queue
+Question: "How long are callers waiting?"
+```bash
+wxcli cc-queue-stats list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for q in sorted(items, key=lambda x: x.get('avgWaitTime', x.get('averageWaitTime', 0)), reverse=True):
+    name = q.get('queueName', q.get('name', '?'))
+    wait = q.get('avgWaitTime', q.get('averageWaitTime', 0))
+    print(f'{name}: avg {wait}s wait')
+"
+```
+
+#### Recipe CC-4 — Service level by queue
+Question: "Are we meeting our SLA?"
+```bash
+wxcli cc-queue-stats list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for q in items:
+    name = q.get('queueName', q.get('name', '?'))
+    sl = q.get('serviceLevel', q.get('serviceLevelPercentage', 'N/A'))
+    print(f'{name}: {sl}% service level')
+"
+```
+
+### Agent Statistics
+
+```bash
+wxcli cc-agents list-statistics -o json
+```
+
+#### Recipe CC-5 — Agent handle time ranking
+Question: "Which agents are fastest/slowest?"
+```bash
+wxcli cc-agents list-statistics -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for a in sorted(items, key=lambda x: x.get('avgHandleTime', x.get('averageHandleTime', 0)), reverse=True):
+    name = a.get('agentName', a.get('name', '?'))
+    aht = a.get('avgHandleTime', a.get('averageHandleTime', 0))
+    print(f'{name}: avg {aht}s handle time')
+"
+```
+
+#### Recipe CC-6 — Agent utilization
+Question: "How busy is each agent?"
+```bash
+wxcli cc-agents list-statistics -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for a in sorted(items, key=lambda x: x.get('callsHandled', x.get('totalCalls', 0)), reverse=True):
+    name = a.get('agentName', a.get('name', '?'))
+    handled = a.get('callsHandled', a.get('totalCalls', 0))
+    print(f'{name}: {handled} calls handled')
+"
+```
+
+### Estimated Wait Time
+
+#### Recipe CC-7 — Current wait time check
+Question: "What's the current wait for queue X?"
+```bash
+wxcli cc-ewt show -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+if isinstance(data, dict):
+    print(f\"Estimated wait time: {data.get('estimatedWaitTime', data.get('ewt', 'N/A'))}s\")
+else:
+    for q in data:
+        print(f\"{q.get('queueName', '?')}: {q.get('estimatedWaitTime', q.get('ewt', 'N/A'))}s\")
+"
+```
+
+### Agent Summaries
+
+#### Recipe CC-8 — Search interaction summaries
+Question: "Find summaries mentioning billing disputes"
+```bash
+wxcli cc-agent-summaries create --json-body '{"query": "billing dispute"}' -o json
+```
+
+### Real-Time Monitoring
+
+#### Recipe CC-9 — Real-time queue depth
+Question: "How many callers are waiting right now?"
+```bash
+wxcli cc-realtime create -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+if isinstance(data, list):
+    for q in data:
+        print(f\"{q.get('queueName', '?')}: {q.get('callsInQueue', q.get('waitingCalls', 0))} waiting\")
+else:
+    print(json.dumps(data, indent=2))
+"
+```
+
+#### Recipe CC-10 — Agent availability status
+Question: "Who's available right now?"
+```bash
+wxcli cc-agents list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+from collections import Counter
+states = Counter(a.get('state', a.get('agentState', 'Unknown')) for a in items)
+for state, count in states.most_common():
+    print(f'{state}: {count} agents')
+"
+```
+
+### Historical Search
+
+#### Recipe CC-11 — Search tasks by date range
+Question: "Show all contacts handled yesterday"
+```bash
+wxcli cc-search create --json-body '{"from": "2026-04-09T00:00:00Z", "to": "2026-04-10T00:00:00Z"}' -o json
+```
+
+#### Recipe CC-12 — Longest wait today
+Question: "What was the worst wait time today?"
+```bash
+wxcli cc-queue-stats list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+longest = max(items, key=lambda x: x.get('maxWaitTime', x.get('longestWaitTime', 0)), default={})
+name = longest.get('queueName', longest.get('name', '?'))
+wait = longest.get('maxWaitTime', longest.get('longestWaitTime', 0))
+print(f'Longest wait: {wait}s in queue {name}')
+"
+```
+
+---
+
+## Critical Rules
+
+1. **CC-scoped OAuth or Service App required.** Standard admin tokens get 403. Must use `cjp:config_read` / `cjp:config_write` — via OAuth Integration or Service App (both supported).
+2. **Region must be set.** CC APIs route to regional endpoints. Default is us1.
+3. **Response shapes vary.** CC APIs may return objects or arrays. Recipes handle both with `isinstance` checks.
+4. **Field names vary.** Different CC API versions use different field names (e.g., `avgWaitTime` vs `averageWaitTime`). Recipes use fallbacks with `x.get('field1', x.get('field2', 0))`.
+5. **Real-time data is ephemeral.** Snapshot of current state, not historical.
+
+---
+
+## Context Compaction Recovery
+
+If context compacts mid-execution:
+1. Read `docs/reference/contact-center-analytics.md` for API details
+2. Verify CC auth with `wxcli whoami` and region — check `cc_region` in `~/.wxcli/config.json` (no getter command; set/reset via `wxcli set-cc-region`)
+3. Resume from the appropriate recipe

wxcli/_playbook/.claude/skills/reporting-meetings/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: reporting-meetings
+description: |
+  Query and analyze Webex meetings quality, usage reports, workspace utilization,
+  historical platform analytics, and live meeting monitoring.
+  NOT for: Webex Calling CDR/queue stats (use reporting skill), Contact Center analytics
+  (use reporting-cc skill), or scheduling/managing meetings (use manage-meetings skill).
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: [meetings-report-type]
+---
+
+# Meetings & Workspace Analytics Workflow
+
+**Checkpoint — do NOT proceed until you can answer these:**
+1. Which CLI group provides per-meeting quality data in JSON? (Answer: `wxcli meeting-qualities` — returns jitter, latency, packet loss per media session. Faster than async CSV reports for single-meeting troubleshooting.)
+2. Which CLI group provides historical platform analytics? (Answer: `wxcli analytics` — messaging daily totals, room device metrics, meetings aggregates.)
+
+If you cannot answer both, read `docs/reference/meetings-infrastructure.md` and `docs/reference/reporting-analytics.md` before proceeding.
+
+## Step 1: Load references
+
+1. Read `docs/reference/meetings-infrastructure.md` for meeting quality, participants, Video Mesh
+2. Read `docs/reference/meetings-core.md` for meeting CRUD and reports
+3. Read `docs/reference/reporting-analytics.md` Section 2-3 for report templates
+
+**Mandatory --help verification:** Before constructing any wxcli command, run `wxcli <group> --help` to verify the subcommand exists, then `wxcli <group> <subcommand> --help` to verify the exact flags (e.g. `wxcli meeting-qualities --help` and `wxcli meeting-reports --help`). Do NOT rely on examples in this skill or reference docs — the CLI is auto-generated and flag names may differ from what documentation suggests.
+
+## Step 2: Verify auth token
+
+```bash
+wxcli whoami
+```
+
+### Required scopes
+
+| Report Type | Scope |
+|-------------|-------|
+| Meeting quality | `analytics:read_all` |
+| Meeting usage/attendees | `analytics:read_all` |
+| Historical analytics | `analytics:read_all` |
+| Workspace metrics | `spark-admin:workspace_metrics_read` |
+| Live monitoring | `analytics:read_all` |
+
+## Step 3: Identify the reporting need
+
+| Need | CLI Group | Command |
+|------|-----------|---------|
+| Quality for a specific meeting (jitter, latency, loss) | `meeting-qualities` | `list` |
+| Meeting usage trends | `meeting-reports` | `list` |
+| Meeting attendee details | `meeting-reports` | `list-attendees` |
+| Historical messaging metrics | `analytics` | `show` |
+| Historical room device metrics | `analytics` | `show-daily-totals` |
+| Historical meetings aggregates | `analytics` | `show-aggregates` |
+| Workspace usage | `workspace-metrics` | `list` |
+| Workspace duration | `workspace-metrics` | `list-workspace-duration-metrics` |
+| Live meeting counts | `live-monitoring` | `create` |
+
+## Step 4: Execute and analyze
+
+### Meeting Quality
+
+```bash
+wxcli meeting-qualities list --meeting-id MEETING_ID -o json
+```
+
+#### Recipe M-1 — Meeting quality for a specific meeting
+Question: "How was the quality on yesterday's all-hands?"
+```bash
+wxcli meeting-qualities list --meeting-id MEETING_ID -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for p in items:
+    name = p.get('participantName', p.get('displayName', '?'))
+    jitter = p.get('audioJitter', p.get('jitter', 'N/A'))
+    latency = p.get('audioLatency', p.get('latency', 'N/A'))
+    loss = p.get('audioPacketLoss', p.get('packetLoss', 'N/A'))
+    print(f'{name}: jitter={jitter}ms latency={latency}ms loss={loss}%')
+"
+```
+
+#### Recipe M-2 — Quality issues in a meeting
+Question: "Did anyone have bad quality?"
+```bash
+wxcli meeting-qualities list --meeting-id MEETING_ID -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+issues = []
+for p in items:
+    name = p.get('participantName', p.get('displayName', '?'))
+    jitter = float(p.get('audioJitter', p.get('jitter', 0)) or 0)
+    latency = float(p.get('audioLatency', p.get('latency', 0)) or 0)
+    loss = float(p.get('audioPacketLoss', p.get('packetLoss', 0)) or 0)
+    if jitter > 30 or latency > 200 or loss > 5:
+        issues.append(f'{name}: jitter={jitter}ms latency={latency}ms loss={loss}%')
+if issues:
+    print(f'{len(issues)} participants with quality issues:')
+    for i in issues: print(f'  {i}')
+else:
+    print('No quality issues detected (thresholds: jitter>30ms, latency>200ms, loss>5%)')
+"
+```
+
+### Meeting Usage
+
+#### Recipe M-3 — Meeting usage summary
+Question: "How many meetings are we having?"
+```bash
+wxcli meeting-reports list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+print(f'Meeting usage reports: {len(items)}')
+for r in items[:10]:
+    print(f\"  {r.get('meetingDate', r.get('date', '?'))}: {r.get('totalMeetings', r.get('meetingCount', '?'))} meetings\")
+"
+```
+
+#### Recipe M-4 — Meeting attendance
+Question: "How many invitees actually joined?"
+```bash
+wxcli meeting-reports list-attendees --meeting-id MEETING_ID -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+attended = [a for a in items if a.get('attended', a.get('joined', False))]
+print(f'Attendees: {len(attended)} of {len(items)} ({len(attended)/len(items)*100:.1f}%)' if items else 'No data')
+"
+```
+
+### Historical Analytics
+
+#### Recipe M-5 — Messaging adoption trend
+Question: "Is messaging usage growing?"
+```bash
+wxcli analytics show -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for d in items[:14]:
+    print(f\"{d.get('date', '?')}: {d.get('totalMessages', d.get('messages', '?'))} messages\")
+"
+```
+
+#### Recipe M-6 — Room device utilization
+Question: "Are our room devices being used?"
+```bash
+wxcli analytics show-daily-totals -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for d in items[:14]:
+    print(f\"{d.get('date', '?')}: {d.get('activatedDevices', d.get('activeDevices', '?'))} active devices\")
+"
+```
+
+#### Recipe M-7 — Meetings aggregate comparison
+Question: "How do this month's meetings compare?"
+```bash
+wxcli analytics show-aggregates -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+if isinstance(data, dict):
+    for key, val in data.items():
+        print(f'{key}: {val}')
+else:
+    print(json.dumps(data, indent=2))
+"
+```
+
+### Workspace Metrics
+
+#### Recipe M-8 — Workspace occupancy
+Question: "Which rooms are used the most?"
+```bash
+wxcli workspace-metrics list -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for w in sorted(items, key=lambda x: x.get('utilizationPercentage', x.get('occupancy', 0)), reverse=True)[:15]:
+    name = w.get('workspaceName', w.get('name', '?'))
+    util = w.get('utilizationPercentage', w.get('occupancy', 0))
+    print(f'{name}: {util}% utilized')
+"
+```
+
+#### Recipe M-9 — Workspace duration analysis
+Question: "How long are rooms occupied on average?"
+```bash
+wxcli workspace-metrics list-workspace-duration-metrics -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for w in sorted(items, key=lambda x: x.get('averageDuration', x.get('avgDuration', 0)), reverse=True)[:15]:
+    name = w.get('workspaceName', w.get('name', '?'))
+    dur = w.get('averageDuration', w.get('avgDuration', 0))
+    print(f'{name}: avg {dur/60:.1f} min per session')
+"
+```
+
+### Live Monitoring
+
+#### Recipe M-10 — Live meetings right now
+Question: "How many meetings are happening globally?"
+```bash
+wxcli live-monitoring create -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+if isinstance(data, dict):
+    for country, count in sorted(data.items(), key=lambda x: x[1] if isinstance(x[1], (int,float)) else 0, reverse=True):
+        print(f'{country}: {count}')
+else:
+    print(json.dumps(data, indent=2))
+"
+```
+
+#### Recipe M-11 — Quality by participant (recurring issues)
+Question: "Who has recurring quality issues across meetings?"
+Note: Requires multiple meeting quality pulls. Run for each recent meeting ID.
+```bash
+wxcli meeting-qualities list --meeting-id MEETING_ID_1 -o json > /tmp/mq1.json
+wxcli meeting-qualities list --meeting-id MEETING_ID_2 -o json > /tmp/mq2.json
+python3.11 -c "
+import json
+from collections import defaultdict
+issues = defaultdict(int)
+for f in ['/tmp/mq1.json', '/tmp/mq2.json']:
+    data = json.load(open(f))
+    items = data if isinstance(data, list) else data.get('items', [data])
+    for p in items:
+        name = p.get('participantName', p.get('displayName', '?'))
+        jitter = float(p.get('audioJitter', p.get('jitter', 0)) or 0)
+        latency = float(p.get('audioLatency', p.get('latency', 0)) or 0)
+        loss = float(p.get('audioPacketLoss', p.get('packetLoss', 0)) or 0)
+        if jitter > 30 or latency > 200 or loss > 5:
+            issues[name] += 1
+for name, count in sorted(issues.items(), key=lambda x: x[1], reverse=True):
+    print(f'{name}: quality issues in {count} meetings')
+"
+```
+
+#### Recipe M-12 — Attendee report for compliance
+Question: "Who attended this meeting?"
+```bash
+wxcli meeting-reports list-attendees --meeting-id MEETING_ID -o json | python3.11 -c "
+import json, sys
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+for a in items:
+    name = a.get('displayName', a.get('name', '?'))
+    email = a.get('email', '?')
+    joined = a.get('joinTime', a.get('joinedTime', '?'))
+    left = a.get('leaveTime', a.get('leftTime', '?'))
+    print(f'{name} ({email}): joined {joined}, left {left}')
+"
+```
+
+#### Recipe M-13 — Top meeting hosts
+Question: "Who schedules the most meetings?"
+```bash
+wxcli meeting-reports list -o json | python3.11 -c "
+import json, sys
+from collections import Counter
+data = json.load(sys.stdin)
+items = data if isinstance(data, list) else data.get('items', [data])
+hosts = Counter(r.get('hostEmail', r.get('hostName', '?')) for r in items)
+for host, count in hosts.most_common(15):
+    print(f'{host}: {count} meetings')
+"
+```
+
+---
+
+## Critical Rules
+
+1. **Meeting quality requires a meeting ID.** Use `wxcli meetings list` to find meeting IDs first.
+2. **Historical analytics may require Pro Pack.** Depends on the data type.
+3. **Live monitoring is a snapshot.** Data is current, not historical.
+4. **Workspace metrics require workspace admin scope.** `spark-admin:workspace_metrics_read`.
+5. **Response shapes vary across API versions.** Recipes use `isinstance` checks and field fallbacks.
+
+---
+
+## Context Compaction Recovery
+
+If context compacts mid-execution:
+1. Read `docs/reference/meetings-infrastructure.md` for meeting quality API details
+2. Read `docs/reference/reporting-analytics.md` for report template details
+3. Resume from the appropriate recipe