deepflow-opendesk-cli 0.1.2__tar.gz → 0.1.4__tar.gz

deepflow_opendesk_cli-0.1.4/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: deepflow-opendesk-cli
+Version: 0.1.4
+Summary: Command-line client for OpenDesk admin configuration and outbound task 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 and outbound task 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 admin configuration APIs and API-key outbound task management 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
+- Outbound task templates, manual outbound tasks, and automatic outbound tasks
+- Learning courses and exams (admin configuration)
+- 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 docs schema FieldDefinitionCreate
+
+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 call service_hours.list
+deepflow_opendesk_cli call satisfaction.get
+deepflow_opendesk_cli call welcome_rules.create --json-file welcome-rule.json
+deepflow_opendesk_cli routing session list
+deepflow_opendesk_cli queue policies
+deepflow_opendesk_cli outbound-templates list
+deepflow_opendesk_cli outbound-templates get-script 12
+deepflow_opendesk_cli outbound-templates set-script 12 --json-file script.json
+deepflow_opendesk_cli outbound-tasks list
+deepflow_opendesk_cli auto-outbound-tasks list
+deepflow_opendesk_cli call courses.list
+deepflow_opendesk_cli call exams.list
+```
+
+## Web Channel Bot Process Visibility
+
+After deploying a server that supports `config.open_agent_hide_process`, the
+existing generic commands can read and update this setting. No dedicated CLI
+flag is required. Refresh the cached schema to discover the new boolean field:
+
+```bash
+deepflow_opendesk_cli schema fetch
+deepflow_opendesk_cli docs schema ChannelConfig
+deepflow_opendesk_cli docs show channels.update
+```
+
+Channel updates replace the full configuration; sending only the new boolean
+can reset other settings. Read the channel first, preserve its editable fields
+and complete `config`, then change the boolean. For example, using `jq`:
+
+```bash
+deepflow_opendesk_cli call channels.get --path channel_id=12 > channel-current.json
+jq -e '.ok == true and (.data.config | type == "object")' channel-current.json
+jq '.data | {name, channel_type, access_mode, logo_url, favicon_url, config}
+    | .config.open_agent_hide_process = true' \
+  channel-current.json > channel-update.json
+
+deepflow_opendesk_cli call channels.update --path channel_id=12 \
+  --json-file channel-update.json --dry-run
+deepflow_opendesk_cli call channels.update --path channel_id=12 \
+  --json-file channel-update.json
+deepflow_opendesk_cli call channels.get --path channel_id=12
+```
+
+Continue to the update only if the read and validation succeeded. Use JSON
+`false` to restore process visibility, not the string `"false"`. Both new and
+legacy channels default to `false` when the field is missing. The setting affects
+visitor display only; disabling the bot does not clear it. Existing channel
+management permissions still apply. Concurrent edits between the read and update
+can be overwritten, so read the latest configuration before applying the change.
+
+`request PUT /api/v1/channels/12 --json-file channel-update.json` is equivalent;
+batch and workflow bodies also pass the same field through unchanged. `--dry-run`
+prints the request without sending it; the server performs field validation.
+
+## Outbound Tasks
+
+The outbound commands use the API-key OpenAPI under
+`/api/v1/open/engagement`. Set the tenant API key in `OPENDESK_TOKEN` or pass
+the global `--token` option before the command.
+
+Manual task examples:
+
+```bash
+deepflow_opendesk_cli outbound-tasks create --json-file manual-task.json
+deepflow_opendesk_cli outbound-tasks publish 18
+deepflow_opendesk_cli outbound-tasks targets 18 --status pending
+deepflow_opendesk_cli outbound-tasks add-target 18 \
+  --json '{"phone_number":"13800138000","field_values":{"name":"Alice"}}'
+deepflow_opendesk_cli outbound-tasks add-targets 18 --json-file targets.json
+deepflow_opendesk_cli outbound-tasks import-targets 18 targets.xlsx
+deepflow_opendesk_cli outbound-tasks records 18
+```
+
+Automatic task examples:
+
+```bash
+deepflow_opendesk_cli auto-outbound-tasks create --json-file auto-task.json
+deepflow_opendesk_cli auto-outbound-tasks start 27
+deepflow_opendesk_cli auto-outbound-tasks monitor 27
+deepflow_opendesk_cli auto-outbound-tasks add-targets 27 --json-file targets.json
+deepflow_opendesk_cli auto-outbound-tasks import-targets 27 targets.csv
+deepflow_opendesk_cli auto-outbound-tasks mark-target-invalid 81
+deepflow_opendesk_cli auto-outbound-tasks delete 27 --yes
+```
+
+`add-targets` accepts a JSON object containing 1–5000 targets:
+
+```json
+{
+  "targets": [
+    {
+      "phone_number": "13800138000",
+      "user_id": 123,
+      "field_values": {"name": "Alice", "customer_level": "VIP"}
+    }
+  ]
+}
+```
+
+`import-targets` keeps the existing Excel/CSV file import behavior. Use
+`docs show outbound_tasks.create` or `docs show auto_outbound_tasks.create`
+after `schema fetch` to inspect the current request fields.
+
+Equivalent module invocation:
+
+```bash
+python -m deepflow_opendesk_cli docs list
+```
+
+## Construct Request Bodies
+
+`docs show <endpoint-key>` expands the request body schema into a field tree
+(name, type, required, enum, description) and prints a generated example
+payload, so an agent can construct a valid body without reading the OpenAPI
+components by hand. `docs schema <SchemaName>` does the same for any component
+schema in the fetched OpenAPI document.
+
+```bash
+deepflow_opendesk_cli docs show fields.create
+deepflow_opendesk_cli docs schema WelcomeMessageRuleCreate --json
+```
+
+Use the printed example as a starting point, edit values, then pass it with
+`--json` / `--json-file`. Add `--dry-run` to validate the plan without sending
+requests.
+
+## AI Agent Flow
+
+Recommended execution loop:
+
+```text
+1. schema fetch or docs list
+2. docs show <endpoint-key> (and docs schema <SchemaName> for body details)
+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
+```
+
+## Workflows
+
+`workflow list` shows named configuration workflows. Running a workflow without
+`--json-file` executes its built-in **read-only** plan, which snapshots the
+relevant current configuration (safe to run anytime). Pass `--json-file` with a
+batch-style operations array to run a custom write plan instead.
+
+```bash
+deepflow_opendesk_cli workflow list
+deepflow_opendesk_cli workflow run setup-tenant --dry-run
+deepflow_opendesk_cli workflow run setup-web-channel --json-file channel-plan.json --yes
+```
+
+## 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.4/README.md

@@ -0,0 +1,263 @@
+# deepflow-opendesk-cli
+
+Python command-line client for OpenDesk admin configuration and outbound task 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 admin configuration APIs and API-key outbound task management 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
+- Outbound task templates, manual outbound tasks, and automatic outbound tasks
+- Learning courses and exams (admin configuration)
+- 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 docs schema FieldDefinitionCreate
+
+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 call service_hours.list
+deepflow_opendesk_cli call satisfaction.get
+deepflow_opendesk_cli call welcome_rules.create --json-file welcome-rule.json
+deepflow_opendesk_cli routing session list
+deepflow_opendesk_cli queue policies
+deepflow_opendesk_cli outbound-templates list
+deepflow_opendesk_cli outbound-templates get-script 12
+deepflow_opendesk_cli outbound-templates set-script 12 --json-file script.json
+deepflow_opendesk_cli outbound-tasks list
+deepflow_opendesk_cli auto-outbound-tasks list
+deepflow_opendesk_cli call courses.list
+deepflow_opendesk_cli call exams.list
+```
+
+## Web Channel Bot Process Visibility
+
+After deploying a server that supports `config.open_agent_hide_process`, the
+existing generic commands can read and update this setting. No dedicated CLI
+flag is required. Refresh the cached schema to discover the new boolean field:
+
+```bash
+deepflow_opendesk_cli schema fetch
+deepflow_opendesk_cli docs schema ChannelConfig
+deepflow_opendesk_cli docs show channels.update
+```
+
+Channel updates replace the full configuration; sending only the new boolean
+can reset other settings. Read the channel first, preserve its editable fields
+and complete `config`, then change the boolean. For example, using `jq`:
+
+```bash
+deepflow_opendesk_cli call channels.get --path channel_id=12 > channel-current.json
+jq -e '.ok == true and (.data.config | type == "object")' channel-current.json
+jq '.data | {name, channel_type, access_mode, logo_url, favicon_url, config}
+    | .config.open_agent_hide_process = true' \
+  channel-current.json > channel-update.json
+
+deepflow_opendesk_cli call channels.update --path channel_id=12 \
+  --json-file channel-update.json --dry-run
+deepflow_opendesk_cli call channels.update --path channel_id=12 \
+  --json-file channel-update.json
+deepflow_opendesk_cli call channels.get --path channel_id=12
+```
+
+Continue to the update only if the read and validation succeeded. Use JSON
+`false` to restore process visibility, not the string `"false"`. Both new and
+legacy channels default to `false` when the field is missing. The setting affects
+visitor display only; disabling the bot does not clear it. Existing channel
+management permissions still apply. Concurrent edits between the read and update
+can be overwritten, so read the latest configuration before applying the change.
+
+`request PUT /api/v1/channels/12 --json-file channel-update.json` is equivalent;
+batch and workflow bodies also pass the same field through unchanged. `--dry-run`
+prints the request without sending it; the server performs field validation.
+
+## Outbound Tasks
+
+The outbound commands use the API-key OpenAPI under
+`/api/v1/open/engagement`. Set the tenant API key in `OPENDESK_TOKEN` or pass
+the global `--token` option before the command.
+
+Manual task examples:
+
+```bash
+deepflow_opendesk_cli outbound-tasks create --json-file manual-task.json
+deepflow_opendesk_cli outbound-tasks publish 18
+deepflow_opendesk_cli outbound-tasks targets 18 --status pending
+deepflow_opendesk_cli outbound-tasks add-target 18 \
+  --json '{"phone_number":"13800138000","field_values":{"name":"Alice"}}'
+deepflow_opendesk_cli outbound-tasks add-targets 18 --json-file targets.json
+deepflow_opendesk_cli outbound-tasks import-targets 18 targets.xlsx
+deepflow_opendesk_cli outbound-tasks records 18
+```
+
+Automatic task examples:
+
+```bash
+deepflow_opendesk_cli auto-outbound-tasks create --json-file auto-task.json
+deepflow_opendesk_cli auto-outbound-tasks start 27
+deepflow_opendesk_cli auto-outbound-tasks monitor 27
+deepflow_opendesk_cli auto-outbound-tasks add-targets 27 --json-file targets.json
+deepflow_opendesk_cli auto-outbound-tasks import-targets 27 targets.csv
+deepflow_opendesk_cli auto-outbound-tasks mark-target-invalid 81
+deepflow_opendesk_cli auto-outbound-tasks delete 27 --yes
+```
+
+`add-targets` accepts a JSON object containing 1–5000 targets:
+
+```json
+{
+  "targets": [
+    {
+      "phone_number": "13800138000",
+      "user_id": 123,
+      "field_values": {"name": "Alice", "customer_level": "VIP"}
+    }
+  ]
+}
+```
+
+`import-targets` keeps the existing Excel/CSV file import behavior. Use
+`docs show outbound_tasks.create` or `docs show auto_outbound_tasks.create`
+after `schema fetch` to inspect the current request fields.
+
+Equivalent module invocation:
+
+```bash
+python -m deepflow_opendesk_cli docs list
+```
+
+## Construct Request Bodies
+
+`docs show <endpoint-key>` expands the request body schema into a field tree
+(name, type, required, enum, description) and prints a generated example
+payload, so an agent can construct a valid body without reading the OpenAPI
+components by hand. `docs schema <SchemaName>` does the same for any component
+schema in the fetched OpenAPI document.
+
+```bash
+deepflow_opendesk_cli docs show fields.create
+deepflow_opendesk_cli docs schema WelcomeMessageRuleCreate --json
+```
+
+Use the printed example as a starting point, edit values, then pass it with
+`--json` / `--json-file`. Add `--dry-run` to validate the plan without sending
+requests.
+
+## AI Agent Flow
+
+Recommended execution loop:
+
+```text
+1. schema fetch or docs list
+2. docs show <endpoint-key> (and docs schema <SchemaName> for body details)
+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
+```
+
+## Workflows
+
+`workflow list` shows named configuration workflows. Running a workflow without
+`--json-file` executes its built-in **read-only** plan, which snapshots the
+relevant current configuration (safe to run anytime). Pass `--json-file` with a
+batch-style operations array to run a custom write plan instead.
+
+```bash
+deepflow_opendesk_cli workflow list
+deepflow_opendesk_cli workflow run setup-tenant --dry-run
+deepflow_opendesk_cli workflow run setup-web-channel --json-file channel-plan.json --yes
+```
+
+## 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.2 → deepflow_opendesk_cli-0.1.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepflow-opendesk-cli"
-version = "0.1.2"
-description = "Command-line client for OpenDesk admin configuration APIs."
+version = "0.1.4"
+description = "Command-line client for OpenDesk admin configuration and outbound task APIs."
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [{ name = "DeepFlow AI" }]

{deepflow_opendesk_cli-0.1.2 → deepflow_opendesk_cli-0.1.4}/setup.py

@@ -7,8 +7,8 @@ from setuptools import find_packages, setup
 
 setup(
     name="deepflow-opendesk-cli",
-    version="0.1.2",
-    description="Command-line client for OpenDesk admin configuration APIs.",
+    version="0.1.4",
+    description="Command-line client for OpenDesk admin configuration and outbound task APIs.",
     long_description=Path("README.md").read_text(encoding="utf-8"),
     long_description_content_type="text/markdown",
     python_requires=">=3.11",

deepflow_opendesk_cli-0.1.4/src/deepflow_opendesk_cli/__init__.py

@@ -0,0 +1,3 @@
+"""OpenDesk admin configuration and outbound task API CLI."""
+
+__version__ = "0.1.4"