ClickUp Typed Client Patterns
Overview
Keep application code independent of transport details without presenting an ungoverned third-party wrapper as an official SDK.
Prerequisites
- Pinned official v2 and v3 OpenAPI documents or reviewed endpoint schemas
- A server-side HTTP runtime, validation library, and test framework
- Auth, Workspace, timeout, retry, redaction, and observability policies
Tool Discipline
Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.
Current Contract
- ClickUp publishes v2 and v3 OpenAPI specifications suitable for generation.
- Route every operation to an explicit version/base path and preserve ClickUp field types, including nullable webhook fields.
- Inject personal or OAuth tokens at call time and never store them in client objects serialized to logs.
- Retry only idempotent transient operations by default; writes need durable application idempotency.
Authentication
Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.
Instructions
- Inventory required operations and pin the matching official schema/version digest.
- Generate or hand-write a narrow transport and wrap it behind domain-oriented interfaces.
- Inject auth, Workspace allow-list, timeouts, content type, and redacted telemetry centrally.
- Create endpoint-specific pagination helpers instead of one incorrect universal iterator.
- Map statuses/error codes into typed retryable, authorization, plan, validation, and unknown classes.
- Test fixtures, schema drift, cancellation, retry ceilings, partial writes, and version migration seams.
Approval Boundaries
Do not auto-generate broad production access, silently fall back between API versions, or retry writes without a durable source key and owner policy.
Output
Return schema pins, supported operations, version routing, auth boundary, error/pagination policies, test coverage, and unsupported surfaces.
Error Handling
| Condition | Response |
|---|---|
| Generated client exposes the token | Block release and correct serialization/logging. |
| Schema has breaking drift | Regenerate in a review branch and run contract tests. |
| Endpoint pagination is unknown | Refuse full-scan claims until documented. |
| Write outcome is ambiguous | Reconcile by durable source ID before retry. |
Examples
The example below is a redacted operator receipt; it contains no task text, member data, credential, or webhook secret.
schemas=v2@sha256:...+v3@sha256:...; operations=11; direct-http=0; write-retry=off; contracts=pass