@rawdash/connector-clickup 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +147 -0
- package/dist/index.d.ts +761 -0
- package/dist/index.js +673 -0
- package/dist/index.js.map +1 -0
- package/package.json +43 -0
package/README.md
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
<!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
|
|
2
|
+
|
|
3
|
+
# @rawdash/connector-clickup
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@rawdash/connector-clickup)
|
|
6
|
+
[](https://github.com/rawdash/rawdash/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
Sync spaces, folders, lists, tasks, and task lifecycle events from a ClickUp workspace for throughput, open-work, and status-distribution analytics.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm install @rawdash/connector-clickup
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Authentication
|
|
17
|
+
|
|
18
|
+
Authenticates with a ClickUp personal API token sent in the Authorization header. The token scopes the sync to the workspaces, spaces, and tasks the issuing user can access.
|
|
19
|
+
|
|
20
|
+
1. Open ClickUp -> Settings -> Apps.
|
|
21
|
+
2. Under API Token, click Generate (or copy the existing personal token). It starts with pk\_.
|
|
22
|
+
3. Store it as a secret and reference it from the connector config as `apiToken: secret("CLICKUP_API_TOKEN")`, alongside your Workspace ID.
|
|
23
|
+
|
|
24
|
+
## Configuration
|
|
25
|
+
|
|
26
|
+
| Field | Type | Required | Description |
|
|
27
|
+
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| `apiToken` | secret | Yes | ClickUp personal API token. Create one at ClickUp -> Settings -> Apps -> API Token. |
|
|
29
|
+
| `teamId` | string | Yes | ClickUp Workspace (team) ID to sync. Find it in the URL: app.clickup.com/<workspace_id>/home. |
|
|
30
|
+
| `resources` | array | No | Which ClickUp resources to sync. Omit to sync all of them. 'task_events' derives created / closed lifecycle events from each task's timestamps and shares the task query with 'tasks'. |
|
|
31
|
+
|
|
32
|
+
## Resources
|
|
33
|
+
|
|
34
|
+
- **`clickup_space`** _(entity)_ - Workspace spaces with their name and privacy flag.
|
|
35
|
+
- Endpoint: `GET /team/{team_id}/space`
|
|
36
|
+
- `name`: Space name.
|
|
37
|
+
- `private`: Whether the space is private.
|
|
38
|
+
- `archived`: Whether the space is archived.
|
|
39
|
+
- **`clickup_folder`** _(entity)_ - Folders within each space, with their parent space.
|
|
40
|
+
- Endpoint: `GET /space/{space_id}/folder`
|
|
41
|
+
- `name`: Folder name.
|
|
42
|
+
- `spaceId`: Parent space id.
|
|
43
|
+
- `taskCount`: Number of tasks across the folder at sync time.
|
|
44
|
+
- `archived`: Whether the folder is archived.
|
|
45
|
+
- **`clickup_list`** _(entity)_ - Lists (folder-scoped and folderless) with their parent folder and space.
|
|
46
|
+
- Endpoint: `GET /space/{space_id}/list and GET /folder/{folder_id}/list`
|
|
47
|
+
- `name`: List name.
|
|
48
|
+
- `folderId`: Parent folder id (null if folderless).
|
|
49
|
+
- `spaceId`: Parent space id.
|
|
50
|
+
- `taskCount`: Number of tasks in the list at sync time.
|
|
51
|
+
- `archived`: Whether the list is archived.
|
|
52
|
+
- **`clickup_task`** _(entity)_ - Tasks with their status, priority, assignees, parent list / folder / space, tags, and lifecycle timestamps.
|
|
53
|
+
- Endpoint: `GET /team/{team_id}/task`
|
|
54
|
+
- `name`: Task name.
|
|
55
|
+
- `status`: Current status name (e.g. "in progress").
|
|
56
|
+
- `statusType`: Status category: open, custom, closed, or done.
|
|
57
|
+
- `priority`: Priority label (urgent / high / normal / low), or null.
|
|
58
|
+
- `listId`: Parent list id.
|
|
59
|
+
- `folderId`: Parent folder id.
|
|
60
|
+
- `spaceId`: Parent space id.
|
|
61
|
+
- `assignees`: Assignee user ids.
|
|
62
|
+
- `assigneeCount`: Number of assignees.
|
|
63
|
+
- `tags`: Tag names on the task.
|
|
64
|
+
- `createdAt`: When the task was created (Unix ms).
|
|
65
|
+
- `closedAt`: When the task was closed (Unix ms; null if open).
|
|
66
|
+
- `dueDate`: Task due date (Unix ms; null if unset).
|
|
67
|
+
- **`clickup_task_event`** _(event)_ - Task lifecycle events (created / closed) derived from each task's date_created and date_closed. The scope is cleared and rewritten from a full task scan on every sync (including incremental runs).
|
|
68
|
+
- Endpoint: `GET /team/{team_id}/task`
|
|
69
|
+
- Derived from each task's own date_created / date_closed timestamps, not from a separate per-task activity call. Drives created-per-day and closed-per-day throughput timeseries.
|
|
70
|
+
- `kind`: "created" or "closed".
|
|
71
|
+
- `taskId`: Task the event belongs to.
|
|
72
|
+
- `listId`: Parent list id, denormalised.
|
|
73
|
+
- `spaceId`: Parent space id, denormalised.
|
|
74
|
+
- `status`: Task status name at sync time.
|
|
75
|
+
|
|
76
|
+
## Example
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
import {
|
|
80
|
+
defineConfig,
|
|
81
|
+
defineDashboard,
|
|
82
|
+
defineMetric,
|
|
83
|
+
secret,
|
|
84
|
+
} from '@rawdash/core';
|
|
85
|
+
|
|
86
|
+
const clickup = {
|
|
87
|
+
name: 'clickup',
|
|
88
|
+
connectorId: 'clickup',
|
|
89
|
+
config: {
|
|
90
|
+
apiToken: secret('CLICKUP_API_TOKEN'),
|
|
91
|
+
teamId: '9000000000',
|
|
92
|
+
},
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
export default defineConfig({
|
|
96
|
+
connectors: [clickup],
|
|
97
|
+
dashboards: {
|
|
98
|
+
product: defineDashboard({
|
|
99
|
+
widgets: {
|
|
100
|
+
open_tasks: {
|
|
101
|
+
kind: 'stat',
|
|
102
|
+
title: 'Open tasks',
|
|
103
|
+
metric: defineMetric({
|
|
104
|
+
connector: clickup,
|
|
105
|
+
shape: 'entity',
|
|
106
|
+
entityType: 'clickup_task',
|
|
107
|
+
fn: 'count',
|
|
108
|
+
filter: [{ field: 'statusType', op: 'eq', value: 'open' }],
|
|
109
|
+
}),
|
|
110
|
+
},
|
|
111
|
+
tasks_closed: {
|
|
112
|
+
kind: 'timeseries',
|
|
113
|
+
title: 'Tasks closed per day',
|
|
114
|
+
window: '30d',
|
|
115
|
+
metric: defineMetric({
|
|
116
|
+
connector: clickup,
|
|
117
|
+
shape: 'event',
|
|
118
|
+
name: 'clickup_task_event',
|
|
119
|
+
fn: 'count',
|
|
120
|
+
filter: [{ field: 'kind', op: 'eq', value: 'closed' }],
|
|
121
|
+
}),
|
|
122
|
+
},
|
|
123
|
+
},
|
|
124
|
+
}),
|
|
125
|
+
},
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Rate limits
|
|
130
|
+
|
|
131
|
+
ClickUp rate-limits per token (100 requests/minute on the Free Forever / Unlimited plans, higher on Business+) and exposes X-RateLimit-Remaining / X-RateLimit-Reset headers; the shared HTTP client backs off on 429.
|
|
132
|
+
|
|
133
|
+
## Limitations
|
|
134
|
+
|
|
135
|
+
- Personal API token auth only (OAuth app installs are out of scope).
|
|
136
|
+
- Task lifecycle events (created / closed) are derived from each task's own date_created / date_closed fields rather than the per-task activity feed, which avoids an N+1 sync; the event scope is cleared and rewritten from a full task scan on every sync.
|
|
137
|
+
- Custom fields, comments, time tracking, and goals are out of scope.
|
|
138
|
+
|
|
139
|
+
## Links
|
|
140
|
+
|
|
141
|
+
- [Rawdash docs](https://rawdash.dev/docs/connectors)
|
|
142
|
+
- [ClickUp API docs](https://clickup.com/api)
|
|
143
|
+
- [GitHub](https://github.com/rawdash/rawdash)
|
|
144
|
+
|
|
145
|
+
## License
|
|
146
|
+
|
|
147
|
+
Apache-2.0
|