deepflow-opendesk-cli 0.1.0__py3-none-any.whl

deepflow_opendesk_cli/schema.py

@@ -0,0 +1,384 @@
+"""OpenAPI schema parsing and admin-configuration endpoint filtering."""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+CONFIG_TAGS = {
+    "System",
+    "SystemSettings",
+    "OpenAgentSettings",
+    "Roles",
+    "Employees",
+    "EmployeeGroups",
+    "EmployeeSelect",
+    "ServiceHours",
+    "Channels",
+    "ConversationSettings",
+    "FieldDefinitions",
+    "FormLayouts",
+    "InteractionRules",
+    "UserViews",
+    "TicketViews",
+    "OrganizationViews",
+    "VoiceFlows",
+    "TicketWorkflows",
+    "InboundRoutingRules",
+    "SessionRoutingRules",
+    "Tenants",
+    "SIP Trunks",
+    "Phone Numbers",
+}
+
+INCLUDE_PATHS = (
+    "/api/v1/auth/login",
+    "/api/v1/auth/me",
+    "/api/v1/session-summary/config*",
+    "/api/v1/call-summary/config*",
+    "/api/v1/queue/policies*",
+    "/api/v1/upload/avatar",
+    "/api/v1/upload/channel-logo",
+    "/api/v1/upload/channel-favicon",
+    "/api/v1/call-center/phone-numbers*",
+)
+
+EXCLUDE_PATHS = (
+    "/api/v1/auth/reset-password",
+    "/api/v1/auth/send-verify-code",
+    "/api/v1/public/*",
+    "/api/v1/conversations*",
+    "/api/v1/session-records*",
+    "/api/v1/tickets*",
+    "/api/v1/users*",
+    "/api/v1/organizations*",
+    "/api/v1/reports*",
+    "/api/v1/workspace/*",
+    "/api/v1/agent/*",
+    "/api/v1/call-center/agents/*",
+    "/api/v1/queue/tasks*",
+    "/api/v1/queue/dispatch",
+    "/api/v1/queue/state",
+    "/api/v1/upload/custom-field-file",
+)
+
+CURATED_ALIASES: dict[tuple[str, str], str] = {
+    ("POST", "/api/v1/auth/login"): "auth.login",
+    ("GET", "/api/v1/auth/me"): "auth.me",
+    ("GET", "/api/v1/system/info"): "system.info",
+    ("GET", "/api/v1/system-settings"): "system.settings",
+    ("PUT", "/api/v1/system-settings"): "system.settings_update",
+    ("PUT", "/api/v1/system-settings/organization"): "system.organization_update",
+    ("GET", "/api/v1/roles"): "roles.list",
+    ("POST", "/api/v1/roles"): "roles.create",
+    ("GET", "/api/v1/roles/permission-tree"): "roles.permission_tree",
+    ("GET", "/api/v1/employees"): "employees.list",
+    ("POST", "/api/v1/employees"): "employees.create",
+    ("GET", "/api/v1/employee-groups"): "employee_groups.list",
+    ("GET", "/api/v1/field-definitions"): "fields.list",
+    ("POST", "/api/v1/field-definitions"): "fields.create",
+    ("GET", "/api/v1/field-definitions/unified"): "fields.unified",
+    ("GET", "/api/v1/form-layouts/by-scene/{scene}"): "forms.get_by_scene",
+    ("GET", "/api/v1/channels"): "channels.list",
+    ("GET", "/api/v1/channels/{channel_id}"): "channels.get",
+    ("GET", "/api/v1/session-routing-rules"): "routing.session_list",
+    ("GET", "/api/v1/inbound-routing-rules"): "routing.inbound_list",
+    ("GET", "/api/v1/queue/policies"): "queue.policies",
+    ("GET", "/api/v1/voice-flows"): "voice_flows.list",
+    ("GET", "/api/v1/ticket-workflows"): "ticket_workflows.list",
+}
+
+HTTP_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE"}
+NO_AUTH_PATHS = {"/api/v1/auth/login", "/api/v1/system/info", "/api/v1/health"}
+
+
+@dataclass(frozen=True)
+class ParamDoc:
+    """Path or query parameter documentation."""
+
+    name: str
+    type: str
+    required: bool
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class EndpointDoc:
+    """Machine-readable endpoint documentation for humans and AI agents."""
+
+    key: str
+    operation_id: str
+    method: str
+    path: str
+    tag: str
+    summary: str
+    path_params: list[ParamDoc] = field(default_factory=list)
+    query_params: list[ParamDoc] = field(default_factory=list)
+    body_schema: str = ""
+    response_schema: str = ""
+    requires_auth: bool = True
+    examples: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable representation."""
+        return asdict(self)
+
+
+def read_schema_file(path: str | Path) -> dict[str, Any]:
+    """Read an OpenAPI schema object from disk."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("OpenAPI schema must be a JSON object")
+    return data
+
+
+def fetch_openapi_schema(host: str, token: str | None = None, timeout: int = 30) -> dict[str, Any]:
+    """Fetch ``/openapi.json`` from an OpenDesk host."""
+    url = f"{host.rstrip('/')}/openapi.json"
+    headers = {"Accept": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    request = Request(url, headers=headers, method="GET")
+    try:
+        with urlopen(request, timeout=timeout) as response:  # noqa: S310 - CLI calls user-provided hosts.
+            payload = response.read().decode("utf-8")
+    except HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HTTP {exc.code} while fetching OpenAPI schema: {body}") from exc
+    except URLError as exc:
+        raise RuntimeError(f"Failed to fetch OpenAPI schema from {url}: {exc.reason}") from exc
+    data = json.loads(payload)
+    if not isinstance(data, dict):
+        raise RuntimeError("OpenAPI schema response must be a JSON object")
+    return data
+
+
+def build_catalog(schema: dict[str, Any]) -> list[EndpointDoc]:
+    """Build the configuration endpoint catalog from an OpenAPI schema."""
+    endpoints: list[EndpointDoc] = []
+    paths = schema.get("paths", {})
+    if not isinstance(paths, dict):
+        return endpoints
+
+    for path, operations in paths.items():
+        if not isinstance(path, str) or not isinstance(operations, dict):
+            continue
+        for raw_method, operation in operations.items():
+            method = raw_method.upper()
+            if method not in HTTP_METHODS or not isinstance(operation, dict):
+                continue
+            tag = _first_tag(operation)
+            if not is_config_endpoint(method, path, tag):
+                continue
+            endpoints.append(_endpoint_from_operation(method, path, tag, operation))
+
+    return _dedupe_keys(endpoints)
+
+
+def catalog_by_key(catalog: list[EndpointDoc]) -> dict[str, EndpointDoc]:
+    """Index endpoints by key and OpenAPI operation id."""
+    indexed: dict[str, EndpointDoc] = {}
+    for endpoint in catalog:
+        indexed[endpoint.key] = endpoint
+        if endpoint.operation_id:
+            indexed[endpoint.operation_id] = endpoint
+    return indexed
+
+
+def get_endpoint(catalog: list[EndpointDoc], key: str) -> EndpointDoc:
+    """Return an endpoint by key or operation id."""
+    indexed = catalog_by_key(catalog)
+    try:
+        return indexed[key]
+    except KeyError as exc:
+        choices = ", ".join(sorted(item.key for item in catalog))
+        raise KeyError(f"Unknown endpoint '{key}'. Available endpoints: {choices}") from exc
+
+
+def is_config_endpoint(method: str, path: str, tag: str) -> bool:
+    """Return whether an endpoint belongs to the admin configuration surface."""
+    _ = method
+    if _matches_any(path, EXCLUDE_PATHS):
+        return False
+    if _matches_any(path, INCLUDE_PATHS):
+        return True
+    return tag in CONFIG_TAGS
+
+
+def find_matching_endpoint(catalog: list[EndpointDoc], method: str, path: str) -> EndpointDoc | None:
+    """Find a catalog endpoint for a concrete path."""
+    method = method.upper()
+    for endpoint in catalog:
+        if endpoint.method != method:
+            continue
+        if endpoint.path == path or _path_template_matches(endpoint.path, path):
+            return endpoint
+    return None
+
+
+def normalize_identifier(value: str) -> str:
+    """Normalize a label into a stable snake_case identifier."""
+    value = re.sub(r"[^0-9A-Za-z]+", "_", value).strip("_").lower()
+    return re.sub(r"_+", "_", value) or "endpoint"
+
+
+def schema_ref_name(schema_fragment: Any) -> str:
+    """Summarize a schema fragment as a compact string."""
+    if not isinstance(schema_fragment, dict):
+        return ""
+    ref = schema_fragment.get("$ref")
+    if isinstance(ref, str):
+        return ref.rsplit("/", 1)[-1]
+    if "type" in schema_fragment:
+        return str(schema_fragment["type"])
+    if "allOf" in schema_fragment:
+        return "allOf"
+    if "anyOf" in schema_fragment:
+        return "anyOf"
+    if "oneOf" in schema_fragment:
+        return "oneOf"
+    return ""
+
+
+def _endpoint_from_operation(method: str, path: str, tag: str, operation: dict[str, Any]) -> EndpointDoc:
+    operation_id = str(operation.get("operationId") or "")
+    summary = str(operation.get("summary") or operation_id or f"{method} {path}")
+    key = CURATED_ALIASES.get((method, path)) or f"{normalize_identifier(tag)}.{_operation_action(operation_id, summary)}"
+    path_params, query_params = _params(operation)
+    body_schema = _request_body_schema(operation)
+    response_schema = _response_schema(operation)
+    return EndpointDoc(
+        key=key,
+        operation_id=operation_id,
+        method=method,
+        path=path,
+        tag=tag,
+        summary=summary,
+        path_params=path_params,
+        query_params=query_params,
+        body_schema=body_schema,
+        response_schema=response_schema,
+        requires_auth=path not in NO_AUTH_PATHS,
+        examples=[_example_for(key, method, path)],
+    )
+
+
+def _dedupe_keys(endpoints: list[EndpointDoc]) -> list[EndpointDoc]:
+    seen: dict[str, int] = {}
+    result: list[EndpointDoc] = []
+    for endpoint in endpoints:
+        count = seen.get(endpoint.key, 0)
+        seen[endpoint.key] = count + 1
+        if count == 0:
+            result.append(endpoint)
+            continue
+        suffix = hashlib.sha1(f"{endpoint.method} {endpoint.path}".encode("utf-8")).hexdigest()[:8]
+        result.append(
+            EndpointDoc(
+                key=f"{endpoint.key}_{suffix}",
+                operation_id=endpoint.operation_id,
+                method=endpoint.method,
+                path=endpoint.path,
+                tag=endpoint.tag,
+                summary=endpoint.summary,
+                path_params=endpoint.path_params,
+                query_params=endpoint.query_params,
+                body_schema=endpoint.body_schema,
+                response_schema=endpoint.response_schema,
+                requires_auth=endpoint.requires_auth,
+                examples=endpoint.examples,
+            )
+        )
+    return result
+
+
+def _first_tag(operation: dict[str, Any]) -> str:
+    tags = operation.get("tags")
+    if isinstance(tags, list) and tags:
+        return str(tags[0])
+    return ""
+
+
+def _params(operation: dict[str, Any]) -> tuple[list[ParamDoc], list[ParamDoc]]:
+    path_params: list[ParamDoc] = []
+    query_params: list[ParamDoc] = []
+    raw_params = operation.get("parameters", [])
+    if not isinstance(raw_params, list):
+        return path_params, query_params
+    for raw in raw_params:
+        if not isinstance(raw, dict):
+            continue
+        schema = raw.get("schema") if isinstance(raw.get("schema"), dict) else {}
+        item = ParamDoc(
+            name=str(raw.get("name") or ""),
+            type=str(schema.get("type") or schema_ref_name(schema) or "string"),
+            required=bool(raw.get("required")),
+            description=str(raw.get("description") or ""),
+        )
+        location = raw.get("in")
+        if location == "path":
+            path_params.append(item)
+        elif location == "query":
+            query_params.append(item)
+    return path_params, query_params
+
+
+def _request_body_schema(operation: dict[str, Any]) -> str:
+    body = operation.get("requestBody")
+    if not isinstance(body, dict):
+        return ""
+    content = body.get("content")
+    if not isinstance(content, dict):
+        return ""
+    for content_type in ("application/json", "multipart/form-data"):
+        media = content.get(content_type)
+        if isinstance(media, dict):
+            return schema_ref_name(media.get("schema"))
+    return ""
+
+
+def _response_schema(operation: dict[str, Any]) -> str:
+    responses = operation.get("responses")
+    if not isinstance(responses, dict):
+        return ""
+    response = responses.get("200") or responses.get("201") or responses.get("default")
+    if not isinstance(response, dict):
+        return ""
+    content = response.get("content")
+    if not isinstance(content, dict):
+        return ""
+    media = content.get("application/json")
+    if isinstance(media, dict):
+        return schema_ref_name(media.get("schema"))
+    return ""
+
+
+def _operation_action(operation_id: str, summary: str) -> str:
+    base = operation_id.split("_api_v1_", 1)[0] if operation_id else summary
+    return normalize_identifier(base)
+
+
+def _example_for(key: str, method: str, path: str) -> str:
+    if "{" in path:
+        return f"deepflow_opendesk_cli call {key} --path name=value"
+    if method in {"POST", "PUT", "PATCH"}:
+        return f"deepflow_opendesk_cli call {key} --json '{{}}'"
+    return f"deepflow_opendesk_cli call {key}"
+
+
+def _matches_any(path: str, patterns: tuple[str, ...]) -> bool:
+    return any(fnmatch.fnmatchcase(path, pattern) for pattern in patterns)
+
+
+def _path_template_matches(template: str, path: str) -> bool:
+    pattern = re.escape(template)
+    pattern = re.sub(r"\\\{[^/]+\\\}", r"[^/]+", pattern)
+    return re.fullmatch(pattern, path) is not None

deepflow_opendesk_cli/workflows.py

@@ -0,0 +1,37 @@
+"""Simple workflow plan helpers for OpenDesk admin configuration."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .client import CliError
+
+WORKFLOWS: dict[str, str] = {
+    "setup-tenant": "Initialize tenant-level system settings and optional tenant metadata.",
+    "setup-web-channel": "Configure Web SDK channel, welcome rules, and routing prerequisites.",
+    "bootstrap-admin-config": "Apply fields, views, forms, service hours, and routing configuration.",
+}
+
+
+def list_workflows() -> list[dict[str, str]]:
+    """Return available workflow names and descriptions."""
+    return [{"name": name, "description": description} for name, description in sorted(WORKFLOWS.items())]
+
+
+def load_workflow_operations(name: str, json_file: str | None) -> list[dict[str, Any]]:
+    """Load workflow operations from a JSON file."""
+    if name not in WORKFLOWS:
+        choices = ", ".join(sorted(WORKFLOWS))
+        raise CliError(f"Unknown workflow '{name}'. Available workflows: {choices}")
+    if not json_file:
+        raise CliError("workflow run requires --json-file with an operations plan")
+    payload = json.loads(Path(json_file).read_text(encoding="utf-8"))
+    if isinstance(payload, dict):
+        operations = payload.get("operations")
+    else:
+        operations = payload
+    if not isinstance(operations, list) or not all(isinstance(item, dict) for item in operations):
+        raise CliError("Workflow plan must be a JSON object with operations[] or a JSON array")
+    return list(operations)

deepflow_opendesk_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: deepflow-opendesk-cli
+Version: 0.1.0
+Summary: Command-line client for OpenDesk admin configuration APIs.
+Author: DeepFlow AI
+Project-URL: Repository, https://github.com/DeepFlowAI/opendesk-dev
+Keywords: deepflow,opendesk,cli,openapi,admin,configuration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: requires-python
+
+# deepflow-opendesk-cli
+
+Python command-line client for OpenDesk admin configuration APIs.
+
+The CLI is designed for implementation engineers, operators, and AI agents that need to configure OpenDesk through the same APIs used by the admin console.
+
+## Scope
+
+This package intentionally exposes only admin configuration APIs. Runtime workspace data, public visitor APIs, reports, and call-center agent actions are excluded by a schema whitelist.
+
+Included examples:
+
+- System settings
+- Roles, employees, employee groups
+- Service hours
+- Channels
+- Field definitions, form layouts, interaction rules
+- User, ticket, and organization view configuration
+- Satisfaction and welcome-message settings
+- Voice flows, ticket workflows, inbound/session routing rules
+- Queue policies
+- Optional tenant, SIP trunk, and phone-number configuration endpoints when extensions are loaded
+
+## Install For Development
+
+```bash
+cd packages/deepflow-opendesk-cli
+pip install -e ".[dev]"
+```
+
+## Configure Host And Token
+
+```bash
+export OPENDESK_HOST="http://localhost:5001"
+export OPENDESK_TOKEN="..."
+```
+
+Or log in and save a local profile:
+
+```bash
+deepflow_opendesk_cli auth login \
+  --tenant 12058577c8114513 \
+  --username test \
+  --save-token
+```
+
+Profile files are stored under `~/.opendesk/cli/{profile}/` with owner-only permissions where supported.
+
+## Common Commands
+
+```bash
+deepflow_opendesk_cli schema fetch
+deepflow_opendesk_cli docs list --tag FieldDefinitions
+deepflow_opendesk_cli docs show fields.create --json
+
+deepflow_opendesk_cli request GET /api/v1/system/info
+deepflow_opendesk_cli call fields.list --query domain=ticket
+deepflow_opendesk_cli call fields.create --json-file field.json
+
+deepflow_opendesk_cli system settings
+deepflow_opendesk_cli roles permission-tree
+deepflow_opendesk_cli employees list
+deepflow_opendesk_cli channels list
+deepflow_opendesk_cli routing session list
+deepflow_opendesk_cli queue policies
+```
+
+Equivalent module invocation:
+
+```bash
+python -m deepflow_opendesk_cli docs list
+```
+
+## AI Agent Flow
+
+Recommended execution loop:
+
+```text
+1. schema fetch or docs list
+2. docs show <endpoint-key>
+3. request/call --dry-run
+4. present plan to a human
+5. batch run / workflow run --yes
+6. verify with config list/get commands
+```
+
+## Batch
+
+`batch run` accepts JSONL. Each line is a config operation:
+
+```jsonl
+{"key":"auth.me"}
+{"key":"fields.create","body":{"domain":"ticket","name":"Customer Tier","field_type":"select"}}
+{"method":"PUT","path":"/api/v1/system-settings","body":{"default_language":"zh","default_timezone":"Asia/Shanghai"}}
+```
+
+Run:
+
+```bash
+deepflow_opendesk_cli batch run ops.jsonl --dry-run
+deepflow_opendesk_cli batch run ops.jsonl --continue-on-error --output results.jsonl
+```
+
+## Development
+
+```bash
+cd packages/deepflow-opendesk-cli
+PYTHONPATH=src python -m pytest tests -q
+python -m build
+```
+
+## Distribution
+
+Releases are automated. Pushing a `v*` git tag (e.g. `v0.1.1`) triggers
+`.github/workflows/release.yml`, which runs the tests, builds the sdist + wheel,
+publishes `deepflow-opendesk-cli` to PyPI, and cuts a GitHub Release.
+
+```bash
+pip install deepflow-opendesk-cli
+```
+
+To cut a patch release, run the helper script (bumps the version across
+`pyproject.toml`, `setup.py`, and `__init__.py`, then tags and pushes):
+
+```bash
+bash .claude/skills/release-publish/scripts/release-tag.sh --dry-run
+bash .claude/skills/release-publish/scripts/release-tag.sh
+```
+
+To build locally without publishing: `python -m build`.

deepflow_opendesk_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+deepflow_opendesk_cli/__init__.py,sha256=QQUA2RQSL5navxL2IBHLJuCcYDNGu6DlVSvyG0Bj-cA,67
+deepflow_opendesk_cli/__main__.py,sha256=8T1O4_06PjtF3IgGo08A184Ih4Nv0Sokp4SNQAAebBA,146
+deepflow_opendesk_cli/batch.py,sha256=6b2NggZO6PZkSU0zNRqiYfEPrtRKx0QI_ALnLJx2zr4,1837
+deepflow_opendesk_cli/cli.py,sha256=m_5ONJKhHBSOgUeBVJnDLL4kaP_09vlPxUeO9kpz1Ig,27751
+deepflow_opendesk_cli/client.py,sha256=xfaRE8E0lhSFf8oST4xHRbwd6ysXnYntEpwiTpFUlcQ,10793
+deepflow_opendesk_cli/profiles.py,sha256=1qxnwZPtOMKZuHYR2KyQrNimZiKCoZJmmoHkZvzd6n8,2683
+deepflow_opendesk_cli/schema.py,sha256=LCVFLelF1HYRIwcBSjFlBWnGskRZBLb-cNZWlq744L8,13336
+deepflow_opendesk_cli/workflows.py,sha256=1SOJM_m4_S0MgyiJwGZ3OsabG6yB03E56qF7mgijrVQ,1561
+deepflow_opendesk_cli-0.1.0.dist-info/METADATA,sha256=7vlFUyMEu_SippEoKeVBqwYcXle_Yc5wBxnLfFSgJVo,4332
+deepflow_opendesk_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+deepflow_opendesk_cli-0.1.0.dist-info/entry_points.txt,sha256=5mTQ__pNqudneSyStqhp1LTYH0_zWuZEwGmV4iO-Qxk,73
+deepflow_opendesk_cli-0.1.0.dist-info/top_level.txt,sha256=JrIzmrPOJORIaCHKzwnFXoV1N1TmHFY3jOv-7LAzx7E,22
+deepflow_opendesk_cli-0.1.0.dist-info/RECORD,,

deepflow_opendesk_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deepflow_opendesk_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+deepflow_opendesk_cli = deepflow_opendesk_cli.cli:main

deepflow_opendesk_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepflow_opendesk_cli