hap-cli 0.6.8__tar.gz → 0.6.9__tar.gz

hap_cli-0.6.9/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: hap-cli
+Version: 0.6.9
+Summary: CLI harness for MingDAO HAP - Enterprise no-code platform
+Author: hap-cli
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: pycryptodome>=3.15
+Requires-Dist: python-socketio[client]>=5.10
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# hap-cli
+
+CLI harness for **MingDAO HAP** (明道云) — an enterprise no-code platform.
+
+## Installation
+
+```bash
+pip install hap-cli
+```
+
+The package ships with the v3 tool schemas it needs, so no extra setup is
+required after `pip install`.
+
+## Quick start
+
+### 1. Login
+
+```bash
+# MingDAO SaaS (default)
+hap auth login
+
+# Specific environment
+hap auth login mingdao                       # production
+hap auth login nocoly                        # Nocoly SaaS
+hap auth login https://hap.example.com       # self-hosted
+
+# Non-interactive (scripts / headless servers)
+hap auth login https://your-server.com --token YOUR_TOKEN
+```
+
+The browser flow opens the MingDAO login page and captures the token. If the
+callback can't reach the CLI (no GUI, restricted network), interrupt the
+command — it falls back to a paste prompt for the token shown on the success
+page.
+
+```bash
+hap auth whoami        # current user + current organization
+hap auth logout        # clear the saved token
+```
+
+### 2. Pick an organization and app
+
+```bash
+hap auth list-my-orgs                # current org marked with *
+hap auth switch-org ORG_ID           # switch the saved current org
+hap app list                         # uses the saved current org
+hap app list --org-id ORG_ID         # explicit override
+
+# Save a default app so every --app-id can be omitted
+hap app select APP_ID
+hap app unselect                     # clear it
+```
+
+`hap auth switch-org` only changes the default organization. The default app
+is managed independently with `hap app select` / `hap app unselect`.
+
+### 3. Explore worksheets and records
+
+```bash
+hap app info APP_ID                          # sections, worksheets, custom pages
+hap worksheet list                           # uses the default app
+hap worksheet info WORKSHEET_ID              # full structure (settings + fields)
+hap worksheet field-types                    # reference for field type IDs
+hap worksheet record list WORKSHEET_ID --page-size 10
+```
+
+### 4. JSON output
+
+```bash
+hap --json worksheet record list WORKSHEET_ID
+```
+
+Every command supports `--json` for machine-readable output.
+
+---
+
+## Commands
+
+The full authoritative list lives in [hap-cli-command.md](../hap-cli-command.md).
+The summary below covers the top-level groups; run `hap <group> --help` to
+discover every subcommand.
+
+### auth — authentication & session
+
+| Command | Description |
+|---|---|
+| `auth login [SERVER]` | Browser login (use `--token` for scripted login) |
+| `auth logout` | Clear the saved auth token |
+| `auth whoami` | Show current user and current organization |
+| `auth list-my-orgs` | List every org for the current account (current marked `*`) |
+| `auth switch-org ORG_ID` | Switch the saved current organization |
+
+### app — application management
+
+| Command | Description |
+|---|---|
+| `app list` | List apps in the org (default app marked `*`) |
+| `app list-managed` | Apps where the current user is admin |
+| `app info APP_ID` | App detail with sections, worksheets, custom pages |
+| `app create / update / delete` | App lifecycle |
+| `app select APP_ID` / `app unselect` | Manage the default app used when `--app-id` is omitted |
+| `app create-section / edit-section / delete-section` | Section management |
+| `app sort-sections / sort-worksheets` | Reorder sections / a section's worksheets |
+| `app create-item` | Batch-create empty worksheets / custom pages |
+| `app backup / restore / export / exports / backup-logs` | Backup & export |
+| `app usage / logs` | Statistics and operation logs |
+| `app role …` | Role CRUD, permissions, members, leave-all, applications |
+| `app optionset …` | Option set CRUD and cross-app moves |
+| `app knowledge list / search` | Vector knowledge bases |
+
+### worksheet — worksheets, views, custom actions, charts
+
+| Command | Description |
+|---|---|
+| `worksheet list / info / fields / field-types` | Discover structure |
+| `worksheet create / update / copy / delete` | Worksheet lifecycle |
+| `worksheet rules / save-rule` | Business rules |
+| `worksheet switches / edit-switch` | Feature switches |
+| `worksheet form-settings / save-form-settings` | Form submission settings |
+| `worksheet custom-actions / create-custom-action / delete-custom-action` | Custom action buttons |
+| `worksheet create-chart` | Build a statistics chart on a worksheet |
+| `worksheet view list / info / create / copy / delete / sort` | View management |
+
+### worksheet record — record CRUD
+
+| Command | Description |
+|---|---|
+| `worksheet record list / get` | Query and read |
+| `worksheet record create / update / delete` | Single-row CRUD |
+| `worksheet record batch-create / batch-update` | Bulk operations (main-site path; relation/sub-table cells persist) |
+| `worksheet record relations / share-link` | Linked records and share URLs |
+| `worksheet record discussions / add-discussion / delete-discussion` | Discussion threads |
+| `worksheet record logs` | Per-record change log |
+| `worksheet record pivot / bottom-stats` | Aggregations and summary rows |
+
+### workflow — process & node management
+
+| Command | Description |
+|---|---|
+| `workflow list / get / structure / history / groups / stats` | Inspect |
+| `workflow create / update / copy / move / delete` | Lifecycle |
+| `workflow publish / rollback` | Versioning |
+| `workflow trigger / trigger-pbp` | Manual trigger |
+| `workflow config-get / config-set` | Global config |
+| `workflow create-approval / update-approval / delete-approval` | Approval blocks |
+| `workflow node …` | Node CRUD, batch-add / batch-update / batch-delete (and `*-approval` variants), test-code / test-webhook / test-ai, controls, types, code templates |
+
+> Always run `hap workflow structure PROCESS_ID` before computing insertion
+> points, branch IDs, or approval block IDs. Don't fabricate node / block /
+> branch IDs.
+
+### approval — approvals & todos
+
+| Command | Description |
+|---|---|
+| `approval todo / todo-count / todo-filters / archived` | Pending and archived |
+| `approval get / get-by-row / list-by-row / work-item / operations / op-history / history / history-detail` | Read instance state |
+| `approval approve / reject / submit / sign / forward / urge` | Act on a task |
+| `approval revoke / terminate / restart / retry` | Lifecycle |
+| `approval batch / retry-batch / end-batch` | Bulk variants |
+| `approval list-types` | Enum reference |
+| `approval delegation create / list / list-by-company / list-by-principals / update` | Delegation CRUD |
+
+### custom-page — custom pages
+
+| Command | Description |
+|---|---|
+| `custom-page info / save / update-config` | Read and write the layout |
+| `custom-page create / rename / copy / delete` | Lifecycle |
+| `custom-page component-types` | Component reference |
+
+### contact — contacts & address book
+
+| Command | Description |
+|---|---|
+| `contact search / resolve` | Find members by keyword / name / email / phone |
+| `contact friends / friend-requests` | Address book |
+| `contact add-friend / accept-friend / reject-friend / ignore-friend / remove-friend` | Friend management |
+
+### department — directory
+
+| Command | Description |
+|---|---|
+| `department list / tree / info / members / search` | Organization directory queries |
+
+### post — feed posts
+
+| Command | Description |
+|---|---|
+| `post list / search / get` | Read |
+| `post create / update / delete` | Author |
+| `post comment / comments / comment-delete` | Comments |
+| `post like / likes / favorite` | Reactions |
+| `post pin / unpin / pinned` | Pinning |
+| `post topics` | Topic-tag autocomplete |
+
+### calendar — calendar & events
+
+| Command | Description |
+|---|---|
+| `calendar list / get / create / update / delete` | Event lifecycle |
+| `calendar categories` | Built-in categories |
+| `calendar add-member / remove-member` | Membership |
+
+### chat — chat & messaging
+
+| Command | Description |
+|---|---|
+| `chat list` | Recent sessions |
+| `chat messages` | 1-on-1 / group / inbox messages |
+| `chat files` | Files shared in a chat |
+| `chat send-to-one` | Send a plain-text message to one or more users (1-on-1) |
+| `chat send-to-group` | Send a plain-text message to a group chat |
+| `chat card-detail` | Resolve embedded card references |
+
+### group — chat group lifecycle
+
+| Command | Description |
+|---|---|
+| `group info GROUP_ID` | Group metadata |
+| `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
+| `group add-member` | Add one or more members (`--group-id`, `--account-id`) |
+| `group remove-member` | Remove a single member (`--group-id`, `--account-id`) |
+
+### region — administrative regions
+
+| Command | Description |
+|---|---|
+| `region get` | Look up regions by `--id` or `--search` keyword |
+
+### icon — built-in icon catalogue
+
+| Command | Description |
+|---|---|
+| `icon search` | Search icons by Chinese/English keyword (OR across terms, more matches rank higher); no keyword lists all |
+| `icon list` | List every icon with its keywords |
+
+### config — local CLI settings
+
+| Command | Description |
+|---|---|
+| `config show` | Display the current configuration summary |
+| `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
+| `config language [LANG]` | Switch UI language (`en` / `zh-Hans` / `zh-Hant` / `ja`) |
+| `config log on / off / status` | Toggle and inspect API logging |
+| `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
+| `config log view [--lines N] [--no-follow]` | Tail the log file |
+
+Logs land in `~/.hap-cli/hap-cli.log` (10 MB × 3, rotating). When enabled,
+every HAP API call is logged at `INFO` with URL, request body, response
+body, and a redacted `Authorization` header (first 16 chars). `password`
+and other sensitive keys are masked. `HAP_LOG_LEVEL=DEBUG` temporarily
+overrides the persisted level.
+
+---
+
+## Default app & organization
+
+Every command that needs an `--app-id` resolves it in this order:
+
+1. The explicit `--app-id` you passed;
+2. The default app saved by `hap app select`;
+3. Otherwise the command exits with an error suggesting `hap app select APP_ID`.
+
+`hap auth switch-org` changes the default *organization* only — it does not
+touch the default app.
+
+## REPL mode
+
+```bash
+hap repl
+hap> worksheet record list WORKSHEET_ID
+hap> --json workflow list
+hap> approval todo-count
+hap> quit
+```
+
+Drop the leading `hap`. Prefix `--json` to switch to JSON output for one
+command.
+
+## Examples
+
+```bash
+# Create a record
+hap worksheet record create WORKSHEET_ID -f "c001=value1" -f "c002=value2"
+
+# Build a workflow
+hap workflow create --name "My Flow" --app-id APP_ID
+hap workflow node add PROCESS_ID --type 4 --name "Manager Approval"
+hap workflow node save PROCESS_ID NODE_ID --config '{"accounts":[...]}'
+hap workflow publish PROCESS_ID
+hap workflow trigger PROCESS_ID --source-id ROW_ID
+
+# Approve / reject
+hap approval todo --type 4
+hap approval approve INSTANCE_ID --opinion "Looks good"
+hap approval reject INSTANCE_ID --opinion "Need revision"
+hap approval batch --action 4 -s ID1 -s ID2
+
+# Roles
+hap app role list
+hap app role add-member ROLE_ID -u USER_ID
+
+# Knowledge base search
+hap app knowledge search --keyword "onboarding" --mode hybrid
+```
+
+## Project layout
+
+```
+hap_cli/
+  commands/   thin Click layer — argument parsing & output formatting only
+  core/       business logic (transport, payload assembly, parsing)
+  core/v3/    v3 dispatcher — builds Click commands from sources/v3-api-schema/*.yaml
+  locale/     translation catalog (English-only at the moment)
+sources/v3-api-schema/
+              OpenAPI v3 specs (apifox stable list) + INDEX.json,
+              copied into the wheel at build time
+docs/         end-user documentation
+```
+
+## License
+
+Apache 2.0.

hap_cli-0.6.9/README.md

@@ -0,0 +1,324 @@
+# hap-cli
+
+CLI harness for **MingDAO HAP** (明道云) — an enterprise no-code platform.
+
+## Installation
+
+```bash
+pip install hap-cli
+```
+
+The package ships with the v3 tool schemas it needs, so no extra setup is
+required after `pip install`.
+
+## Quick start
+
+### 1. Login
+
+```bash
+# MingDAO SaaS (default)
+hap auth login
+
+# Specific environment
+hap auth login mingdao                       # production
+hap auth login nocoly                        # Nocoly SaaS
+hap auth login https://hap.example.com       # self-hosted
+
+# Non-interactive (scripts / headless servers)
+hap auth login https://your-server.com --token YOUR_TOKEN
+```
+
+The browser flow opens the MingDAO login page and captures the token. If the
+callback can't reach the CLI (no GUI, restricted network), interrupt the
+command — it falls back to a paste prompt for the token shown on the success
+page.
+
+```bash
+hap auth whoami        # current user + current organization
+hap auth logout        # clear the saved token
+```
+
+### 2. Pick an organization and app
+
+```bash
+hap auth list-my-orgs                # current org marked with *
+hap auth switch-org ORG_ID           # switch the saved current org
+hap app list                         # uses the saved current org
+hap app list --org-id ORG_ID         # explicit override
+
+# Save a default app so every --app-id can be omitted
+hap app select APP_ID
+hap app unselect                     # clear it
+```
+
+`hap auth switch-org` only changes the default organization. The default app
+is managed independently with `hap app select` / `hap app unselect`.
+
+### 3. Explore worksheets and records
+
+```bash
+hap app info APP_ID                          # sections, worksheets, custom pages
+hap worksheet list                           # uses the default app
+hap worksheet info WORKSHEET_ID              # full structure (settings + fields)
+hap worksheet field-types                    # reference for field type IDs
+hap worksheet record list WORKSHEET_ID --page-size 10
+```
+
+### 4. JSON output
+
+```bash
+hap --json worksheet record list WORKSHEET_ID
+```
+
+Every command supports `--json` for machine-readable output.
+
+---
+
+## Commands
+
+The full authoritative list lives in [hap-cli-command.md](../hap-cli-command.md).
+The summary below covers the top-level groups; run `hap <group> --help` to
+discover every subcommand.
+
+### auth — authentication & session
+
+| Command | Description |
+|---|---|
+| `auth login [SERVER]` | Browser login (use `--token` for scripted login) |
+| `auth logout` | Clear the saved auth token |
+| `auth whoami` | Show current user and current organization |
+| `auth list-my-orgs` | List every org for the current account (current marked `*`) |
+| `auth switch-org ORG_ID` | Switch the saved current organization |
+
+### app — application management
+
+| Command | Description |
+|---|---|
+| `app list` | List apps in the org (default app marked `*`) |
+| `app list-managed` | Apps where the current user is admin |
+| `app info APP_ID` | App detail with sections, worksheets, custom pages |
+| `app create / update / delete` | App lifecycle |
+| `app select APP_ID` / `app unselect` | Manage the default app used when `--app-id` is omitted |
+| `app create-section / edit-section / delete-section` | Section management |
+| `app sort-sections / sort-worksheets` | Reorder sections / a section's worksheets |
+| `app create-item` | Batch-create empty worksheets / custom pages |
+| `app backup / restore / export / exports / backup-logs` | Backup & export |
+| `app usage / logs` | Statistics and operation logs |
+| `app role …` | Role CRUD, permissions, members, leave-all, applications |
+| `app optionset …` | Option set CRUD and cross-app moves |
+| `app knowledge list / search` | Vector knowledge bases |
+
+### worksheet — worksheets, views, custom actions, charts
+
+| Command | Description |
+|---|---|
+| `worksheet list / info / fields / field-types` | Discover structure |
+| `worksheet create / update / copy / delete` | Worksheet lifecycle |
+| `worksheet rules / save-rule` | Business rules |
+| `worksheet switches / edit-switch` | Feature switches |
+| `worksheet form-settings / save-form-settings` | Form submission settings |
+| `worksheet custom-actions / create-custom-action / delete-custom-action` | Custom action buttons |
+| `worksheet create-chart` | Build a statistics chart on a worksheet |
+| `worksheet view list / info / create / copy / delete / sort` | View management |
+
+### worksheet record — record CRUD
+
+| Command | Description |
+|---|---|
+| `worksheet record list / get` | Query and read |
+| `worksheet record create / update / delete` | Single-row CRUD |
+| `worksheet record batch-create / batch-update` | Bulk operations (main-site path; relation/sub-table cells persist) |
+| `worksheet record relations / share-link` | Linked records and share URLs |
+| `worksheet record discussions / add-discussion / delete-discussion` | Discussion threads |
+| `worksheet record logs` | Per-record change log |
+| `worksheet record pivot / bottom-stats` | Aggregations and summary rows |
+
+### workflow — process & node management
+
+| Command | Description |
+|---|---|
+| `workflow list / get / structure / history / groups / stats` | Inspect |
+| `workflow create / update / copy / move / delete` | Lifecycle |
+| `workflow publish / rollback` | Versioning |
+| `workflow trigger / trigger-pbp` | Manual trigger |
+| `workflow config-get / config-set` | Global config |
+| `workflow create-approval / update-approval / delete-approval` | Approval blocks |
+| `workflow node …` | Node CRUD, batch-add / batch-update / batch-delete (and `*-approval` variants), test-code / test-webhook / test-ai, controls, types, code templates |
+
+> Always run `hap workflow structure PROCESS_ID` before computing insertion
+> points, branch IDs, or approval block IDs. Don't fabricate node / block /
+> branch IDs.
+
+### approval — approvals & todos
+
+| Command | Description |
+|---|---|
+| `approval todo / todo-count / todo-filters / archived` | Pending and archived |
+| `approval get / get-by-row / list-by-row / work-item / operations / op-history / history / history-detail` | Read instance state |
+| `approval approve / reject / submit / sign / forward / urge` | Act on a task |
+| `approval revoke / terminate / restart / retry` | Lifecycle |
+| `approval batch / retry-batch / end-batch` | Bulk variants |
+| `approval list-types` | Enum reference |
+| `approval delegation create / list / list-by-company / list-by-principals / update` | Delegation CRUD |
+
+### custom-page — custom pages
+
+| Command | Description |
+|---|---|
+| `custom-page info / save / update-config` | Read and write the layout |
+| `custom-page create / rename / copy / delete` | Lifecycle |
+| `custom-page component-types` | Component reference |
+
+### contact — contacts & address book
+
+| Command | Description |
+|---|---|
+| `contact search / resolve` | Find members by keyword / name / email / phone |
+| `contact friends / friend-requests` | Address book |
+| `contact add-friend / accept-friend / reject-friend / ignore-friend / remove-friend` | Friend management |
+
+### department — directory
+
+| Command | Description |
+|---|---|
+| `department list / tree / info / members / search` | Organization directory queries |
+
+### post — feed posts
+
+| Command | Description |
+|---|---|
+| `post list / search / get` | Read |
+| `post create / update / delete` | Author |
+| `post comment / comments / comment-delete` | Comments |
+| `post like / likes / favorite` | Reactions |
+| `post pin / unpin / pinned` | Pinning |
+| `post topics` | Topic-tag autocomplete |
+
+### calendar — calendar & events
+
+| Command | Description |
+|---|---|
+| `calendar list / get / create / update / delete` | Event lifecycle |
+| `calendar categories` | Built-in categories |
+| `calendar add-member / remove-member` | Membership |
+
+### chat — chat & messaging
+
+| Command | Description |
+|---|---|
+| `chat list` | Recent sessions |
+| `chat messages` | 1-on-1 / group / inbox messages |
+| `chat files` | Files shared in a chat |
+| `chat send-to-one` | Send a plain-text message to one or more users (1-on-1) |
+| `chat send-to-group` | Send a plain-text message to a group chat |
+| `chat card-detail` | Resolve embedded card references |
+
+### group — chat group lifecycle
+
+| Command | Description |
+|---|---|
+| `group info GROUP_ID` | Group metadata |
+| `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
+| `group add-member` | Add one or more members (`--group-id`, `--account-id`) |
+| `group remove-member` | Remove a single member (`--group-id`, `--account-id`) |
+
+### region — administrative regions
+
+| Command | Description |
+|---|---|
+| `region get` | Look up regions by `--id` or `--search` keyword |
+
+### icon — built-in icon catalogue
+
+| Command | Description |
+|---|---|
+| `icon search` | Search icons by Chinese/English keyword (OR across terms, more matches rank higher); no keyword lists all |
+| `icon list` | List every icon with its keywords |
+
+### config — local CLI settings
+
+| Command | Description |
+|---|---|
+| `config show` | Display the current configuration summary |
+| `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
+| `config language [LANG]` | Switch UI language (`en` / `zh-Hans` / `zh-Hant` / `ja`) |
+| `config log on / off / status` | Toggle and inspect API logging |
+| `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
+| `config log view [--lines N] [--no-follow]` | Tail the log file |
+
+Logs land in `~/.hap-cli/hap-cli.log` (10 MB × 3, rotating). When enabled,
+every HAP API call is logged at `INFO` with URL, request body, response
+body, and a redacted `Authorization` header (first 16 chars). `password`
+and other sensitive keys are masked. `HAP_LOG_LEVEL=DEBUG` temporarily
+overrides the persisted level.
+
+---
+
+## Default app & organization
+
+Every command that needs an `--app-id` resolves it in this order:
+
+1. The explicit `--app-id` you passed;
+2. The default app saved by `hap app select`;
+3. Otherwise the command exits with an error suggesting `hap app select APP_ID`.
+
+`hap auth switch-org` changes the default *organization* only — it does not
+touch the default app.
+
+## REPL mode
+
+```bash
+hap repl
+hap> worksheet record list WORKSHEET_ID
+hap> --json workflow list
+hap> approval todo-count
+hap> quit
+```
+
+Drop the leading `hap`. Prefix `--json` to switch to JSON output for one
+command.
+
+## Examples
+
+```bash
+# Create a record
+hap worksheet record create WORKSHEET_ID -f "c001=value1" -f "c002=value2"
+
+# Build a workflow
+hap workflow create --name "My Flow" --app-id APP_ID
+hap workflow node add PROCESS_ID --type 4 --name "Manager Approval"
+hap workflow node save PROCESS_ID NODE_ID --config '{"accounts":[...]}'
+hap workflow publish PROCESS_ID
+hap workflow trigger PROCESS_ID --source-id ROW_ID
+
+# Approve / reject
+hap approval todo --type 4
+hap approval approve INSTANCE_ID --opinion "Looks good"
+hap approval reject INSTANCE_ID --opinion "Need revision"
+hap approval batch --action 4 -s ID1 -s ID2
+
+# Roles
+hap app role list
+hap app role add-member ROLE_ID -u USER_ID
+
+# Knowledge base search
+hap app knowledge search --keyword "onboarding" --mode hybrid
+```
+
+## Project layout
+
+```
+hap_cli/
+  commands/   thin Click layer — argument parsing & output formatting only
+  core/       business logic (transport, payload assembly, parsing)
+  core/v3/    v3 dispatcher — builds Click commands from sources/v3-api-schema/*.yaml
+  locale/     translation catalog (English-only at the moment)
+sources/v3-api-schema/
+              OpenAPI v3 specs (apifox stable list) + INDEX.json,
+              copied into the wheel at build time
+docs/         end-user documentation
+```
+
+## License
+
+Apache 2.0.