wxcli 1.2.0__py3-none-any.whl

wxcli/commands/cucm_config.py

@@ -0,0 +1,129 @@
+"""Configuration management for CUCM migration projects.
+
+Manages config.json in the project directory. Keys control pipeline behavior
+(country code, language, auto-rules, etc.).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+# Default auto-resolution rules for clear-cut, low-risk decisions.
+#
+# These reduce manual review burden without risking incorrect choices.
+# Override per-project by writing "auto_rules" to config.json.
+#
+# IMPORTANT: Defaults are seeded into a project's `config.json` ONCE by
+# `wxcli cucm init`. They are NOT applied at runtime — `load_config()`
+# reads the saved file literally. Operators who edit `config.json` to
+# remove a default can restore it via `wxcli cucm config reset auto_rules`
+# (which clobbers any custom rules in `auto_rules` — preserve them by
+# hand-editing instead).
+#
+# To add a new default rule WITHOUT regressing existing in-flight projects:
+# 1. Append the rule here.
+# 2. Document the upgrade procedure in the relevant runbook.
+# 3. Operators on existing projects must either (a) hand-edit their
+#    config.json to append the new rule, or (b) run
+#    `wxcli cucm config reset auto_rules` (destructive to custom rules).
+DEFAULT_AUTO_RULES: list[dict[str, Any]] = [
+    # Incompatible devices have no migration path — always skip
+    {"type": "DEVICE_INCOMPATIBLE", "choice": "skip",
+     "reason": "No MPP migration path exists for this device"},
+    # NOTE: DEVICE_FIRMWARE_CONVERTIBLE was removed 2026-04-15. Convertibility
+    # is now a phone model classification, not an operator choice — the
+    # planner emits a create_activation_code op unconditionally for every
+    # convertible device.
+    # Hotdesk DN conflicts — primary DN always wins
+    {"type": "HOTDESK_DN_CONFLICT", "choice": "keep_primary",
+     "reason": "Primary DN takes precedence over hotdesk conflict"},
+    # CUCM-only forwarding variants — accept the loss (rarely configured)
+    {"type": "FORWARDING_LOSSY", "choice": "accept",
+     "reason": "CUCM-specific forwarding variant has no Webex equivalent"},
+    # SNR timer controls — accept Webex simplification
+    {"type": "SNR_LOSSY", "choice": "accept",
+     "reason": "SNR timer controls are simplified in Webex"},
+    # Unmappable CUCM button types — no Webex equivalent exists
+    {"type": "BUTTON_UNMAPPABLE", "choice": "accept_loss",
+     "reason": "CUCM button type has no Webex equivalent"},
+    # Calling permissions with 0 affected users — orphaned profile
+    # Analyzer writes "assigned_users_count" in context (css_permission.py line 128)
+    {"type": "CALLING_PERMISSION_MISMATCH",
+     "match": {"assigned_users_count": 0}, "choice": "skip",
+     "reason": "Orphaned permission profile — 0 users affected"},
+    # Missing data on devices that are already incompatible — skip
+    # (fixing missing data on a device we're not migrating is pointless)
+    # `is_on_incompatible_device` is written by
+    # enrich_cross_decision_context() during analysis_pipeline step 3.5.
+    {"type": "MISSING_DATA",
+     "match": {"is_on_incompatible_device": True}, "choice": "skip",
+     "reason": "Missing data on incompatible device — skipping device anyway"},
+]
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "country_code": "+1",
+    "default_language": "en_us",
+    "default_country": "US",
+    "outside_dial_digit": "9",
+    "create_method": "people_api",
+    "include_phoneless_users": False,
+    "auto_rules": DEFAULT_AUTO_RULES,
+    "recording_vendor": "Webex",
+    "site_prefix_rules": [],
+    "category_rules": None,
+    # Execution tuning (from 2026-04-10-bulk-operations spec §5b).
+    # Device count at/above which the planner replaces per-device ops with
+    # Webex bulk job submissions. Set to 0 to force bulk always; set to a
+    # very large number (e.g., 999999) to disable bulk.
+    "bulk_device_threshold": 100,
+    # FedRAMP / Webex for Government: rebuildPhones is not supported.
+    # Set to True to omit bulk_rebuild_phones ops from the plan.
+    "skip_rebuild_phones": False,
+    "e911": {
+        "auto_configure_ecbn": True,
+        "notification_email": None,
+        "redsky_enabled": False,
+        "primary_did_strategy": "first_line",
+    },
+}
+
+
+def load_config(project_dir: Path) -> dict[str, Any]:
+    """Load config.json from the project directory, with defaults."""
+    config_path = project_dir / "config.json"
+    config = dict(DEFAULT_CONFIG)
+    if config_path.exists():
+        with open(config_path) as f:
+            saved = json.load(f)
+        config.update(saved)
+    return config
+
+
+def save_config(project_dir: Path, config: dict[str, Any]) -> None:
+    """Write config.json to the project directory."""
+    config_path = project_dir / "config.json"
+    with open(config_path, "w") as f:
+        json.dump(config, f, indent=2)
+
+
+def coerce_value(value: str) -> Any:
+    """Coerce a string CLI value to the appropriate Python type."""
+    if value.lower() in ("true", "yes"):
+        return True
+    if value.lower() in ("false", "no"):
+        return False
+    try:
+        n = int(value)
+        # Only coerce if round-trip matches (preserves "+44" as string)
+        if str(n) == value:
+            return n
+    except ValueError:
+        pass
+    try:
+        return json.loads(value)
+    except (json.JSONDecodeError, ValueError):
+        pass
+    return value

wxcli/commands/customer_assist.py

@@ -0,0 +1,373 @@
+import json
+import typer
+from wxcli.auth import get_api
+from wxcli.errors import WebexError, handle_rest_error
+from wxcli.output import print_table, print_json
+from wxcli.config import get_org_id
+
+
+app = typer.Typer(help="Manage Webex Calling customer-assist.")
+
+
+@app.command("list")
+def cmd_list(
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table|json"),
+    limit: int = typer.Option(0, "--limit", help="Max results (0=all for paginated endpoints, API default for non-paginated)"),
+    offset: int = typer.Option(0, "--offset", help="Start offset"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """List Wrap Up Reasons."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/wrapup/reasons"
+    params = {}
+    if limit > 0:
+        params["max"] = limit
+    if offset > 0:
+        params["start"] = offset
+    result = None
+    try:
+        result = api.session.rest_get(url, params=params)
+    except WebexError as e:
+        handle_rest_error(e)
+    result = result or []
+    items = result.get("wrapupReasons", result.get("data", result if isinstance(result, list) else [])) if isinstance(result, dict) else (result if isinstance(result, list) else [])
+    if output == "json":
+        print_json(items)
+    else:
+        print_table(items, columns=[("ID", "id"), ("Name", "name")], limit=limit)
+
+
+
+@app.command("create")
+def create(
+    name: str = typer.Option(None, "--name", help="(required) Name of the wrap-up reason."),
+    description: str = typer.Option(None, "--description", help="Description of the wrap-up reason."),
+    assign_all_queues_enabled: bool = typer.Option(None, "--assign-all-queues-enabled/--no-assign-all-queues-enabled", help="Denotes whether all queues are assigned to the wrap-up reaso"),
+    json_body: str = typer.Option(None, "--json-body", help="Full JSON body (overrides other options)"),
+    output: str = typer.Option("id", "--output", "-o", help="Output format: id|json"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Create Wrap Up Reason\n\nExample --json-body:\n  '{"name":"...","description":"...","queues":["..."],"assignAllQueuesEnabled":true}'."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/wrapup/reasons"
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if assign_all_queues_enabled is not None:
+            body["assignAllQueuesEnabled"] = assign_all_queues_enabled
+        _missing = [f for f in ['name'] if f not in body or body[f] is None]
+        if _missing:
+            typer.echo("Error: Missing required fields: " + ", ".join(_missing), err=True)
+            raise typer.Exit(1)
+    try:
+        result = api.session.rest_post(url, json=body)
+    except WebexError as e:
+        handle_rest_error(e)
+    if output == "json":
+        print_json(result)
+    elif isinstance(result, dict) and "id" in result:
+        typer.echo(f"Created: {result['id']}")
+    elif not result or result == {}:
+        typer.echo("Created.")
+    else:
+        print_json(result)
+
+
+
+@app.command("show")
+def show(
+    wrapup_reason_id: str = typer.Argument(help="wrapupReasonId"),
+    output: str = typer.Option("json", "--output", "-o", help="Output format: table|json"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Read Wrap Up Reason."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/wrapup/reasons/{wrapup_reason_id}"
+    try:
+        result = api.session.rest_get(url)
+    except WebexError as e:
+        handle_rest_error(e)
+    if output == "json":
+        print_json(result)
+    else:
+        if isinstance(result, dict):
+            print_table([result], columns=[("Key", ""), ("Value", "")], limit=0)
+        elif isinstance(result, list):
+            print_table(result, columns=[("ID", "id"), ("Name", "name")], limit=0)
+        else:
+            print_json(result)
+
+
+
+@app.command("update")
+def update(
+    wrapup_reason_id: str = typer.Argument(help="wrapupReasonId"),
+    name: str = typer.Option(None, "--name", help="Name of the wrap-up reason."),
+    description: str = typer.Option(None, "--description", help="Description of the wrap-up reason."),
+    assign_all_queues_enabled: bool = typer.Option(None, "--assign-all-queues-enabled/--no-assign-all-queues-enabled", help="Denotes whether all queues are assigned to the wrap-up reaso"),
+    unassign_all_queues_enabled: bool = typer.Option(None, "--unassign-all-queues-enabled/--no-unassign-all-queues-enabled", help="Denotes whether all queues are unassigned from the wrap-up r"),
+    json_body: str = typer.Option(None, "--json-body", help="Full JSON body (overrides other options)"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Update Wrap Up Reason\n\nExample --json-body:\n  '{"name":"...","description":"...","queuesToAssign":["..."],"queuesToUnassign":["..."],"assignAllQueuesEnabled":true,"unassignAllQueuesEnabled":true}'."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/wrapup/reasons/{wrapup_reason_id}"
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if assign_all_queues_enabled is not None:
+            body["assignAllQueuesEnabled"] = assign_all_queues_enabled
+        if unassign_all_queues_enabled is not None:
+            body["unassignAllQueuesEnabled"] = unassign_all_queues_enabled
+    try:
+        result = api.session.rest_put(url, json=body)
+    except WebexError as e:
+        handle_rest_error(e)
+    typer.echo(f"Updated.")
+
+
+
+@app.command("delete")
+def delete(
+    wrapup_reason_id: str = typer.Argument(help="wrapupReasonId"),
+    force: bool = typer.Option(False, "--force", help="Skip confirmation"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Delete Wrap Up Reason."""
+    if not force:
+        typer.confirm(f"Delete {wrapup_reason_id}?", abort=True)
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/wrapup/reasons/{wrapup_reason_id}"
+    try:
+        api.session.rest_delete(url)
+    except WebexError as e:
+        handle_rest_error(e)
+    typer.echo(f"Deleted: {wrapup_reason_id}")
+
+
+
+@app.command("validate-wrap-up")
+def validate_wrap_up(
+    name: str = typer.Option(None, "--name", help="Name of the wrap-up reason."),
+    json_body: str = typer.Option(None, "--json-body", help="Full JSON body"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Validate Wrap Up Reason."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/wrapup/reasons/actions/validateName/invoke"
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if name is not None:
+            body["name"] = name
+    try:
+        result = api.session.rest_post(url, json=body)
+    except WebexError as e:
+        handle_rest_error(e)
+    print_json(result)
+
+
+
+@app.command("list-available-queues")
+def list_available_queues(
+    wrapup_reason_id: str = typer.Argument(help="wrapupReasonId"),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table|json"),
+    limit: int = typer.Option(0, "--limit", help="Max results (0=all for paginated endpoints, API default for non-paginated)"),
+    offset: int = typer.Option(0, "--offset", help="Start offset"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Read Available Queues."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/wrapup/reasons/{wrapup_reason_id}/availableQueues"
+    params = {}
+    if limit > 0:
+        params["max"] = limit
+    if offset > 0:
+        params["start"] = offset
+    result = None
+    try:
+        result = api.session.rest_get(url, params=params)
+    except WebexError as e:
+        handle_rest_error(e)
+    result = result or []
+    items = result.get("queues", result.get("data", result if isinstance(result, list) else [])) if isinstance(result, dict) else (result if isinstance(result, list) else [])
+    if output == "json":
+        print_json(items)
+    else:
+        print_table(items, columns=[("ID", "id"), ("Name", "name")], limit=limit)
+
+
+
+@app.command("list-settings")
+def list_settings(
+    location_id: str = typer.Argument(help="locationId"),
+    queue_id: str = typer.Argument(help="queueId"),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table|json"),
+    limit: int = typer.Option(0, "--limit", help="Max results (0=all for paginated endpoints, API default for non-paginated)"),
+    offset: int = typer.Option(0, "--offset", help="Start offset"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Read Wrap Up Reason Settings."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/locations/{location_id}/queues/{queue_id}/wrapup/settings"
+    params = {}
+    if limit > 0:
+        params["max"] = limit
+    if offset > 0:
+        params["start"] = offset
+    result = None
+    try:
+        result = api.session.rest_get(url, params=params)
+    except WebexError as e:
+        handle_rest_error(e)
+    result = result or []
+    items = result.get("wrapupReasons", result.get("data", result if isinstance(result, list) else [])) if isinstance(result, dict) else (result if isinstance(result, list) else [])
+    if output == "json":
+        print_json(items)
+    else:
+        print_table(items, columns=[("ID", "id"), ("Name", "name")], limit=limit)
+
+
+
+@app.command("update-settings")
+def update_settings(
+    location_id: str = typer.Argument(help="locationId"),
+    queue_id: str = typer.Argument(help="queueId"),
+    default_wrapup_reason_id: str = typer.Option(None, "--default-wrapup-reason-id", help="Unique wrap-up identifier."),
+    wrapup_timer_enabled: bool = typer.Option(None, "--wrapup-timer-enabled/--no-wrapup-timer-enabled", help="Denotes whether the wrap-up timer is enabled."),
+    wrapup_timer: str = typer.Option(None, "--wrapup-timer", help="Wrap up timer value in seconds."),
+    json_body: str = typer.Option(None, "--json-body", help="Full JSON body (overrides other options)"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Update Wrap Up Reason Settings\n\nExample --json-body:\n  '{"wrapupReasons":["..."],"defaultWrapupReasonId":"...","wrapupTimerEnabled":true,"wrapupTimer":0}'."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/cxEssentials/locations/{location_id}/queues/{queue_id}/wrapup/settings"
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if default_wrapup_reason_id is not None:
+            body["defaultWrapupReasonId"] = default_wrapup_reason_id
+        if wrapup_timer_enabled is not None:
+            body["wrapupTimerEnabled"] = wrapup_timer_enabled
+        if wrapup_timer is not None:
+            body["wrapupTimer"] = wrapup_timer
+    try:
+        result = api.session.rest_put(url, json=body)
+    except WebexError as e:
+        handle_rest_error(e)
+    typer.echo(f"Updated.")
+
+
+
+@app.command("show-screen-pop")
+def show_screen_pop(
+    location_id: str = typer.Argument(help="locationId"),
+    queue_id: str = typer.Argument(help="queueId"),
+    output: str = typer.Option("json", "--output", "-o", help="Output format: table|json"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Read Screen Pop Configuration."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/locations/{location_id}/queues/{queue_id}/cxEssentials/screenPop"
+    params = {}
+    org_id = get_org_id()
+    if org_id is not None:
+        params["orgId"] = org_id
+    try:
+        result = api.session.rest_get(url, params=params)
+    except WebexError as e:
+        handle_rest_error(e)
+    if output == "json":
+        print_json(result)
+    else:
+        if isinstance(result, dict):
+            print_table([result], columns=[("Key", ""), ("Value", "")], limit=0)
+        elif isinstance(result, list):
+            print_table(result, columns=[("ID", "id"), ("Name", "name")], limit=0)
+        else:
+            print_json(result)
+
+
+
+@app.command("update-screen-pop")
+def update_screen_pop(
+    location_id: str = typer.Argument(help="locationId"),
+    queue_id: str = typer.Argument(help="queueId"),
+    enabled: bool = typer.Option(None, "--enabled/--no-enabled", help="Enable/disable screen pop."),
+    screen_pop_url: str = typer.Option(None, "--screen-pop-url", help="The screen pop URL that integrates Webex calls with other bu"),
+    desktop_label: str = typer.Option(None, "--desktop-label", help="A label for the screen pop configuration."),
+    json_body: str = typer.Option(None, "--json-body", help="Full JSON body (overrides other options)"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Update Screen Pop Configuration\n\nExample --json-body:\n  '{"enabled":true,"screenPopUrl":"...","desktopLabel":"...","queryParams":{"example_param_1":"...","example_param_2":"...","example_param_3":"..."}}'."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/locations/{location_id}/queues/{queue_id}/cxEssentials/screenPop"
+    params = {}
+    org_id = get_org_id()
+    if org_id is not None:
+        params["orgId"] = org_id
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if enabled is not None:
+            body["enabled"] = enabled
+        if screen_pop_url is not None:
+            body["screenPopUrl"] = screen_pop_url
+        if desktop_label is not None:
+            body["desktopLabel"] = desktop_label
+    try:
+        result = api.session.rest_put(url, json=body, params=params)
+    except WebexError as e:
+        handle_rest_error(e)
+    typer.echo(f"Updated.")
+
+
+
+@app.command("list-available-agents")
+def list_available_agents(
+    location_id: str = typer.Argument(help="locationId"),
+    has_cx_essentials: str = typer.Option(None, "--has-cx-essentials", help="Returns only the list of available agents with Customer Assi"),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table|json"),
+    limit: int = typer.Option(0, "--limit", help="Max results (0=all for paginated endpoints, API default for non-paginated)"),
+    offset: int = typer.Option(0, "--offset", help="Start offset"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """List Available Agents."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/telephony/config/locations/{location_id}/cxEssentials/agents/availableAgents"
+    params = {}
+    if has_cx_essentials is not None:
+        params["hasCxEssentials"] = has_cx_essentials
+    if limit > 0:
+        params["max"] = limit
+    if offset > 0:
+        params["start"] = offset
+    org_id = get_org_id()
+    if org_id is not None:
+        params["orgId"] = org_id
+    result = None
+    try:
+        result = api.session.rest_get(url, params=params)
+    except WebexError as e:
+        handle_rest_error(e)
+    result = result or []
+    items = result.get("agents", result.get("data", result if isinstance(result, list) else [])) if isinstance(result, dict) else (result if isinstance(result, list) else [])
+    if output == "json":
+        print_json(items)
+    else:
+        print_table(items, columns=[("ID", "id"), ("Name", "name")], limit=limit)
+
+