@todoist/comms-sdk 0.0.1 → 5.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/LICENSE +21 -0
- package/README.md +182 -39
- package/dist/esm/authentication.js +247 -0
- package/dist/esm/clients/add-comment-helper.js +41 -0
- package/dist/esm/clients/attachments-client.js +99 -0
- package/dist/esm/clients/base-client.js +30 -0
- package/dist/esm/clients/channels-client.js +209 -0
- package/dist/esm/clients/comments-client.js +177 -0
- package/dist/esm/clients/conversation-messages-client.js +167 -0
- package/dist/esm/clients/conversations-client.js +281 -0
- package/dist/esm/clients/groups-client.js +170 -0
- package/dist/esm/clients/hooks-client.js +50 -0
- package/dist/esm/clients/inbox-client.js +186 -0
- package/dist/esm/clients/notify-audience.js +43 -0
- package/dist/esm/clients/reactions-client.js +96 -0
- package/dist/esm/clients/search-client.js +140 -0
- package/dist/esm/clients/threads-client.js +363 -0
- package/dist/esm/clients/users-client.js +368 -0
- package/dist/esm/clients/workspace-users-client.js +299 -0
- package/dist/esm/clients/workspaces-client.js +177 -0
- package/dist/esm/comms-api.js +67 -0
- package/dist/esm/consts/endpoints.js +31 -0
- package/dist/esm/index.js +20 -0
- package/dist/esm/migration.js +92 -0
- package/dist/esm/testUtils/msw-handlers.js +45 -0
- package/dist/esm/testUtils/msw-setup.js +32 -0
- package/dist/esm/testUtils/obsidian-fetch-adapter.js +50 -0
- package/dist/esm/testUtils/test-defaults.js +103 -0
- package/dist/esm/transport/fetch-with-retry.js +240 -0
- package/dist/esm/transport/http-client.js +53 -0
- package/dist/esm/transport/http-dispatcher.js +149 -0
- package/dist/esm/types/api-version.js +5 -0
- package/dist/esm/types/entities.js +515 -0
- package/dist/esm/types/enums.js +34 -0
- package/dist/esm/types/errors.js +82 -0
- package/dist/esm/types/http.js +1 -0
- package/dist/esm/types/index.js +6 -0
- package/dist/esm/types/requests.js +184 -0
- package/dist/esm/utils/case-conversion.js +47 -0
- package/dist/esm/utils/conversation-title.js +110 -0
- package/dist/esm/utils/headers.js +29 -0
- package/dist/esm/utils/index.js +5 -0
- package/dist/esm/utils/multipart-upload.js +198 -0
- package/dist/esm/utils/reply-recipients.js +111 -0
- package/dist/esm/utils/timestamp-conversion.js +54 -0
- package/dist/esm/utils/url-helpers.js +202 -0
- package/dist/esm/utils/uuidv7.js +170 -0
- package/dist/types/authentication.d.ts +183 -0
- package/dist/types/clients/add-comment-helper.d.ts +32 -0
- package/dist/types/clients/attachments-client.d.ts +55 -0
- package/dist/types/clients/base-client.d.ts +37 -0
- package/dist/types/clients/channels-client.d.ts +211 -0
- package/dist/types/clients/comments-client.d.ts +228 -0
- package/dist/types/clients/conversation-messages-client.d.ts +201 -0
- package/dist/types/clients/conversations-client.d.ts +366 -0
- package/dist/types/clients/groups-client.d.ts +148 -0
- package/dist/types/clients/hooks-client.d.ts +29 -0
- package/dist/types/clients/inbox-client.d.ts +478 -0
- package/dist/types/clients/notify-audience.d.ts +22 -0
- package/dist/types/clients/reactions-client.d.ts +57 -0
- package/dist/types/clients/search-client.d.ts +71 -0
- package/dist/types/clients/threads-client.d.ts +547 -0
- package/dist/types/clients/users-client.d.ts +280 -0
- package/dist/types/clients/workspace-users-client.d.ts +172 -0
- package/dist/types/clients/workspaces-client.d.ts +154 -0
- package/dist/types/comms-api.d.ts +73 -0
- package/dist/types/consts/endpoints.d.ts +27 -0
- package/dist/types/index.d.ts +21 -0
- package/dist/types/migration.d.ts +78 -0
- package/dist/types/testUtils/msw-handlers.d.ts +28 -0
- package/dist/types/testUtils/msw-setup.d.ts +1 -0
- package/dist/types/testUtils/obsidian-fetch-adapter.d.ts +29 -0
- package/dist/types/testUtils/test-defaults.d.ts +17 -0
- package/dist/types/transport/fetch-with-retry.d.ts +4 -0
- package/dist/types/transport/http-client.d.ts +14 -0
- package/dist/types/transport/http-dispatcher.d.ts +46 -0
- package/dist/types/types/api-version.d.ts +6 -0
- package/dist/types/types/entities.d.ts +3081 -0
- package/dist/types/types/enums.d.ts +55 -0
- package/dist/types/types/errors.d.ts +57 -0
- package/dist/types/types/http.d.ts +60 -0
- package/dist/types/types/index.d.ts +6 -0
- package/dist/types/types/requests.d.ts +604 -0
- package/dist/types/utils/case-conversion.d.ts +8 -0
- package/dist/types/utils/conversation-title.d.ts +84 -0
- package/dist/types/utils/headers.d.ts +13 -0
- package/dist/types/utils/index.d.ts +6 -0
- package/dist/types/utils/multipart-upload.d.ts +59 -0
- package/dist/types/utils/reply-recipients.d.ts +60 -0
- package/dist/types/utils/timestamp-conversion.d.ts +13 -0
- package/dist/types/utils/url-helpers.d.ts +129 -0
- package/dist/types/utils/uuidv7.d.ts +42 -0
- package/package.json +80 -8
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { ENDPOINT_CONVERSATIONS } from '../consts/endpoints.js';
|
|
3
|
+
import { request } from '../transport/http-client.js';
|
|
4
|
+
import { ConversationSchema, createConversationSchema, StatusOkSchema, UnreadConversationSchema, } from '../types/entities.js';
|
|
5
|
+
import { resolveCreateId } from '../utils/uuidv7.js';
|
|
6
|
+
import { BaseClient } from './base-client.js';
|
|
7
|
+
export const ConversationListSchema = z.array(ConversationSchema);
|
|
8
|
+
const GetUnreadResponseSchema = z.object({
|
|
9
|
+
data: z.array(UnreadConversationSchema),
|
|
10
|
+
version: z.number().int(),
|
|
11
|
+
});
|
|
12
|
+
/**
|
|
13
|
+
* Client for `/api/v1.0/conversations/`. `getOrCreate` requires an `id` (the
|
|
14
|
+
* SDK auto-generates one for new conversations); the backend dedupes on
|
|
15
|
+
* `userIds`, so an existing conversation will be returned with its own
|
|
16
|
+
* already-assigned `id` and your generated one is silently dropped.
|
|
17
|
+
*/
|
|
18
|
+
export class ConversationsClient extends BaseClient {
|
|
19
|
+
constructor() {
|
|
20
|
+
super(...arguments);
|
|
21
|
+
this.linkBaseUrl = this.getLinkBaseUrl();
|
|
22
|
+
// Reuse the shared singletons when no custom base is configured.
|
|
23
|
+
this.conversationSchema = this.linkBaseUrl
|
|
24
|
+
? createConversationSchema(this.linkBaseUrl)
|
|
25
|
+
: ConversationSchema;
|
|
26
|
+
this.conversationListSchema = this.linkBaseUrl
|
|
27
|
+
? z.array(this.conversationSchema)
|
|
28
|
+
: ConversationListSchema;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Gets a page of conversations for a workspace, newest activity first.
|
|
32
|
+
* The server returns at most 500 rows per request (20 by default); pass
|
|
33
|
+
* the last row's `lastActive`/`id` as `olderThan`/`beforeId` to fetch
|
|
34
|
+
* the next page. Paired, they form a strict compound boundary, so pages
|
|
35
|
+
* never repeat rows. Omitting `archived` returns active and archived
|
|
36
|
+
* conversations mixed.
|
|
37
|
+
*
|
|
38
|
+
* @param args - The arguments for getting conversations.
|
|
39
|
+
* @param args.workspaceId - The workspace ID.
|
|
40
|
+
* @param args.archived - Optional flag to filter archived (true) or active (false) conversations.
|
|
41
|
+
* @param args.olderThan - Optional date to get conversations last active before.
|
|
42
|
+
* @param args.beforeId - Optional conversation id. Paired with olderThan it forms the
|
|
43
|
+
* strict compound cursor; alone it pages by conversation id order instead.
|
|
44
|
+
* @param args.limit - Optional page size (server default 20, max 500).
|
|
45
|
+
* @returns An array of conversation objects.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* ```typescript
|
|
49
|
+
* const page = await api.conversations.getConversations({ workspaceId: 123, limit: 500 })
|
|
50
|
+
* const last = page.at(-1)
|
|
51
|
+
* const nextPage = last
|
|
52
|
+
* ? await api.conversations.getConversations({
|
|
53
|
+
* workspaceId: 123,
|
|
54
|
+
* limit: 500,
|
|
55
|
+
* olderThan: last.lastActive,
|
|
56
|
+
* beforeId: last.id,
|
|
57
|
+
* })
|
|
58
|
+
* : []
|
|
59
|
+
* ```
|
|
60
|
+
*/
|
|
61
|
+
getConversations(args) {
|
|
62
|
+
// Fields are picked explicitly (matching getThreads/getComments) so a
|
|
63
|
+
// future Date field can't silently reach the generic snake-casing,
|
|
64
|
+
// which would turn it into an empty object on the wire.
|
|
65
|
+
const params = { workspaceId: args.workspaceId };
|
|
66
|
+
if (args.archived != null)
|
|
67
|
+
params.archived = args.archived;
|
|
68
|
+
if (args.olderThan)
|
|
69
|
+
params.olderThanTs = Math.floor(args.olderThan.getTime() / 1000);
|
|
70
|
+
if (args.beforeId != null)
|
|
71
|
+
params.beforeId = args.beforeId;
|
|
72
|
+
if (args.limit != null)
|
|
73
|
+
params.limit = args.limit;
|
|
74
|
+
return request({
|
|
75
|
+
httpMethod: 'GET',
|
|
76
|
+
baseUri: this.getBaseUri(),
|
|
77
|
+
relativePath: `${ENDPOINT_CONVERSATIONS}/get`,
|
|
78
|
+
apiToken: this.apiToken,
|
|
79
|
+
payload: params,
|
|
80
|
+
headers: this.headers,
|
|
81
|
+
customFetch: this.customFetch,
|
|
82
|
+
}).then((response) => this.conversationListSchema.parse(response.data));
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Gets a single conversation object by id.
|
|
86
|
+
*
|
|
87
|
+
* @param id - The conversation ID.
|
|
88
|
+
* @returns The conversation object.
|
|
89
|
+
*/
|
|
90
|
+
getConversation(id) {
|
|
91
|
+
return this.simple('GET', 'getone', { id }, this.conversationSchema);
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Gets an existing 1:1 / group conversation with `userIds`, or creates a
|
|
95
|
+
* new one. `id` is auto-generated if not supplied — on dedupe, the
|
|
96
|
+
* backend returns the existing conversation's `id` instead.
|
|
97
|
+
*
|
|
98
|
+
* @param args - The arguments for getting or creating a conversation.
|
|
99
|
+
* @param args.workspaceId - The workspace ID.
|
|
100
|
+
* @param args.userIds - Array of user IDs to include in the conversation.
|
|
101
|
+
* @returns The conversation object (existing or newly created).
|
|
102
|
+
*
|
|
103
|
+
* @example
|
|
104
|
+
* ```typescript
|
|
105
|
+
* const conversation = await api.conversations.getOrCreateConversation({
|
|
106
|
+
* workspaceId: 123,
|
|
107
|
+
* userIds: [101, 202, 303],
|
|
108
|
+
* })
|
|
109
|
+
* ```
|
|
110
|
+
*/
|
|
111
|
+
getOrCreateConversation(args) {
|
|
112
|
+
return this.simple('GET', 'get_or_create', { ...args, id: resolveCreateId(args.id) }, this.conversationSchema);
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Updates a conversation's title.
|
|
116
|
+
*
|
|
117
|
+
* @param args - The arguments for updating a conversation.
|
|
118
|
+
* @param args.id - The conversation ID.
|
|
119
|
+
* @param args.title - The new title for the conversation.
|
|
120
|
+
* @param args.archived - Optional flag to archive/unarchive the conversation.
|
|
121
|
+
* @returns The updated conversation object.
|
|
122
|
+
*
|
|
123
|
+
* @example
|
|
124
|
+
* ```typescript
|
|
125
|
+
* const conversation = await api.conversations.updateConversation({
|
|
126
|
+
* id: '7YpL3oZ4kZ9vP7Q1tR2sX42',
|
|
127
|
+
* title: 'New Title',
|
|
128
|
+
* })
|
|
129
|
+
* ```
|
|
130
|
+
*/
|
|
131
|
+
updateConversation(args) {
|
|
132
|
+
const params = { id: args.id, title: args.title };
|
|
133
|
+
if (args.archived !== undefined)
|
|
134
|
+
params.archived = args.archived;
|
|
135
|
+
return this.simple('POST', 'update', params, this.conversationSchema);
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Archives a conversation.
|
|
139
|
+
*
|
|
140
|
+
* @param id - The conversation ID.
|
|
141
|
+
* @returns The updated conversation object.
|
|
142
|
+
*/
|
|
143
|
+
archiveConversation(id) {
|
|
144
|
+
return this.simple('POST', 'archive', { id }, this.conversationSchema);
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Unarchives a conversation.
|
|
148
|
+
*
|
|
149
|
+
* @param id - The conversation ID.
|
|
150
|
+
* @returns The updated conversation object.
|
|
151
|
+
*/
|
|
152
|
+
unarchiveConversation(id) {
|
|
153
|
+
return this.simple('POST', 'unarchive', { id }, this.conversationSchema);
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Adds a user to a conversation.
|
|
157
|
+
*
|
|
158
|
+
* @param args - The arguments for adding a user.
|
|
159
|
+
* @param args.id - The conversation ID.
|
|
160
|
+
* @param args.userId - The user ID to add.
|
|
161
|
+
* @returns The updated conversation object.
|
|
162
|
+
*/
|
|
163
|
+
addUser(args) {
|
|
164
|
+
return this.simple('POST', 'add_user', { ...args }, this.conversationSchema);
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Adds multiple users to a conversation.
|
|
168
|
+
*
|
|
169
|
+
* @param args - The arguments for adding users.
|
|
170
|
+
* @param args.id - The conversation ID.
|
|
171
|
+
* @param args.userIds - Array of user IDs to add.
|
|
172
|
+
* @returns The updated conversation object.
|
|
173
|
+
*
|
|
174
|
+
* @example
|
|
175
|
+
* ```typescript
|
|
176
|
+
* await api.conversations.addUsers({ id: '7YpL3oZ4kZ9vP7Q1tR2sX42', userIds: [101, 202] })
|
|
177
|
+
* ```
|
|
178
|
+
*/
|
|
179
|
+
addUsers(args) {
|
|
180
|
+
return this.simple('POST', 'add_users', { ...args }, this.conversationSchema);
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Removes a user from a conversation.
|
|
184
|
+
*
|
|
185
|
+
* @param args - The arguments for removing a user.
|
|
186
|
+
* @param args.id - The conversation ID.
|
|
187
|
+
* @param args.userId - The user ID to remove.
|
|
188
|
+
* @returns The updated conversation object.
|
|
189
|
+
*/
|
|
190
|
+
removeUser(args) {
|
|
191
|
+
return this.simple('POST', 'remove_user', { ...args }, this.conversationSchema);
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Removes multiple users from a conversation.
|
|
195
|
+
*
|
|
196
|
+
* @param args - The arguments for removing users.
|
|
197
|
+
* @param args.id - The conversation ID.
|
|
198
|
+
* @param args.userIds - Array of user IDs to remove.
|
|
199
|
+
* @returns The updated conversation object.
|
|
200
|
+
*/
|
|
201
|
+
removeUsers(args) {
|
|
202
|
+
return this.simple('POST', 'remove_users', { ...args }, this.conversationSchema);
|
|
203
|
+
}
|
|
204
|
+
/**
|
|
205
|
+
* Marks a conversation as read.
|
|
206
|
+
*
|
|
207
|
+
* @param args - The arguments for marking as read.
|
|
208
|
+
* @param args.id - The conversation ID.
|
|
209
|
+
* @param args.objIndex - Optional index of the message to mark as last read.
|
|
210
|
+
* @param args.messageId - Optional message ID to mark as last read.
|
|
211
|
+
*/
|
|
212
|
+
markRead(args) {
|
|
213
|
+
return this.simple('POST', 'mark_read', { ...args }, StatusOkSchema);
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* Marks a conversation as unread.
|
|
217
|
+
*
|
|
218
|
+
* @param args - The arguments for marking as unread.
|
|
219
|
+
* @param args.id - The conversation ID.
|
|
220
|
+
* @param args.objIndex - Optional index of the message to mark as last unread.
|
|
221
|
+
* @param args.messageId - Optional message ID to mark as last unread.
|
|
222
|
+
*/
|
|
223
|
+
markUnread(args) {
|
|
224
|
+
return this.simple('POST', 'mark_unread', { ...args }, StatusOkSchema);
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* Returns unread conversations for a workspace, paired with the unread
|
|
228
|
+
* version counter.
|
|
229
|
+
*
|
|
230
|
+
* @param workspaceId - The workspace ID.
|
|
231
|
+
* @returns Object containing the array of unread conversation references and a version counter.
|
|
232
|
+
*/
|
|
233
|
+
getUnread(workspaceId) {
|
|
234
|
+
return this.simple('GET', 'get_unread', { workspaceId }, GetUnreadResponseSchema);
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Clears all unread conversations for a workspace.
|
|
238
|
+
*
|
|
239
|
+
* @param workspaceId - The workspace ID.
|
|
240
|
+
*/
|
|
241
|
+
clearUnread(workspaceId) {
|
|
242
|
+
return this.simple('GET', 'clear_unread', { workspaceId }, StatusOkSchema);
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* Mutes a conversation for a specified number of minutes.
|
|
246
|
+
* The user will receive no notifications from this conversation during that period.
|
|
247
|
+
*
|
|
248
|
+
* @param args - The arguments for muting a conversation.
|
|
249
|
+
* @param args.id - The conversation ID.
|
|
250
|
+
* @param args.minutes - Number of minutes to mute the conversation.
|
|
251
|
+
* @returns The updated conversation object.
|
|
252
|
+
*
|
|
253
|
+
* @example
|
|
254
|
+
* ```typescript
|
|
255
|
+
* const conversation = await api.conversations.muteConversation({ id: '7YpL3oZ4kZ9vP7Q1tR2sX42', minutes: 30 })
|
|
256
|
+
* ```
|
|
257
|
+
*/
|
|
258
|
+
muteConversation(args) {
|
|
259
|
+
return this.simple('GET', 'mute', { ...args }, this.conversationSchema);
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* Unmutes a conversation.
|
|
263
|
+
*
|
|
264
|
+
* @param id - The conversation ID.
|
|
265
|
+
* @returns The updated conversation object.
|
|
266
|
+
*/
|
|
267
|
+
unmuteConversation(id) {
|
|
268
|
+
return this.simple('GET', 'unmute', { id }, this.conversationSchema);
|
|
269
|
+
}
|
|
270
|
+
simple(httpMethod, suffix, params, schema) {
|
|
271
|
+
return request({
|
|
272
|
+
httpMethod,
|
|
273
|
+
baseUri: this.getBaseUri(),
|
|
274
|
+
relativePath: `${ENDPOINT_CONVERSATIONS}/${suffix}`,
|
|
275
|
+
apiToken: this.apiToken,
|
|
276
|
+
payload: params,
|
|
277
|
+
headers: this.headers,
|
|
278
|
+
customFetch: this.customFetch,
|
|
279
|
+
}).then((response) => schema.parse(response.data));
|
|
280
|
+
}
|
|
281
|
+
}
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { ENDPOINT_GROUPS } from '../consts/endpoints.js';
|
|
3
|
+
import { request } from '../transport/http-client.js';
|
|
4
|
+
import { GroupSchema, StatusOkSchema } from '../types/entities.js';
|
|
5
|
+
import { resolveCreateId } from '../utils/uuidv7.js';
|
|
6
|
+
import { BaseClient } from './base-client.js';
|
|
7
|
+
export const GroupListSchema = z.array(GroupSchema);
|
|
8
|
+
/**
|
|
9
|
+
* Client for `/api/v1.0/groups/`. The broadcast markers `EVERYONE` /
|
|
10
|
+
* `EVERYONE_IN_THREAD` are NOT addressable through these endpoints — they
|
|
11
|
+
* only appear as members of `direct_group_mentions` / `groups` lists on
|
|
12
|
+
* thread/comment writes.
|
|
13
|
+
*
|
|
14
|
+
* `getone` / `update` / `remove` and the member-management ops all require
|
|
15
|
+
* `workspace_id` alongside the group `id`.
|
|
16
|
+
*/
|
|
17
|
+
export class GroupsClient extends BaseClient {
|
|
18
|
+
/**
|
|
19
|
+
* Gets all groups for a given workspace.
|
|
20
|
+
*
|
|
21
|
+
* @param workspaceId - The workspace ID.
|
|
22
|
+
* @returns An array of group objects.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```typescript
|
|
26
|
+
* const groups = await api.groups.getGroups(123)
|
|
27
|
+
* groups.forEach(g => console.log(g.name))
|
|
28
|
+
* ```
|
|
29
|
+
*/
|
|
30
|
+
getGroups(workspaceId) {
|
|
31
|
+
return request({
|
|
32
|
+
httpMethod: 'GET',
|
|
33
|
+
baseUri: this.getBaseUri(),
|
|
34
|
+
relativePath: `${ENDPOINT_GROUPS}/get`,
|
|
35
|
+
apiToken: this.apiToken,
|
|
36
|
+
payload: { workspaceId },
|
|
37
|
+
headers: this.headers,
|
|
38
|
+
customFetch: this.customFetch,
|
|
39
|
+
}).then((response) => GroupListSchema.parse(response.data));
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Gets a single group object by id. Requires `workspaceId`.
|
|
43
|
+
*
|
|
44
|
+
* @param args - The arguments for getting a group.
|
|
45
|
+
* @param args.id - The group ID.
|
|
46
|
+
* @param args.workspaceId - The workspace ID.
|
|
47
|
+
* @returns The group object.
|
|
48
|
+
*/
|
|
49
|
+
getGroup(args) {
|
|
50
|
+
return this.simple('GET', 'getone', { ...args }, GroupSchema);
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Creates a new group. `id` is auto-generated if not supplied.
|
|
54
|
+
*
|
|
55
|
+
* @param args - The arguments for creating a group.
|
|
56
|
+
* @param args.workspaceId - The workspace ID.
|
|
57
|
+
* @param args.name - The group name.
|
|
58
|
+
* @param args.id - Optional caller-supplied group ID (for optimistic-UI workflows).
|
|
59
|
+
* @param args.description - Optional group description.
|
|
60
|
+
* @param args.userIds - Optional array of user IDs to add to the group.
|
|
61
|
+
* @returns The created group object.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* ```typescript
|
|
65
|
+
* const group = await api.groups.createGroup({
|
|
66
|
+
* workspaceId: 123,
|
|
67
|
+
* name: 'Engineering Team',
|
|
68
|
+
* userIds: [1, 2, 3],
|
|
69
|
+
* })
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
72
|
+
createGroup(args) {
|
|
73
|
+
return this.simple('POST', 'add', { ...args, id: resolveCreateId(args.id) }, GroupSchema);
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Updates a group's properties. Requires `workspaceId`.
|
|
77
|
+
*
|
|
78
|
+
* @param args - The arguments for updating a group.
|
|
79
|
+
* @param args.id - The group ID.
|
|
80
|
+
* @param args.workspaceId - The workspace ID.
|
|
81
|
+
* @param args.name - Optional new group name.
|
|
82
|
+
* @param args.description - Optional new group description.
|
|
83
|
+
* @returns The updated group object.
|
|
84
|
+
*/
|
|
85
|
+
updateGroup(args) {
|
|
86
|
+
return this.simple('POST', 'update', { ...args }, GroupSchema);
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Permanently deletes a group. Requires `workspaceId`.
|
|
90
|
+
*
|
|
91
|
+
* @param args - The arguments for deleting a group.
|
|
92
|
+
* @param args.id - The group ID.
|
|
93
|
+
* @param args.workspaceId - The workspace ID.
|
|
94
|
+
*/
|
|
95
|
+
deleteGroup(args) {
|
|
96
|
+
return this.simple('POST', 'remove', { ...args }, StatusOkSchema);
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Adds a user to a group.
|
|
100
|
+
*
|
|
101
|
+
* @param args - The arguments for adding a user.
|
|
102
|
+
* @param args.id - The group ID.
|
|
103
|
+
* @param args.workspaceId - The workspace ID.
|
|
104
|
+
* @param args.userId - The user ID to add.
|
|
105
|
+
*/
|
|
106
|
+
addUser(args) {
|
|
107
|
+
// The backend only exposes the plural `add_users` endpoint (routed via
|
|
108
|
+
// Todoist); there is no `add_user`. Delegate to `addUsers` so the wire
|
|
109
|
+
// contract lives in one place.
|
|
110
|
+
const { userId, ...rest } = args;
|
|
111
|
+
return this.addUsers({ ...rest, userIds: [userId] });
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Adds multiple users to a group.
|
|
115
|
+
*
|
|
116
|
+
* @param args - The arguments for adding users.
|
|
117
|
+
* @param args.id - The group ID.
|
|
118
|
+
* @param args.workspaceId - The workspace ID.
|
|
119
|
+
* @param args.userIds - Array of user IDs to add.
|
|
120
|
+
*
|
|
121
|
+
* @example
|
|
122
|
+
* ```typescript
|
|
123
|
+
* await api.groups.addUsers({
|
|
124
|
+
* id: '7YpL3oZ4kZ9vP7Q1tR2sX45',
|
|
125
|
+
* workspaceId: 123,
|
|
126
|
+
* userIds: [101, 202, 303],
|
|
127
|
+
* })
|
|
128
|
+
* ```
|
|
129
|
+
*/
|
|
130
|
+
addUsers(args) {
|
|
131
|
+
return this.simple('POST', 'add_users', { ...args }, StatusOkSchema);
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Removes a user from a group.
|
|
135
|
+
*
|
|
136
|
+
* @param args - The arguments for removing a user.
|
|
137
|
+
* @param args.id - The group ID.
|
|
138
|
+
* @param args.workspaceId - The workspace ID.
|
|
139
|
+
* @param args.userId - The user ID to remove.
|
|
140
|
+
*/
|
|
141
|
+
removeUser(args) {
|
|
142
|
+
// The backend only exposes the plural `remove_users` endpoint (routed
|
|
143
|
+
// via Todoist); there is no `remove_user`. Delegate to `removeUsers` so
|
|
144
|
+
// the wire contract lives in one place.
|
|
145
|
+
const { userId, ...rest } = args;
|
|
146
|
+
return this.removeUsers({ ...rest, userIds: [userId] });
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Removes multiple users from a group.
|
|
150
|
+
*
|
|
151
|
+
* @param args - The arguments for removing users.
|
|
152
|
+
* @param args.id - The group ID.
|
|
153
|
+
* @param args.workspaceId - The workspace ID.
|
|
154
|
+
* @param args.userIds - Array of user IDs to remove.
|
|
155
|
+
*/
|
|
156
|
+
removeUsers(args) {
|
|
157
|
+
return this.simple('POST', 'remove_users', { ...args }, StatusOkSchema);
|
|
158
|
+
}
|
|
159
|
+
simple(httpMethod, suffix, params, schema) {
|
|
160
|
+
return request({
|
|
161
|
+
httpMethod,
|
|
162
|
+
baseUri: this.getBaseUri(),
|
|
163
|
+
relativePath: `${ENDPOINT_GROUPS}/${suffix}`,
|
|
164
|
+
apiToken: this.apiToken,
|
|
165
|
+
payload: params,
|
|
166
|
+
headers: this.headers,
|
|
167
|
+
customFetch: this.customFetch,
|
|
168
|
+
}).then((response) => schema.parse(response.data));
|
|
169
|
+
}
|
|
170
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { ENDPOINT_HOOKS } from '../consts/endpoints.js';
|
|
2
|
+
import { request } from '../transport/http-client.js';
|
|
3
|
+
import { HookSubscribeResponseSchema, StatusOkSchema, } from '../types/entities.js';
|
|
4
|
+
import { BaseClient } from './base-client.js';
|
|
5
|
+
/**
|
|
6
|
+
* Client for `/api/v1.0/hooks/`. REST hooks require Todoist OAuth bearer tokens
|
|
7
|
+
* that include Comms audience; session tokens are rejected by the backend.
|
|
8
|
+
*/
|
|
9
|
+
export class HooksClient extends BaseClient {
|
|
10
|
+
/**
|
|
11
|
+
* Subscribes the current OAuth app to a REST hook event.
|
|
12
|
+
*
|
|
13
|
+
* @param args - The hook subscription parameters.
|
|
14
|
+
* @param args.targetUrl - HTTPS endpoint, up to 150 characters, that will receive webhook POSTs.
|
|
15
|
+
* @param args.event - Event name to subscribe to.
|
|
16
|
+
* @param args.workspaceId - Optional workspace filter.
|
|
17
|
+
* @param args.channelId - Optional channel filter.
|
|
18
|
+
* @param args.threadId - Optional thread filter.
|
|
19
|
+
* @param args.conversationId - Optional conversation filter for message events.
|
|
20
|
+
* @returns The `{ status: 'ok', id }` response for the subscription.
|
|
21
|
+
*/
|
|
22
|
+
subscribe(args) {
|
|
23
|
+
return request({
|
|
24
|
+
httpMethod: 'POST',
|
|
25
|
+
baseUri: this.getBaseUri(),
|
|
26
|
+
relativePath: `${ENDPOINT_HOOKS}/subscribe`,
|
|
27
|
+
apiToken: this.apiToken,
|
|
28
|
+
payload: args,
|
|
29
|
+
headers: this.headers,
|
|
30
|
+
customFetch: this.customFetch,
|
|
31
|
+
}).then((response) => HookSubscribeResponseSchema.parse(response.data));
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Unsubscribes all hooks with the target URL for the current OAuth app.
|
|
35
|
+
*
|
|
36
|
+
* @param args - The hook unsubscribe parameters.
|
|
37
|
+
* @param args.targetUrl - Target URL to remove.
|
|
38
|
+
*/
|
|
39
|
+
unsubscribe(args) {
|
|
40
|
+
return request({
|
|
41
|
+
httpMethod: 'POST',
|
|
42
|
+
baseUri: this.getBaseUri(),
|
|
43
|
+
relativePath: `${ENDPOINT_HOOKS}/unsubscribe`,
|
|
44
|
+
apiToken: this.apiToken,
|
|
45
|
+
payload: args,
|
|
46
|
+
headers: this.headers,
|
|
47
|
+
customFetch: this.customFetch,
|
|
48
|
+
}).then((response) => StatusOkSchema.parse(response.data));
|
|
49
|
+
}
|
|
50
|
+
}
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { ENDPOINT_INBOX } from '../consts/endpoints.js';
|
|
3
|
+
import { request } from '../transport/http-client.js';
|
|
4
|
+
import { createInboxThreadSchema, InboxThreadSchema } from '../types/entities.js';
|
|
5
|
+
import { BaseClient } from './base-client.js';
|
|
6
|
+
export const InboxThreadListSchema = z.array(InboxThreadSchema);
|
|
7
|
+
/** Client for `/api/v1.0/inbox/`. */
|
|
8
|
+
export class InboxClient extends BaseClient {
|
|
9
|
+
constructor() {
|
|
10
|
+
super(...arguments);
|
|
11
|
+
this.linkBaseUrl = this.getLinkBaseUrl();
|
|
12
|
+
// Reuse the shared singletons when no custom base is configured.
|
|
13
|
+
this.inboxThreadSchema = this.linkBaseUrl
|
|
14
|
+
? createInboxThreadSchema(this.linkBaseUrl)
|
|
15
|
+
: InboxThreadSchema;
|
|
16
|
+
this.inboxThreadListSchema = this.linkBaseUrl
|
|
17
|
+
? z.array(this.inboxThreadSchema)
|
|
18
|
+
: InboxThreadListSchema;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Gets inbox items (threads).
|
|
22
|
+
*
|
|
23
|
+
* @param args - The arguments for getting inbox.
|
|
24
|
+
* @param args.workspaceId - The workspace ID.
|
|
25
|
+
* @param args.newerThan - Optional date to get items newer than.
|
|
26
|
+
* @param args.olderThan - Optional date to get items older than.
|
|
27
|
+
* @param args.limit - Optional limit on number of items returned.
|
|
28
|
+
* @param args.cursor - Optional cursor for pagination.
|
|
29
|
+
* @param args.archiveFilter - Optional filter: 'active' (default), 'archived', or 'all'.
|
|
30
|
+
* @returns Inbox threads.
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* ```typescript
|
|
34
|
+
* const inbox = await api.inbox.getInbox({
|
|
35
|
+
* workspaceId: 123,
|
|
36
|
+
* newerThan: new Date('2024-01-01'),
|
|
37
|
+
* })
|
|
38
|
+
*
|
|
39
|
+
* // Include archived (done) items alongside active ones
|
|
40
|
+
* const allInbox = await api.inbox.getInbox({
|
|
41
|
+
* workspaceId: 123,
|
|
42
|
+
* archiveFilter: 'all',
|
|
43
|
+
* })
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
getInbox(args) {
|
|
47
|
+
const params = { workspace_id: args.workspaceId };
|
|
48
|
+
if (args.newerThan)
|
|
49
|
+
params.newer_than_ts = Math.floor(args.newerThan.getTime() / 1000);
|
|
50
|
+
if (args.olderThan)
|
|
51
|
+
params.older_than_ts = Math.floor(args.olderThan.getTime() / 1000);
|
|
52
|
+
if (args.limit)
|
|
53
|
+
params.limit = args.limit;
|
|
54
|
+
if (args.cursor)
|
|
55
|
+
params.cursor = args.cursor;
|
|
56
|
+
if (args.archiveFilter)
|
|
57
|
+
params.archive_filter = args.archiveFilter;
|
|
58
|
+
return request({
|
|
59
|
+
httpMethod: 'GET',
|
|
60
|
+
baseUri: this.getBaseUri(),
|
|
61
|
+
relativePath: `${ENDPOINT_INBOX}/get`,
|
|
62
|
+
apiToken: this.apiToken,
|
|
63
|
+
payload: params,
|
|
64
|
+
headers: this.headers,
|
|
65
|
+
customFetch: this.customFetch,
|
|
66
|
+
}).then((response) => this.inboxThreadListSchema.parse(response.data));
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Gets unread count for inbox.
|
|
70
|
+
*
|
|
71
|
+
* @param workspaceId - The workspace ID.
|
|
72
|
+
* @returns The unread count.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```typescript
|
|
76
|
+
* const count = await api.inbox.getCount(123)
|
|
77
|
+
* console.log(`Unread items: ${count}`)
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
80
|
+
getCount(workspaceId) {
|
|
81
|
+
return request({
|
|
82
|
+
httpMethod: 'GET',
|
|
83
|
+
baseUri: this.getBaseUri(),
|
|
84
|
+
relativePath: `${ENDPOINT_INBOX}/get_count`,
|
|
85
|
+
apiToken: this.apiToken,
|
|
86
|
+
payload: { workspace_id: workspaceId },
|
|
87
|
+
headers: this.headers,
|
|
88
|
+
customFetch: this.customFetch,
|
|
89
|
+
}).then((response) => response.data.data);
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Archives a thread in the inbox.
|
|
93
|
+
*
|
|
94
|
+
* @param id - The thread ID.
|
|
95
|
+
*
|
|
96
|
+
* @example
|
|
97
|
+
* ```typescript
|
|
98
|
+
* await api.inbox.archiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
|
|
99
|
+
* ```
|
|
100
|
+
*/
|
|
101
|
+
archiveThread(id) {
|
|
102
|
+
return request({
|
|
103
|
+
httpMethod: 'POST',
|
|
104
|
+
baseUri: this.getBaseUri(),
|
|
105
|
+
relativePath: `${ENDPOINT_INBOX}/archive`,
|
|
106
|
+
apiToken: this.apiToken,
|
|
107
|
+
payload: { id },
|
|
108
|
+
headers: this.headers,
|
|
109
|
+
customFetch: this.customFetch,
|
|
110
|
+
}).then(() => undefined);
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Unarchives a thread in the inbox.
|
|
114
|
+
*
|
|
115
|
+
* @param id - The thread ID.
|
|
116
|
+
*
|
|
117
|
+
* @example
|
|
118
|
+
* ```typescript
|
|
119
|
+
* await api.inbox.unarchiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
|
|
120
|
+
* ```
|
|
121
|
+
*/
|
|
122
|
+
unarchiveThread(id) {
|
|
123
|
+
return request({
|
|
124
|
+
httpMethod: 'POST',
|
|
125
|
+
baseUri: this.getBaseUri(),
|
|
126
|
+
relativePath: `${ENDPOINT_INBOX}/unarchive`,
|
|
127
|
+
apiToken: this.apiToken,
|
|
128
|
+
payload: { id },
|
|
129
|
+
headers: this.headers,
|
|
130
|
+
customFetch: this.customFetch,
|
|
131
|
+
}).then(() => undefined);
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Marks all inbox items as read in a workspace.
|
|
135
|
+
*
|
|
136
|
+
* @param workspaceId - The workspace ID.
|
|
137
|
+
*
|
|
138
|
+
* @example
|
|
139
|
+
* ```typescript
|
|
140
|
+
* await api.inbox.markAllRead(123)
|
|
141
|
+
* ```
|
|
142
|
+
*/
|
|
143
|
+
markAllRead(workspaceId) {
|
|
144
|
+
return request({
|
|
145
|
+
httpMethod: 'POST',
|
|
146
|
+
baseUri: this.getBaseUri(),
|
|
147
|
+
relativePath: `${ENDPOINT_INBOX}/mark_all_read`,
|
|
148
|
+
apiToken: this.apiToken,
|
|
149
|
+
payload: { workspace_id: workspaceId },
|
|
150
|
+
headers: this.headers,
|
|
151
|
+
customFetch: this.customFetch,
|
|
152
|
+
}).then(() => undefined);
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Archives all inbox items in a workspace.
|
|
156
|
+
*
|
|
157
|
+
* @param args - The arguments for archiving all.
|
|
158
|
+
* @param args.workspaceId - The workspace ID.
|
|
159
|
+
* @param args.channelIds - Optional array of channel IDs to filter by.
|
|
160
|
+
* @param args.olderThan - Optional date to filter items older than.
|
|
161
|
+
*
|
|
162
|
+
* @example
|
|
163
|
+
* ```typescript
|
|
164
|
+
* await api.inbox.archiveAll({
|
|
165
|
+
* workspaceId: 123,
|
|
166
|
+
* olderThan: new Date('2024-01-01'),
|
|
167
|
+
* })
|
|
168
|
+
* ```
|
|
169
|
+
*/
|
|
170
|
+
archiveAll(args) {
|
|
171
|
+
const params = { workspace_id: args.workspaceId };
|
|
172
|
+
if (args.channelIds)
|
|
173
|
+
params.channel_ids = args.channelIds;
|
|
174
|
+
if (args.olderThan)
|
|
175
|
+
params.older_than_ts = Math.floor(args.olderThan.getTime() / 1000);
|
|
176
|
+
return request({
|
|
177
|
+
httpMethod: 'POST',
|
|
178
|
+
baseUri: this.getBaseUri(),
|
|
179
|
+
relativePath: `${ENDPOINT_INBOX}/archive_all`,
|
|
180
|
+
apiToken: this.apiToken,
|
|
181
|
+
payload: params,
|
|
182
|
+
headers: this.headers,
|
|
183
|
+
customFetch: this.customFetch,
|
|
184
|
+
}).then(() => undefined);
|
|
185
|
+
}
|
|
186
|
+
}
|