dida365-openapi

# Dida365 OpenAPI ## Overview Use this skill to call the documented Dida365 OpenAPI surface through the bundled Python CLI. Prefer `python scripts/dida365.py ...` over ad hoc `curl` because the bundled CLI already handles OAuth, config loading, exact project-name resolution, structured errors, and every documented endpoint. Use Python 3.9 or newer. The skill's default support surface is the documented API plus stable tested extensions that behaved consistently in real app/API round-trips: - task `kind` writes for `TEXT` and `NOTE` - task `tags` writes ## Boundaries This skill intentionally stays on the official Dida365 OpenAPI surface. It does not use browser-cookie private APIs. That means the following are explicit non-goals here: - standalone tag catalog / CRUD operations outside task create or update writes - project folder / group operations - full-account sync from private endpoints - private batch task/project operations - achievement or productivity-stat calculations from private data If a user asks for those, state that they are outside the official API-backed scope of this skill. ## Quick Start 1. Persist app config once: - `python scripts/dida365.py auth setup --client-id ... --client-secret ... --redirect-uri ...` 2. Preferred OAuth path: - `python scripts/dida365.py auth login-local --client-id ... --client-secret ...` - Open the URL printed to stderr and finish the browser flow. 3. Verify the connection: - `python scripts/dida365.py project data --project-id inbox` 4. Read or write data: - `python scripts/dida365.py project list` - `python scripts/dida365.py task create --project-id inbox --title "Example"` - `python scripts/dida365.py task completed --start-date ... --end-date ...` to query completed tasks across all projects Manual `authorize-url` / `exchange-code` flows remain supported; see `references/auth-and-config.md` when the localhost callback flow is not suitable. ## Command Rules - Use `auth` for OAuth helpers, token cache inspection, and token cleanup. - Use `project` for project CRUD and project data reads. - Use `task` for task CRUD, complete, move, completed-task queries, and filter queries. - Use `project data --project-id inbox` for inbox reads. Do not use `project get --project-id inbox`. - Use `--project-name` only when the user gave a human-readable project name. Resolution is exact match only. - Use `--json-file` or `--json` when the payload contains arrays or nested objects such as `items`, `reminders`, bulk move operations, or advanced filter bodies. - Treat first-class flags as the final override layer. `--json-file` loads a base payload, `--json` overrides it, and scalar flags override both. - After write operations such as `task create`, `task update`, and `task complete`, prefer a read-back step when the stored result matters. Use `task get` to verify fields like `reminders`, `repeatFlag`, `tags`, and `kind`. - Stable task `kind` writes are `TEXT` and `NOTE`. Use checklist `items` instead of direct `CHECKLIST` kind writes. - `task filter --tag-json` uses any-match / OR semantics in real testing, not all-match semantics. - Unfiltered `task filter` responses are capped at 200 rows for this endpoint on the tested account. Narrow the query window or add filters when completeness matters. - Use the enum values, date format, confirmed reminder patterns, and confirmed recurrence patterns from `references/api-reference.md`. Do not invent undocumented values. - The CLI blocks known gray-area reminder and recurrence values. If a pattern is not listed as confirmed in `references/api-reference.md`, do not assume it is safe. - Expect JSON on stdout for every command. Commands that allow successful empty responses normalize them to `{"ok": true}`. - Expect structured JSON errors on stderr for validation failures and non-2xx API responses. ## Auth And Config - Config precedence is CLI flags, then environment variables, then local files in `${XDG_CONFIG_HOME:-~/.config}/dida365-openapi/`. - `auth exchange-code` and `auth login-local` persist config and token state; `auth setup` persists config without performing OAuth. - See `references/auth-and-config.md` for environment variables, local file locations, and localhost callback details. ## Command Selection - Need the raw authorization link: use `auth authorize-url`. - Already have an OAuth `code`: use `auth exchange-code`. - Want the CLI to wait for the browser callback: use `auth login-local`. - Need to inspect current config or token state: use `auth status`. - Need to remove only the cached token: use `auth clear-token`. - Need inbox tasks or columns: use `project data --project-id inbox`. - Need one project by id or exact name: use `project get`. - Need tasks under a project plus columns: use `project data`. - Need today's tasks: use `task filter` with the local-day `startDate` / `endDate` window. - Need a weekly completion review: use `task completed` with a weekly date range and omit `--project-id` for an account-wide view. - Need an exact documented create/update payload: prefer `--json-file`. - Need a single move operation quickly: use `task move --from-project-id ... --to-project-id ... --task-id ...`. - Need multiple move operations: use `task move --json '[{...}, {...}]'`. - Need completed tasks across all projects: omit `--project-id` from `task completed`. ## References - Read [references/auth-and-config.md](references/auth-and-config.md) for OAuth flow details, config precedence, token cache rules, and local callback behavior. - Read [references/api-reference.md](references/api-reference.md) for endpoint coverage, field names, request-body quirks, documented schema notes, and confirmed `repeatFlag` patterns. - Read [references/examples.md](references/examples.md) for command examples covering common read/write flows.