Metadata-Version: 2.4
Name: deepflow-opendesk-cli
Version: 0.1.3
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
```

## 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`.
