wxcli 1.2.0__py3-none-any.whl

wxcli/commands/workspaces.py

@@ -0,0 +1,279 @@
+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 workspaces.")
+
+
+@app.command("list")
+def cmd_list(
+    location_id: str = typer.Option(None, "--location-id", help="Location associated with the workspace. Values must originat"),
+    workspace_location_id: str = typer.Option(None, "--workspace-location-id", help="Location associated with the workspace. Both values from the"),
+    floor_id: str = typer.Option(None, "--floor-id", help="Floor associated with the workspace."),
+    display_name: str = typer.Option(None, "--display-name", help="List workspaces by display name."),
+    capacity: str = typer.Option(None, "--capacity", help="List workspaces with the given capacity. Must be -1 or highe"),
+    type_param: str = typer.Option(None, "--type", help="Choices: notSet, focus, huddle, meetingRoom, open, desk, other"),
+    calling: str = typer.Option(None, "--calling", help="Choices: freeCalling, hybridCalling, webexCalling, webexEdgeForDevices, thirdPartySipCalling, none"),
+    supported_devices: str = typer.Option(None, "--supported-devices", help="Choices: collaborationDevices, phones"),
+    calendar: str = typer.Option(None, "--calendar", help="Choices: none, google, microsoft"),
+    device_hosted_meetings_enabled: str = typer.Option(None, "--device-hosted-meetings-enabled", help="List workspaces enabled for device hosted meetings."),
+    device_platform: str = typer.Option(None, "--device-platform", help="Choices: cisco, microsoftTeamsRoom"),
+    health_level: str = typer.Option(None, "--health-level", help="Choices: error, warning, info, ok"),
+    include_devices: str = typer.Option(None, "--include-devices", help="Flag identifying whether to include the devices associated w"),
+    include_capabilities: str = typer.Option(None, "--include-capabilities", help="Flag identifying whether to include the workspace capabiliti"),
+    planned_maintenance: str = typer.Option(None, "--planned-maintenance", help="Choices: off, on, upcoming"),
+    custom_attribute: str = typer.Option(None, "--custom-attribute", help="List workspaces with given custom attribute key."),
+    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 Workspaces."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/workspaces"
+    params = {}
+    if location_id is not None:
+        params["locationId"] = location_id
+    if workspace_location_id is not None:
+        params["workspaceLocationId"] = workspace_location_id
+    if floor_id is not None:
+        params["floorId"] = floor_id
+    if display_name is not None:
+        params["displayName"] = display_name
+    if capacity is not None:
+        params["capacity"] = capacity
+    if type_param is not None:
+        params["type"] = type_param
+    if calling is not None:
+        params["calling"] = calling
+    if supported_devices is not None:
+        params["supportedDevices"] = supported_devices
+    if calendar is not None:
+        params["calendar"] = calendar
+    if device_hosted_meetings_enabled is not None:
+        params["deviceHostedMeetingsEnabled"] = device_hosted_meetings_enabled
+    if device_platform is not None:
+        params["devicePlatform"] = device_platform
+    if health_level is not None:
+        params["healthLevel"] = health_level
+    if include_devices is not None:
+        params["includeDevices"] = include_devices
+    if include_capabilities is not None:
+        params["includeCapabilities"] = include_capabilities
+    if planned_maintenance is not None:
+        params["plannedMaintenance"] = planned_maintenance
+    if custom_attribute is not None:
+        params["customAttribute"] = custom_attribute
+    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("items", 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'), ('Display Name', 'displayName'), ('Type', 'type'), ('Calling', 'calling.type')], limit=limit)
+
+
+
+@app.command("create")
+def create(
+    display_name: str = typer.Option(None, "--display-name", help="(required) A friendly name for the workspace."),
+    org_id: str = typer.Option(None, "--org-id", help="`OrgId` associated with the workspace. Only admin users of a"),
+    location_id: str = typer.Option(None, "--location-id", help="Location associated with the workspace. Must be provided whe"),
+    workspace_location_id: str = typer.Option(None, "--workspace-location-id", help="Legacy workspace location ID associated with the workspace."),
+    floor_id: str = typer.Option(None, "--floor-id", help="Floor associated with the workspace."),
+    capacity: str = typer.Option(None, "--capacity", help="How many people the workspace is suitable for. If set, must"),
+    type_param: str = typer.Option(None, "--type", help="Choices: notSet, focus, huddle, meetingRoom, open, desk, other"),
+    sip_address: str = typer.Option(None, "--sip-address", help="The `sipAddress` field can only be provided when calling typ"),
+    notes: str = typer.Option(None, "--notes", help="Notes associated to the workspace."),
+    hotdesking_status: str = typer.Option(None, "--hotdesking-status", help="Choices: on, off"),
+    supported_devices: str = typer.Option(None, "--supported-devices", help="Choices: collaborationDevices, phones"),
+    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 a Workspace\n\nExample --json-body:\n  '{"displayName":"...","orgId":"...","locationId":"...","workspaceLocationId":"...","floorId":"...","capacity":0,"type":"notSet","sipAddress":"..."}'."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/workspaces"
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if display_name is not None:
+            body["displayName"] = display_name
+        if org_id is not None:
+            body["orgId"] = org_id
+        if location_id is not None:
+            body["locationId"] = location_id
+        if workspace_location_id is not None:
+            body["workspaceLocationId"] = workspace_location_id
+        if floor_id is not None:
+            body["floorId"] = floor_id
+        if capacity is not None:
+            body["capacity"] = capacity
+        if type_param is not None:
+            body["type"] = type_param
+        if sip_address is not None:
+            body["sipAddress"] = sip_address
+        if notes is not None:
+            body["notes"] = notes
+        if hotdesking_status is not None:
+            body["hotdeskingStatus"] = hotdesking_status
+        if supported_devices is not None:
+            body["supportedDevices"] = supported_devices
+        _missing = [f for f in ['displayName'] 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(
+    workspace_id: str = typer.Argument(help="workspaceId"),
+    include_devices: str = typer.Option(None, "--include-devices", help="Flag identifying whether to include the devices associated w"),
+    include_capabilities: str = typer.Option(None, "--include-capabilities", help="Flag identifying whether to include the workspace capabiliti"),
+    output: str = typer.Option("json", "--output", "-o", help="Output format: table|json"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Get Workspace Details."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/workspaces/{workspace_id}"
+    params = {}
+    if include_devices is not None:
+        params["includeDevices"] = include_devices
+    if include_capabilities is not None:
+        params["includeCapabilities"] = include_capabilities
+    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")
+def update(
+    workspace_id: str = typer.Argument(help="workspaceId"),
+    display_name: str = typer.Option(None, "--display-name", help="A friendly name for the workspace."),
+    location_id: str = typer.Option(None, "--location-id", help="Location associated with the workspace. Must be provided whe"),
+    workspace_location_id: str = typer.Option(None, "--workspace-location-id", help="Legacy workspace location ID associated with the workspace."),
+    floor_id: str = typer.Option(None, "--floor-id", help="Floor associated with the workspace."),
+    capacity: str = typer.Option(None, "--capacity", help="How many people the workspace is suitable for. If set, must"),
+    type_param: str = typer.Option(None, "--type", help="Choices: notSet, focus, huddle, meetingRoom, open, desk, other"),
+    sip_address: str = typer.Option(None, "--sip-address", help="The `sipAddress` field can only be provided when calling typ"),
+    notes: str = typer.Option(None, "--notes", help="Notes associated to the workspace."),
+    hotdesking_status: str = typer.Option(None, "--hotdesking-status", help="Choices: on, off"),
+    json_body: str = typer.Option(None, "--json-body", help="Full JSON body (overrides other options)"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Update a Workspace\n\nExample --json-body:\n  '{"displayName":"...","locationId":"...","workspaceLocationId":"...","floorId":"...","capacity":0,"type":"notSet","calendar":{"type":"...","emailAddress":"...","resourceGroupId":"..."},"sipAddress":"..."}'."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/workspaces/{workspace_id}"
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if display_name is not None:
+            body["displayName"] = display_name
+        if location_id is not None:
+            body["locationId"] = location_id
+        if workspace_location_id is not None:
+            body["workspaceLocationId"] = workspace_location_id
+        if floor_id is not None:
+            body["floorId"] = floor_id
+        if capacity is not None:
+            body["capacity"] = capacity
+        if type_param is not None:
+            body["type"] = type_param
+        if sip_address is not None:
+            body["sipAddress"] = sip_address
+        if notes is not None:
+            body["notes"] = notes
+        if hotdesking_status is not None:
+            body["hotdeskingStatus"] = hotdesking_status
+    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(
+    workspace_id: str = typer.Argument(help="workspaceId"),
+    force: bool = typer.Option(False, "--force", help="Skip confirmation"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Delete a Workspace."""
+    if not force:
+        typer.confirm(f"Delete {workspace_id}?", abort=True)
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/workspaces/{workspace_id}"
+    try:
+        api.session.rest_delete(url)
+    except WebexError as e:
+        handle_rest_error(e)
+    typer.echo(f"Deleted: {workspace_id}")
+
+
+
+@app.command("show-capabilities")
+def show_capabilities(
+    workspace_id: str = typer.Argument(help="workspaceId"),
+    output: str = typer.Option("json", "--output", "-o", help="Output format: table|json"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Get Workspace Capabilities."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/workspaces/{workspace_id}/capabilities"
+    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)
+
+

wxcli/commands/xapi.py

@@ -0,0 +1,114 @@
+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
+
+
+app = typer.Typer(help="Manage Webex Calling xapi.")
+
+
+@app.command("show")
+def show(
+    device_id: str = typer.Option(..., "--device-id", help="The unique identifier for the Webex RoomOS Device."),
+    name: str = typer.Option(..., "--name", help="A list of status expressions used to query the Webex RoomOS"),
+    output: str = typer.Option("json", "--output", "-o", help="Output format: table|json"),
+    debug: bool = typer.Option(False, "--debug"),
+):
+    """Query Status."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/xapi/status"
+    params = {}
+    if device_id is not None:
+        params["deviceId"] = device_id
+    if name is not None:
+        params["name"] = name
+    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("list")
+def cmd_list(
+    device_id: str = typer.Option(..., "--device-id", help="A list of device IDs to query schemas from. A request can co"),
+    status: str = typer.Option(None, "--status", help="A list of status key expressions to query schemas for. Suppo"),
+    command: str = typer.Option(None, "--command", help="A list of command key expressions to query schemas for. Supp"),
+    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"),
+):
+    """Query Schema."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/xapi/schema"
+    params = {}
+    if device_id is not None:
+        params["deviceId"] = device_id
+    if status is not None:
+        params["status"] = status
+    if command is not None:
+        params["command"] = command
+    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("items", 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(
+    command_name: str = typer.Argument(help="commandName"),
+    device_id: str = typer.Option(None, "--device-id", help="(required) The unique identifier for the Webex RoomOS Device."),
+    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"),
+):
+    """Execute Command\n\nExample --json-body:\n  '{"deviceId":"...","arguments":{"Level":0},"body":{"Booking":{"Id":"...","Title":"...","Protocol":"...","Time":"...","Organizer":"...","Number":"..."}}}'."""
+    api = get_api(debug=debug)
+    url = f"https://webexapis.com/v1/xapi/command/{command_name}"
+    if json_body:
+        body = json.loads(json_body)
+    else:
+        body = {}
+        if device_id is not None:
+            body["deviceId"] = device_id
+        _missing = [f for f in ['deviceId'] 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)
+
+

wxcli/config.py

@@ -0,0 +1,139 @@
+import base64
+import json
+from pathlib import Path
+
+DEFAULT_CONFIG_PATH = Path.home() / ".wxcli" / "config.json"
+
+def load_config(path: Path = DEFAULT_CONFIG_PATH) -> dict:
+    if not path.exists():
+        return {"profiles": {}}
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+def save_config(data: dict, path: Path = DEFAULT_CONFIG_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+def get_token(path: Path = DEFAULT_CONFIG_PATH) -> str | None:
+    config = load_config(path)
+    profile = config.get("profiles", {}).get("default", {})
+    return profile.get("token")
+
+def get_expires_at(path: Path = DEFAULT_CONFIG_PATH) -> str | None:
+    config = load_config(path)
+    profile = config.get("profiles", {}).get("default", {})
+    return profile.get("expires_at")
+
+def get_org_id(path: Path = DEFAULT_CONFIG_PATH) -> str | None:
+    config = load_config(path)
+    profile = config.get("profiles", {}).get("default", {})
+    return profile.get("org_id")
+
+def get_org_name(path: Path = DEFAULT_CONFIG_PATH) -> str | None:
+    config = load_config(path)
+    profile = config.get("profiles", {}).get("default", {})
+    return profile.get("org_name")
+
+def decode_webex_id(encoded_id: str) -> str:
+    """Decode a base64-encoded Webex Spark ID to its UUID suffix.
+
+    Webex Calling APIs return orgId as a base64 URN like:
+      Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi9iODQxMDE0Ny02MTA0LTQyZTgt...
+    which decodes to: ciscospark://us/ORGANIZATION/b8410147-6104-42e8-9b93-...
+
+    The Contact Center API requires the bare UUID (after the last '/'),
+    not the full base64 string.
+    """
+    try:
+        padding = 4 - len(encoded_id) % 4
+        if padding != 4:
+            encoded_id += "=" * padding
+        decoded = base64.b64decode(encoded_id).decode("utf-8")
+        return decoded.rsplit("/", 1)[-1]
+    except Exception:
+        return encoded_id
+
+
+def resolve_org_id(api_session) -> str:
+    """Return the org ID from config, or fetch it from /v1/people/me."""
+    saved = get_org_id()
+    if saved:
+        return saved
+    return api_session.rest_get("https://webexapis.com/v1/people/me").get("orgId", "")
+
+
+def get_cc_org_id(api_session) -> str:
+    """Return the decoded UUID org ID suitable for CC API path parameters.
+
+    Uses the saved org_id from config if available (already decoded), otherwise
+    fetches from people/me and decodes the base64 Spark ID.
+    """
+    saved = get_org_id()
+    if saved:
+        return decode_webex_id(saved)
+    raw = api_session.rest_get("https://webexapis.com/v1/people/me").get("orgId", "")
+    return decode_webex_id(raw)
+
+
+CC_REGIONS = {
+    "us1": "https://api.wxcc-us1.cisco.com",
+    "eu1": "https://api.wxcc-eu1.cisco.com",
+    "eu2": "https://api.wxcc-eu2.cisco.com",
+    "anz1": "https://api.wxcc-anz1.cisco.com",
+    "ca1": "https://api.wxcc-ca1.cisco.com",
+    "jp1": "https://api.wxcc-jp1.cisco.com",
+    "sg1": "https://api.wxcc-sg1.cisco.com",
+}
+
+def get_cc_base_url(path: Path = DEFAULT_CONFIG_PATH) -> str:
+    config = load_config(path)
+    profile = config.get("profiles", {}).get("default", {})
+    region = profile.get("cc_region", "us1")
+    return CC_REGIONS.get(region, CC_REGIONS["us1"])
+
+def save_cc_region(region: str, path: Path = DEFAULT_CONFIG_PATH) -> None:
+    config = load_config(path)
+    profile = config.setdefault("profiles", {}).setdefault("default", {})
+    profile["cc_region"] = region
+    save_config(config, path)
+
+FS_DATACENTERS = {
+    "intgus1": "https://flow-store.intgus1.ciscoccservice.com/flow-store",
+    "us1": "https://flow-store.us1.ciscoccservice.com/flow-store",
+}
+
+def get_fs_base_url(path: Path = DEFAULT_CONFIG_PATH) -> str:
+    config = load_config(path)
+    profile = config.get("profiles", {}).get("default", {})
+    dc = profile.get("fs_datacenter", "intgus1")
+    return FS_DATACENTERS.get(dc, FS_DATACENTERS["intgus1"])
+
+def get_fs_project_id(path: Path = DEFAULT_CONFIG_PATH) -> str:
+    config = load_config(path)
+    profile = config.get("profiles", {}).get("default", {})
+    pid = profile.get("fs_project_id")
+    if pid:
+        return pid
+    raise SystemExit(
+        "Flow Store project ID not configured. Run:\n"
+        "  wxcli fs-projects list   # to find your project ID\n"
+        "  Then set it in ~/.wxcli/config.json under profiles.default.fs_project_id"
+    )
+
+def save_fs_datacenter(datacenter: str, path: Path = DEFAULT_CONFIG_PATH) -> None:
+    config = load_config(path)
+    profile = config.setdefault("profiles", {}).setdefault("default", {})
+    profile["fs_datacenter"] = datacenter
+    save_config(config, path)
+
+def save_org(org_id: str | None, org_name: str | None, path: Path = DEFAULT_CONFIG_PATH) -> None:
+    config = load_config(path)
+    profile = config.setdefault("profiles", {}).setdefault("default", {})
+    if org_id:
+        profile["org_id"] = org_id
+        profile["org_name"] = org_name
+    else:
+        profile.pop("org_id", None)
+        profile.pop("org_name", None)
+    save_config(config, path)

wxcli/errors.py

@@ -0,0 +1,77 @@
+"""Centralized error handler for wxcli commands."""
+import json
+import typer
+
+
+class WebexError(Exception):
+    """Webex API error. Message-first: WebexError(response.text) remains valid.
+
+    status_code and body (parsed JSON error, when parseable) are optional
+    enrichments so handlers can key off status instead of substring matching.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None, body: dict | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+_ERROR_TIPS = {
+    4003: "This endpoint requires a user-level OAuth token, not an admin or service app token.",
+    4008: "This endpoint requires the target user to have a Webex Calling license.",
+    9601: "This endpoint requires a user-level OAuth token, not an admin or service app token.",
+    25008: "Use --json-body for full control over the request body.",
+    25409: "This workspace setting requires a Professional license. Use -o json with the /features/ path commands for Basic workspaces.",
+    28018: "CX Essentials is not enabled for this queue. Use --has-cx-essentials true when creating/querying CX queues.",
+}
+
+_MESSAGE_TIPS = {
+    "Target user not authorized": "This endpoint requires a user-level OAuth token, not an admin or service app token.",
+}
+
+
+def _extract_error_code(err: str) -> int | None:
+    """Extract error code from a Webex API JSON error response."""
+    try:
+        body = json.loads(err)
+        for entry in body.get("errors", []):
+            code = entry.get("errorCode") or entry.get("code")
+            if code is not None:
+                return int(code)
+    except (json.JSONDecodeError, ValueError, AttributeError):
+        pass
+    return None
+
+
+def _truncate_html(err: str) -> str:
+    """Extract a readable message from HTML error responses."""
+    if not err.lstrip().startswith("<"):
+        return err
+    import re
+    title = re.search(r"<title>(.*?)</title>", err, re.IGNORECASE)
+    h1 = re.search(r"<h1>(.*?)</h1>", err, re.IGNORECASE)
+    msg = (h1 and h1.group(1)) or (title and title.group(1)) or "Non-JSON error response"
+    return msg.strip()
+
+
+def handle_rest_error(e: WebexError) -> None:
+    """Centralized error handler with actionable tips."""
+    err = str(e)
+    code = _extract_error_code(err)
+
+    if code == 4003 and "Target user not authorized" not in err:
+        code = None
+
+    if code and code in _ERROR_TIPS:
+        typer.echo(f"Error: {_truncate_html(err)}", err=True)
+        typer.echo(f"Tip: {_ERROR_TIPS[code]}", err=True)
+    elif any(msg in err for msg in _MESSAGE_TIPS):
+        tip = next(v for k, v in _MESSAGE_TIPS.items() if k in err)
+        typer.echo(f"Error: {_truncate_html(err)}", err=True)
+        typer.echo(f"Tip: {tip}", err=True)
+    elif "wxcc" in err and "403" in err:
+        typer.echo(f"Error: {_truncate_html(err)}", err=True)
+        typer.echo("Tip: Contact Center APIs require CC-scoped OAuth (cjp:config_read / cjp:config_write). Standard admin tokens won't work.", err=True)
+    else:
+        typer.echo(f"Error: {_truncate_html(err)}", err=True)
+    raise typer.Exit(1)