@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.
Files changed (93) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +182 -39
  3. package/dist/esm/authentication.js +247 -0
  4. package/dist/esm/clients/add-comment-helper.js +41 -0
  5. package/dist/esm/clients/attachments-client.js +99 -0
  6. package/dist/esm/clients/base-client.js +30 -0
  7. package/dist/esm/clients/channels-client.js +209 -0
  8. package/dist/esm/clients/comments-client.js +177 -0
  9. package/dist/esm/clients/conversation-messages-client.js +167 -0
  10. package/dist/esm/clients/conversations-client.js +281 -0
  11. package/dist/esm/clients/groups-client.js +170 -0
  12. package/dist/esm/clients/hooks-client.js +50 -0
  13. package/dist/esm/clients/inbox-client.js +186 -0
  14. package/dist/esm/clients/notify-audience.js +43 -0
  15. package/dist/esm/clients/reactions-client.js +96 -0
  16. package/dist/esm/clients/search-client.js +140 -0
  17. package/dist/esm/clients/threads-client.js +363 -0
  18. package/dist/esm/clients/users-client.js +368 -0
  19. package/dist/esm/clients/workspace-users-client.js +299 -0
  20. package/dist/esm/clients/workspaces-client.js +177 -0
  21. package/dist/esm/comms-api.js +67 -0
  22. package/dist/esm/consts/endpoints.js +31 -0
  23. package/dist/esm/index.js +20 -0
  24. package/dist/esm/migration.js +92 -0
  25. package/dist/esm/testUtils/msw-handlers.js +45 -0
  26. package/dist/esm/testUtils/msw-setup.js +32 -0
  27. package/dist/esm/testUtils/obsidian-fetch-adapter.js +50 -0
  28. package/dist/esm/testUtils/test-defaults.js +103 -0
  29. package/dist/esm/transport/fetch-with-retry.js +240 -0
  30. package/dist/esm/transport/http-client.js +53 -0
  31. package/dist/esm/transport/http-dispatcher.js +149 -0
  32. package/dist/esm/types/api-version.js +5 -0
  33. package/dist/esm/types/entities.js +515 -0
  34. package/dist/esm/types/enums.js +34 -0
  35. package/dist/esm/types/errors.js +82 -0
  36. package/dist/esm/types/http.js +1 -0
  37. package/dist/esm/types/index.js +6 -0
  38. package/dist/esm/types/requests.js +184 -0
  39. package/dist/esm/utils/case-conversion.js +47 -0
  40. package/dist/esm/utils/conversation-title.js +110 -0
  41. package/dist/esm/utils/headers.js +29 -0
  42. package/dist/esm/utils/index.js +5 -0
  43. package/dist/esm/utils/multipart-upload.js +198 -0
  44. package/dist/esm/utils/reply-recipients.js +111 -0
  45. package/dist/esm/utils/timestamp-conversion.js +54 -0
  46. package/dist/esm/utils/url-helpers.js +202 -0
  47. package/dist/esm/utils/uuidv7.js +170 -0
  48. package/dist/types/authentication.d.ts +183 -0
  49. package/dist/types/clients/add-comment-helper.d.ts +32 -0
  50. package/dist/types/clients/attachments-client.d.ts +55 -0
  51. package/dist/types/clients/base-client.d.ts +37 -0
  52. package/dist/types/clients/channels-client.d.ts +211 -0
  53. package/dist/types/clients/comments-client.d.ts +228 -0
  54. package/dist/types/clients/conversation-messages-client.d.ts +201 -0
  55. package/dist/types/clients/conversations-client.d.ts +366 -0
  56. package/dist/types/clients/groups-client.d.ts +148 -0
  57. package/dist/types/clients/hooks-client.d.ts +29 -0
  58. package/dist/types/clients/inbox-client.d.ts +478 -0
  59. package/dist/types/clients/notify-audience.d.ts +22 -0
  60. package/dist/types/clients/reactions-client.d.ts +57 -0
  61. package/dist/types/clients/search-client.d.ts +71 -0
  62. package/dist/types/clients/threads-client.d.ts +547 -0
  63. package/dist/types/clients/users-client.d.ts +280 -0
  64. package/dist/types/clients/workspace-users-client.d.ts +172 -0
  65. package/dist/types/clients/workspaces-client.d.ts +154 -0
  66. package/dist/types/comms-api.d.ts +73 -0
  67. package/dist/types/consts/endpoints.d.ts +27 -0
  68. package/dist/types/index.d.ts +21 -0
  69. package/dist/types/migration.d.ts +78 -0
  70. package/dist/types/testUtils/msw-handlers.d.ts +28 -0
  71. package/dist/types/testUtils/msw-setup.d.ts +1 -0
  72. package/dist/types/testUtils/obsidian-fetch-adapter.d.ts +29 -0
  73. package/dist/types/testUtils/test-defaults.d.ts +17 -0
  74. package/dist/types/transport/fetch-with-retry.d.ts +4 -0
  75. package/dist/types/transport/http-client.d.ts +14 -0
  76. package/dist/types/transport/http-dispatcher.d.ts +46 -0
  77. package/dist/types/types/api-version.d.ts +6 -0
  78. package/dist/types/types/entities.d.ts +3081 -0
  79. package/dist/types/types/enums.d.ts +55 -0
  80. package/dist/types/types/errors.d.ts +57 -0
  81. package/dist/types/types/http.d.ts +60 -0
  82. package/dist/types/types/index.d.ts +6 -0
  83. package/dist/types/types/requests.d.ts +604 -0
  84. package/dist/types/utils/case-conversion.d.ts +8 -0
  85. package/dist/types/utils/conversation-title.d.ts +84 -0
  86. package/dist/types/utils/headers.d.ts +13 -0
  87. package/dist/types/utils/index.d.ts +6 -0
  88. package/dist/types/utils/multipart-upload.d.ts +59 -0
  89. package/dist/types/utils/reply-recipients.d.ts +60 -0
  90. package/dist/types/utils/timestamp-conversion.d.ts +13 -0
  91. package/dist/types/utils/url-helpers.d.ts +129 -0
  92. package/dist/types/utils/uuidv7.d.ts +42 -0
  93. package/package.json +80 -8
@@ -0,0 +1,280 @@
1
+ import { type User } from '../types/entities.js';
2
+ import type { SetStatusArgs, UpdateUserArgs } from '../types/requests.js';
3
+ import { BaseClient } from './base-client.js';
4
+ type EmailExistsResponse = {
5
+ exists: boolean;
6
+ verified: boolean;
7
+ };
8
+ type MfaChallengeResponse = {
9
+ mfaToken: string;
10
+ };
11
+ type LoginWithGoogleArgs = {
12
+ idToken: string;
13
+ nonce: string;
14
+ timezone?: string;
15
+ lang?: string;
16
+ mfaToken?: string;
17
+ };
18
+ type RegisterArgs = {
19
+ name: string;
20
+ email: string;
21
+ password: string;
22
+ lang?: string;
23
+ acceptTerms?: boolean;
24
+ };
25
+ type LoginArgs = {
26
+ email: string;
27
+ password: string;
28
+ setSessionCookie?: boolean;
29
+ };
30
+ type MfaChallengeArgs = {
31
+ challengeId: string;
32
+ factor: string;
33
+ methodType: string;
34
+ };
35
+ /**
36
+ * Client for the `/api/v1.0/users/` endpoints. Authentication flows through
37
+ * Todoist-ID; `register` / `login` / `loginWithGoogle` / `loginWithToken` /
38
+ * `loginWithTodoist` are the available entry points.
39
+ */
40
+ export declare class UsersClient extends BaseClient {
41
+ /**
42
+ * Registers a new user via the Todoist-ID bridge.
43
+ *
44
+ * @param args - Registration arguments.
45
+ * @param args.name - The new user's full name.
46
+ * @param args.email - The new user's email.
47
+ * @param args.password - The new user's password.
48
+ * @param args.lang - Optional preferred language.
49
+ * @param args.acceptTerms - Optional flag confirming the user accepts the terms of service.
50
+ * @returns The newly registered user object.
51
+ */
52
+ register(args: RegisterArgs): Promise<User>;
53
+ /**
54
+ * Logs in an existing user.
55
+ *
56
+ * @param args - Login credentials.
57
+ * @param args.email - The user's email.
58
+ * @param args.password - The user's password.
59
+ * @param args.setSessionCookie - Optional flag to set a session cookie (default: true).
60
+ * @returns The authenticated user object.
61
+ *
62
+ * @example
63
+ * ```typescript
64
+ * const user = await api.users.login({
65
+ * email: 'user@example.com',
66
+ * password: 'secret',
67
+ * })
68
+ * ```
69
+ */
70
+ login(args: LoginArgs): Promise<User>;
71
+ /**
72
+ * Logs in using a valid token (sent via Authorization header). The SDK
73
+ * client is already configured with the token, so no args are needed.
74
+ *
75
+ * @returns The authenticated user object.
76
+ */
77
+ loginWithToken(): Promise<User>;
78
+ /**
79
+ * Exchanges the browser's Todoist web-session cookie for a Comms session.
80
+ * Only useful when running in a browser context on the shared Todoist
81
+ * registrable domain — the cookie is sent automatically by the browser.
82
+ *
83
+ * @returns The authenticated user object.
84
+ */
85
+ loginWithTodoist(): Promise<User>;
86
+ /**
87
+ * Logs in (and auto-signs-up) via a Google ID token.
88
+ *
89
+ * @param args - Google login arguments.
90
+ * @param args.idToken - The Google ID token.
91
+ * @param args.nonce - The nonce that was sent to Google.
92
+ * @param args.timezone - Optional user timezone.
93
+ * @param args.lang - Optional preferred language.
94
+ * @param args.mfaToken - Optional MFA token from a prior `mfaChallenge` response.
95
+ * @returns The authenticated user object.
96
+ */
97
+ loginWithGoogle(args: LoginWithGoogleArgs): Promise<User>;
98
+ /**
99
+ * Completes an MFA challenge issued by `loginWithGoogle` (returns an MFA
100
+ * token to pass back to `loginWithGoogle.mfaToken`).
101
+ *
102
+ * @param args - MFA challenge arguments.
103
+ * @param args.challengeId - The challenge ID from the prior login attempt.
104
+ * @param args.factor - The MFA factor identifier.
105
+ * @param args.methodType - The MFA method type.
106
+ * @returns The MFA token to forward to `loginWithGoogle`.
107
+ */
108
+ mfaChallenge(args: MfaChallengeArgs): Promise<MfaChallengeResponse>;
109
+ /** Logs out the current user and clears the session cookie. */
110
+ logout(): Promise<void>;
111
+ /**
112
+ * Gets the user associated with the current access token.
113
+ *
114
+ * @returns The authenticated user's information.
115
+ *
116
+ * @example
117
+ * ```typescript
118
+ * const user = await api.users.getSessionUser()
119
+ * console.log(user.fullName, user.email)
120
+ * ```
121
+ */
122
+ getSessionUser(): Promise<User>;
123
+ /**
124
+ * Fetches a single user. Defaults to the session user when no `id` is
125
+ * passed. Cross-workspace lookups require that the caller and the target
126
+ * share a workspace.
127
+ *
128
+ * @param args - Optional lookup arguments.
129
+ * @param args.id - The user ID. Defaults to the session user.
130
+ * @param args.workspaceId - Optional workspace ID for cross-workspace lookups.
131
+ * @param args.asList - Optional flag controlling list-style response.
132
+ * @returns The user object.
133
+ */
134
+ getUser(args?: {
135
+ id?: number;
136
+ workspaceId?: number;
137
+ asList?: boolean;
138
+ }): Promise<User>;
139
+ /**
140
+ * Looks up a user by their email address.
141
+ *
142
+ * @param email - The email to look up.
143
+ * @returns The user object.
144
+ */
145
+ getUserByEmail(email: string): Promise<User>;
146
+ /**
147
+ * Updates the logged-in user's profile. Most fields are proxied to
148
+ * Todoist (full name, password, language, timezone, etc.).
149
+ *
150
+ * @param args - The user properties to update.
151
+ * @returns The updated user object.
152
+ *
153
+ * @example
154
+ * ```typescript
155
+ * const user = await api.users.update({
156
+ * name: 'John Doe',
157
+ * timezone: 'America/New_York',
158
+ * })
159
+ * ```
160
+ */
161
+ update(args: UpdateUserArgs): Promise<User>;
162
+ /**
163
+ * Creates or partially updates the session user's shared status.
164
+ * The status belongs to the Todoist account, so it is shared with Todoist.
165
+ * Requires the `user:write` scope.
166
+ *
167
+ * @param args - The status to set.
168
+ * @param args.message - 1 to 80 characters once trimmed. Required when creating a status.
169
+ * @param args.emoji - Emoji to set; null removes it, omission preserves it.
170
+ * @param args.activeUntil - Future expiry (`Date` or ISO string); null removes it, omission preserves it.
171
+ * @param args.effects - Merge supplied effects. Omission or {} preserves effects; null clears all.
172
+ * An individual effect set to null is removed; {} preserves its configuration or enables defaults.
173
+ * @returns The updated user object.
174
+ *
175
+ * @example
176
+ * ```typescript
177
+ * await api.users.setStatus({
178
+ * message: 'Deep work',
179
+ * emoji: '🎯',
180
+ * activeUntil: new Date(Date.now() + 2 * 60 * 60 * 1000),
181
+ * effects: { pauseNotifications: {} },
182
+ * })
183
+ * ```
184
+ */
185
+ setStatus(args: SetStatusArgs): Promise<User>;
186
+ /**
187
+ * Clears the session user's shared status. Requires the `user:write` scope.
188
+ *
189
+ * @returns The updated user object.
190
+ */
191
+ clearStatus(): Promise<User>;
192
+ /**
193
+ * Updates the user's password.
194
+ *
195
+ * @param args - Password update arguments.
196
+ * @param args.newPassword - The new password.
197
+ * @param args.currentPassword - The user's existing password. Optional — sent for
198
+ * re-authentication when the account has a password set.
199
+ * @returns The updated user object.
200
+ */
201
+ updatePassword(args: {
202
+ newPassword: string;
203
+ currentPassword?: string;
204
+ }): Promise<User>;
205
+ /**
206
+ * Removes the user's avatar.
207
+ *
208
+ * @returns The updated user object.
209
+ */
210
+ removeAvatar(): Promise<User>;
211
+ /**
212
+ * Invalidates the current API token and returns the user with a fresh
213
+ * token.
214
+ *
215
+ * @returns The user object with the new token.
216
+ *
217
+ * @example
218
+ * ```typescript
219
+ * const user = await api.users.invalidateToken()
220
+ * console.log('New token:', user.token)
221
+ * ```
222
+ */
223
+ invalidateToken(): Promise<User>;
224
+ /**
225
+ * Validates that an arbitrary token is still active. Note this is sent
226
+ * as a GET — the token is read from the query string, not the
227
+ * Authorization header.
228
+ *
229
+ * @param token - The token to validate.
230
+ */
231
+ validateToken(token: string): Promise<void>;
232
+ /**
233
+ * Marks the user as active on a workspace (presence beacon).
234
+ *
235
+ * @param args - Heartbeat arguments.
236
+ * @param args.workspaceId - The workspace ID.
237
+ * @param args.platform - The platform identifier (e.g., 'mobile', 'desktop', 'api').
238
+ *
239
+ * @example
240
+ * ```typescript
241
+ * await api.users.heartbeat({ workspaceId: 123, platform: 'api' })
242
+ * ```
243
+ */
244
+ heartbeat(args: {
245
+ workspaceId: number;
246
+ platform: string;
247
+ }): Promise<void>;
248
+ /**
249
+ * Resets the user's presence for a workspace (marks the user as inactive).
250
+ *
251
+ * @param workspaceId - The workspace ID.
252
+ */
253
+ resetPresence(workspaceId: number): Promise<void>;
254
+ /**
255
+ * Checks whether an email address is registered (and verified).
256
+ *
257
+ * @param email - The email to check.
258
+ * @returns Object indicating whether the email exists and is verified.
259
+ */
260
+ checkEmail(email: string): Promise<EmailExistsResponse>;
261
+ /**
262
+ * Returns the current per-channel mail unsubscribe settings for the
263
+ * caller's primary email.
264
+ *
265
+ * @returns Object mapping email-type keys to their opt-out flag.
266
+ */
267
+ getUnsubscribeSettings(): Promise<Record<string, boolean>>;
268
+ /**
269
+ * Toggles per-email-type opt-out settings.
270
+ *
271
+ * @param settings - Object mapping email-type keys to their opt-out flag.
272
+ * @returns Status object with `"ok"` status.
273
+ */
274
+ updateUnsubscribeSettings(settings: Record<string, boolean>): Promise<{
275
+ status: string;
276
+ }>;
277
+ private get;
278
+ private post;
279
+ }
280
+ export {};
@@ -0,0 +1,172 @@
1
+ import { type VisibleWorkspaceUser, type WorkspaceUser } from '../types/entities.js';
2
+ import { UserType } from '../types/enums.js';
3
+ import type { GetUserByEmailArgs, GetUserByIdArgs, GetUserInfoArgs, GetUserLocalTimeArgs, GetUsersByIdsArgs, GetWorkspaceUsersArgs } from '../types/requests.js';
4
+ import { BaseClient } from './base-client.js';
5
+ /**
6
+ * Client for `/api/v1.0/workspace_users/`. The backend's `add` endpoint
7
+ * rejects non-empty `name` and `channelIds` — set neither.
8
+ */
9
+ export declare class WorkspaceUsersClient extends BaseClient {
10
+ /**
11
+ * Returns a list of workspace user objects for the given workspace id.
12
+ *
13
+ * Removed users are excluded by default; set `args.includeRemoved` to `true` to include them.
14
+ * The Comms API always returns removed users, so the filtering happens client-side.
15
+ *
16
+ * @param args - The arguments for getting workspace users.
17
+ * @param args.workspaceId - The workspace ID.
18
+ * @param args.archived - Optional flag to filter archived users.
19
+ * @param args.includeRemoved - Include users removed from the workspace. Defaults to `false`.
20
+ * @returns An array of workspace user objects.
21
+ *
22
+ * @example
23
+ * ```typescript
24
+ * const users = await api.workspaceUsers.getWorkspaceUsers({ workspaceId: 123 })
25
+ * users.forEach(u => console.log(u.fullName, u.userType))
26
+ * ```
27
+ */
28
+ getWorkspaceUsers(args: GetWorkspaceUsersArgs): Promise<WorkspaceUser[]>;
29
+ /**
30
+ * Returns a list of workspace user IDs for the given workspace id.
31
+ *
32
+ * @param workspaceId - The workspace ID.
33
+ * @returns An array of user IDs.
34
+ */
35
+ getWorkspaceUserIds(workspaceId: number): Promise<number[]>;
36
+ /**
37
+ * Gets a user by id.
38
+ *
39
+ * @param args - The arguments for getting a user by ID.
40
+ * @param args.workspaceId - The workspace ID.
41
+ * @param args.userId - The user's ID.
42
+ * @returns The workspace user object, reduced to the restricted shape when
43
+ * the viewer may not see the user's full profile.
44
+ *
45
+ * @example
46
+ * ```typescript
47
+ * const user = await api.workspaceUsers.getUserById({ workspaceId: 123, userId: 456 })
48
+ * console.log(user.fullName, isRestrictedWorkspaceUser(user) ? null : user.email)
49
+ * ```
50
+ */
51
+ getUserById(args: GetUserByIdArgs): Promise<VisibleWorkspaceUser>;
52
+ /**
53
+ * Gets several users by id, one request per 100 ids. Prefer it over
54
+ * calling {@link getUserById} once per user.
55
+ *
56
+ * @param args - The arguments for getting users by ID.
57
+ * @param args.workspaceId - The workspace ID.
58
+ * @param args.userIds - The users' IDs. Duplicates are requested once.
59
+ * @returns The users keyed by id, each reduced to the restricted shape when
60
+ * the viewer may not see the full profile. An id the workspace has no record
61
+ * of maps to `null`, where {@link getUserById} would fail.
62
+ * @throws If any request fails, discarding the users already loaded.
63
+ *
64
+ * @example
65
+ * ```typescript
66
+ * const users = await api.workspaceUsers.getUsersByIds({ workspaceId: 123, userIds: [456, 789] })
67
+ * console.log(users[456]?.fullName ?? 'Unknown user')
68
+ * ```
69
+ */
70
+ getUsersByIds(args: GetUsersByIdsArgs): Promise<Record<number, VisibleWorkspaceUser | null>>;
71
+ /**
72
+ * Gets a user by email.
73
+ *
74
+ * @param args - The arguments for getting a user by email.
75
+ * @param args.workspaceId - The workspace ID.
76
+ * @param args.email - The user's email.
77
+ * @returns The workspace user object, reduced to the restricted shape when
78
+ * the viewer may not see the user's full profile.
79
+ *
80
+ * @example
81
+ * ```typescript
82
+ * const user = await api.workspaceUsers.getUserByEmail({
83
+ * workspaceId: 123,
84
+ * email: 'user@example.com',
85
+ * })
86
+ * ```
87
+ */
88
+ getUserByEmail(args: GetUserByEmailArgs): Promise<VisibleWorkspaceUser>;
89
+ /**
90
+ * Gets the user's info in the context of the workspace.
91
+ *
92
+ * @param args - The arguments for getting user info.
93
+ * @param args.workspaceId - The workspace ID.
94
+ * @param args.userId - The user's ID.
95
+ * @returns Information about the user in the workspace context.
96
+ */
97
+ getUserInfo(args: GetUserInfoArgs): Promise<Record<string, unknown>>;
98
+ /**
99
+ * Gets the user's local time (e.g., "2017-05-10 07:55:40").
100
+ *
101
+ * @param args - The arguments for getting user local time.
102
+ * @param args.workspaceId - The workspace ID.
103
+ * @param args.userId - The user's ID.
104
+ * @returns The user's local time as a string.
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * const localTime = await api.workspaceUsers.getUserLocalTime({
109
+ * workspaceId: 123,
110
+ * userId: 456,
111
+ * })
112
+ * console.log('User local time:', localTime)
113
+ * ```
114
+ */
115
+ getUserLocalTime(args: GetUserLocalTimeArgs): Promise<string>;
116
+ /**
117
+ * Adds a person to a workspace.
118
+ *
119
+ * @param args - The arguments for adding a user.
120
+ * @param args.workspaceId - The workspace ID.
121
+ * @param args.email - The user's email.
122
+ * @param args.userType - Optional user type (USER, GUEST, or ADMIN).
123
+ * @returns The created workspace user object.
124
+ */
125
+ addUser(args: {
126
+ workspaceId: number;
127
+ email: string;
128
+ userType?: UserType;
129
+ }): Promise<WorkspaceUser>;
130
+ /**
131
+ * Updates a person in a workspace.
132
+ *
133
+ * @param args - The arguments for updating a user.
134
+ * @param args.workspaceId - The workspace ID.
135
+ * @param args.userType - The user type (USER, GUEST, or ADMIN).
136
+ * @param args.email - Optional email of the user to update.
137
+ * @param args.userId - Optional user ID to update (use either email or userId).
138
+ * @returns The updated workspace user object.
139
+ */
140
+ updateUser(args: {
141
+ workspaceId: number;
142
+ userType: UserType;
143
+ email?: string;
144
+ userId?: number;
145
+ }): Promise<WorkspaceUser>;
146
+ /**
147
+ * Removes a person from a workspace.
148
+ *
149
+ * @param args - The arguments for removing a user.
150
+ * @param args.workspaceId - The workspace ID.
151
+ * @param args.email - Optional email of the user to remove.
152
+ * @param args.userId - Optional user ID to remove (use either email or userId).
153
+ */
154
+ removeUser(args: {
155
+ workspaceId: number;
156
+ email?: string;
157
+ userId?: number;
158
+ }): Promise<void>;
159
+ /**
160
+ * Sends a new workspace invitation to the selected user.
161
+ *
162
+ * @param args - The arguments for resending an invite.
163
+ * @param args.workspaceId - The workspace ID.
164
+ * @param args.email - The user's email.
165
+ * @param args.userId - Optional user ID.
166
+ */
167
+ resendInvite(args: {
168
+ workspaceId: number;
169
+ email: string;
170
+ userId?: number;
171
+ }): Promise<void>;
172
+ }
@@ -0,0 +1,154 @@
1
+ import { z } from 'zod';
2
+ import { Channel, Workspace } from '../types/entities.js';
3
+ import { BaseClient } from './base-client.js';
4
+ export declare const ChannelListSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
5
+ id: z.ZodString;
6
+ name: z.ZodString;
7
+ description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
8
+ creator: z.ZodNumber;
9
+ userIds: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
10
+ color: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
11
+ public: z.ZodBoolean;
12
+ workspaceId: z.ZodNumber;
13
+ archived: z.ZodBoolean;
14
+ created: z.ZodDate;
15
+ useDefaultRecipients: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
16
+ defaultGroups: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
17
+ defaultRecipients: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
18
+ isFavorited: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
19
+ icon: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
20
+ version: z.ZodNumber;
21
+ filters: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
22
+ }, z.core.$strip>, z.ZodTransform<{
23
+ url: string;
24
+ id: string;
25
+ name: string;
26
+ creator: number;
27
+ public: boolean;
28
+ workspaceId: number;
29
+ archived: boolean;
30
+ created: Date;
31
+ version: number;
32
+ description?: string | null | undefined;
33
+ userIds?: number[] | null | undefined;
34
+ color?: number | null | undefined;
35
+ useDefaultRecipients?: boolean | null | undefined;
36
+ defaultGroups?: string[] | null | undefined;
37
+ defaultRecipients?: number[] | null | undefined;
38
+ isFavorited?: boolean | null | undefined;
39
+ icon?: number | null | undefined;
40
+ filters?: Record<string, string> | null | undefined;
41
+ }, {
42
+ id: string;
43
+ name: string;
44
+ creator: number;
45
+ public: boolean;
46
+ workspaceId: number;
47
+ archived: boolean;
48
+ created: Date;
49
+ version: number;
50
+ description?: string | null | undefined;
51
+ userIds?: number[] | null | undefined;
52
+ color?: number | null | undefined;
53
+ useDefaultRecipients?: boolean | null | undefined;
54
+ defaultGroups?: string[] | null | undefined;
55
+ defaultRecipients?: number[] | null | undefined;
56
+ isFavorited?: boolean | null | undefined;
57
+ icon?: number | null | undefined;
58
+ filters?: Record<string, string> | null | undefined;
59
+ }>>>;
60
+ /**
61
+ * Client for `/api/v1.0/workspaces/`. Workspace IDs are integers. The backend
62
+ * currently rejects any `color` other than `1` on add/update.
63
+ */
64
+ export declare class WorkspacesClient extends BaseClient {
65
+ private readonly linkBaseUrl;
66
+ private readonly channelListSchema;
67
+ /**
68
+ * Gets all the user's workspaces.
69
+ *
70
+ * @returns An array of all workspaces the user belongs to.
71
+ *
72
+ * @example
73
+ * ```typescript
74
+ * const workspaces = await api.workspaces.getWorkspaces()
75
+ * workspaces.forEach(ws => console.log(ws.name))
76
+ * ```
77
+ */
78
+ getWorkspaces(): Promise<Workspace[]>;
79
+ /**
80
+ * Gets a single workspace object by id.
81
+ *
82
+ * @param id - The workspace ID.
83
+ * @returns The workspace object.
84
+ *
85
+ * @example
86
+ * ```typescript
87
+ * const workspace = await api.workspaces.getWorkspace(123)
88
+ * console.log(workspace.name)
89
+ * ```
90
+ */
91
+ getWorkspace(id: number): Promise<Workspace>;
92
+ /**
93
+ * Gets the user's default workspace.
94
+ *
95
+ * @returns The default workspace object.
96
+ *
97
+ * @example
98
+ * ```typescript
99
+ * const workspace = await api.workspaces.getDefaultWorkspace()
100
+ * console.log(workspace.name)
101
+ * ```
102
+ */
103
+ getDefaultWorkspace(): Promise<Workspace>;
104
+ /**
105
+ * Creates a new workspace.
106
+ *
107
+ * @param name - The name of the new workspace.
108
+ * @returns The created workspace object.
109
+ *
110
+ * @example
111
+ * ```typescript
112
+ * const workspace = await api.workspaces.createWorkspace('My Team')
113
+ * console.log('Created:', workspace.name)
114
+ * ```
115
+ */
116
+ createWorkspace(name: string): Promise<Workspace>;
117
+ /**
118
+ * Updates an existing workspace.
119
+ *
120
+ * @param id - The workspace ID.
121
+ * @param name - The new name for the workspace.
122
+ * @returns The updated workspace object.
123
+ *
124
+ * @example
125
+ * ```typescript
126
+ * const workspace = await api.workspaces.updateWorkspace(123, 'New Team Name')
127
+ * ```
128
+ */
129
+ updateWorkspace(id: number, name: string): Promise<Workspace>;
130
+ /**
131
+ * Removes a workspace and all its data (not recoverable).
132
+ *
133
+ * @param id - The workspace ID.
134
+ *
135
+ * @example
136
+ * ```typescript
137
+ * await api.workspaces.removeWorkspace(123)
138
+ * ```
139
+ */
140
+ removeWorkspace(id: number): Promise<void>;
141
+ /**
142
+ * Gets the public channels of a workspace.
143
+ *
144
+ * @param id - The workspace ID.
145
+ * @returns An array of public channel objects.
146
+ *
147
+ * @example
148
+ * ```typescript
149
+ * const channels = await api.workspaces.getPublicChannels(123)
150
+ * channels.forEach(ch => console.log(ch.name))
151
+ * ```
152
+ */
153
+ getPublicChannels(id: number): Promise<Channel[]>;
154
+ }
@@ -0,0 +1,73 @@
1
+ import { AttachmentsClient } from './clients/attachments-client.js';
2
+ import { ChannelsClient } from './clients/channels-client.js';
3
+ import { CommentsClient } from './clients/comments-client.js';
4
+ import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
5
+ import { ConversationsClient } from './clients/conversations-client.js';
6
+ import { GroupsClient } from './clients/groups-client.js';
7
+ import { HooksClient } from './clients/hooks-client.js';
8
+ import { InboxClient } from './clients/inbox-client.js';
9
+ import { ReactionsClient } from './clients/reactions-client.js';
10
+ import { SearchClient } from './clients/search-client.js';
11
+ import { ThreadsClient } from './clients/threads-client.js';
12
+ import { UsersClient } from './clients/users-client.js';
13
+ import { WorkspaceUsersClient } from './clients/workspace-users-client.js';
14
+ import { WorkspacesClient } from './clients/workspaces-client.js';
15
+ import type { ApiVersion } from './types/api-version.js';
16
+ import type { CustomFetch, CustomHeaders } from './types/http.js';
17
+ export type CommsApiOptions = {
18
+ /** Optional custom API base URL. If not provided, defaults to Comms' standard API endpoint. */
19
+ baseUrl?: string;
20
+ /** Optional API version. Defaults to 'v1.0'. */
21
+ version?: ApiVersion;
22
+ /** Optional custom fetch implementation for cross-platform compatibility (e.g., Obsidian, React Native, Electron). */
23
+ customFetch?: CustomFetch;
24
+ /**
25
+ * Optional headers sent with every request, e.g. `{ 'Doist-Platform': 'cli' }` for client
26
+ * attribution. Pass a function instead to compute them per request, e.g. a fresh request ID;
27
+ * it is called once per request and retries reuse its result. Cannot override `Authorization`
28
+ * or `X-Request-Id`.
29
+ */
30
+ headers?: CustomHeaders;
31
+ };
32
+ /**
33
+ * The main API client for interacting with the Comms REST API.
34
+ *
35
+ * @example
36
+ * ```typescript
37
+ * import { CommsApi } from '@todoist/comms-sdk'
38
+ *
39
+ * const api = new CommsApi('your-api-token')
40
+ * const user = await api.users.getSessionUser()
41
+ * ```
42
+ */
43
+ export declare class CommsApi {
44
+ users: UsersClient;
45
+ workspaces: WorkspacesClient;
46
+ workspaceUsers: WorkspaceUsersClient;
47
+ channels: ChannelsClient;
48
+ threads: ThreadsClient;
49
+ groups: GroupsClient;
50
+ conversations: ConversationsClient;
51
+ comments: CommentsClient;
52
+ conversationMessages: ConversationMessagesClient;
53
+ inbox: InboxClient;
54
+ reactions: ReactionsClient;
55
+ search: SearchClient;
56
+ attachments: AttachmentsClient;
57
+ hooks: HooksClient;
58
+ /**
59
+ * Creates a new Comms API client.
60
+ *
61
+ * @param authToken - Your Comms API token.
62
+ * @param options - Optional configuration options.
63
+ */
64
+ constructor(authToken: string, options?: CommsApiOptions);
65
+ /**
66
+ * Drains the SDK's process-global connection pool. CLIs and scripts
67
+ * should `await api.close()` before exit so Node's event loop empties
68
+ * immediately instead of waiting ~4s on keep-alive. Affects every
69
+ * `CommsApi` and OAuth helper in the same process — it's a
70
+ * process-shutdown gesture, not an instance teardown. Browser-safe.
71
+ */
72
+ close(): Promise<void>;
73
+ }