@doist/comms-sdk 0.0.1 → 0.2.0

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 (115) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +143 -45
  3. package/dist/cjs/authentication.js +211 -0
  4. package/dist/cjs/clients/add-comment-helper.js +70 -0
  5. package/dist/cjs/clients/base-client.js +25 -0
  6. package/dist/cjs/clients/channels-client.js +200 -0
  7. package/dist/cjs/clients/comments-client.js +159 -0
  8. package/dist/cjs/clients/conversation-messages-client.js +158 -0
  9. package/dist/cjs/clients/conversations-client.js +243 -0
  10. package/dist/cjs/clients/groups-client.js +164 -0
  11. package/dist/cjs/clients/inbox-client.js +171 -0
  12. package/dist/cjs/clients/reactions-client.js +97 -0
  13. package/dist/cjs/clients/search-client.js +138 -0
  14. package/dist/cjs/clients/threads-client.js +330 -0
  15. package/dist/cjs/clients/users-client.js +326 -0
  16. package/dist/cjs/clients/workspace-users-client.js +240 -0
  17. package/dist/cjs/clients/workspaces-client.js +166 -0
  18. package/dist/cjs/comms-api.js +66 -0
  19. package/dist/cjs/consts/endpoints.js +32 -0
  20. package/dist/cjs/index.js +48 -0
  21. package/dist/cjs/package.json +1 -0
  22. package/dist/cjs/testUtils/msw-handlers.js +51 -0
  23. package/dist/cjs/testUtils/msw-setup.js +21 -0
  24. package/dist/cjs/testUtils/obsidian-fetch-adapter.js +53 -0
  25. package/dist/cjs/testUtils/test-defaults.js +104 -0
  26. package/dist/cjs/transport/fetch-with-retry.js +136 -0
  27. package/dist/cjs/transport/http-client.js +56 -0
  28. package/dist/cjs/transport/http-dispatcher.js +143 -0
  29. package/dist/cjs/types/api-version.js +8 -0
  30. package/dist/cjs/types/entities.js +411 -0
  31. package/dist/cjs/types/enums.js +37 -0
  32. package/dist/cjs/types/errors.js +12 -0
  33. package/dist/cjs/types/http.js +4 -0
  34. package/dist/cjs/types/index.js +22 -0
  35. package/dist/cjs/types/requests.js +116 -0
  36. package/dist/cjs/utils/case-conversion.js +54 -0
  37. package/dist/cjs/utils/index.js +19 -0
  38. package/dist/cjs/utils/timestamp-conversion.js +49 -0
  39. package/dist/cjs/utils/url-helpers.js +131 -0
  40. package/dist/cjs/utils/uuidv7.js +174 -0
  41. package/dist/esm/authentication.js +203 -0
  42. package/dist/esm/clients/add-comment-helper.js +67 -0
  43. package/dist/esm/clients/base-client.js +21 -0
  44. package/dist/esm/clients/channels-client.js +196 -0
  45. package/dist/esm/clients/comments-client.js +155 -0
  46. package/dist/esm/clients/conversation-messages-client.js +154 -0
  47. package/dist/esm/clients/conversations-client.js +239 -0
  48. package/dist/esm/clients/groups-client.js +160 -0
  49. package/dist/esm/clients/inbox-client.js +167 -0
  50. package/dist/esm/clients/reactions-client.js +93 -0
  51. package/dist/esm/clients/search-client.js +134 -0
  52. package/dist/esm/clients/threads-client.js +326 -0
  53. package/dist/esm/clients/users-client.js +322 -0
  54. package/dist/esm/clients/workspace-users-client.js +236 -0
  55. package/dist/esm/clients/workspaces-client.js +162 -0
  56. package/dist/esm/comms-api.js +62 -0
  57. package/dist/esm/consts/endpoints.js +28 -0
  58. package/dist/esm/index.js +17 -0
  59. package/dist/esm/testUtils/msw-handlers.js +45 -0
  60. package/dist/esm/testUtils/msw-setup.js +18 -0
  61. package/dist/esm/testUtils/obsidian-fetch-adapter.js +50 -0
  62. package/dist/esm/testUtils/test-defaults.js +101 -0
  63. package/dist/esm/transport/fetch-with-retry.js +133 -0
  64. package/dist/esm/transport/http-client.js +51 -0
  65. package/dist/esm/transport/http-dispatcher.js +104 -0
  66. package/dist/esm/types/api-version.js +5 -0
  67. package/dist/esm/types/entities.js +408 -0
  68. package/dist/esm/types/enums.js +34 -0
  69. package/dist/esm/types/errors.js +8 -0
  70. package/dist/esm/types/http.js +1 -0
  71. package/dist/esm/types/index.js +6 -0
  72. package/dist/esm/types/requests.js +113 -0
  73. package/dist/esm/utils/case-conversion.js +47 -0
  74. package/dist/esm/utils/index.js +3 -0
  75. package/dist/esm/utils/timestamp-conversion.js +45 -0
  76. package/dist/esm/utils/url-helpers.js +112 -0
  77. package/dist/esm/utils/uuidv7.js +163 -0
  78. package/dist/types/authentication.d.ts +160 -0
  79. package/dist/types/clients/add-comment-helper.d.ts +29 -0
  80. package/dist/types/clients/base-client.d.ts +28 -0
  81. package/dist/types/clients/channels-client.d.ts +208 -0
  82. package/dist/types/clients/comments-client.d.ts +224 -0
  83. package/dist/types/clients/conversation-messages-client.d.ts +198 -0
  84. package/dist/types/clients/conversations-client.d.ts +346 -0
  85. package/dist/types/clients/groups-client.d.ts +148 -0
  86. package/dist/types/clients/inbox-client.d.ts +96 -0
  87. package/dist/types/clients/reactions-client.d.ts +57 -0
  88. package/dist/types/clients/search-client.d.ts +70 -0
  89. package/dist/types/clients/threads-client.d.ts +536 -0
  90. package/dist/types/clients/users-client.d.ts +250 -0
  91. package/dist/types/clients/workspace-users-client.d.ts +147 -0
  92. package/dist/types/clients/workspaces-client.d.ts +152 -0
  93. package/dist/types/comms-api.d.ts +62 -0
  94. package/dist/types/consts/endpoints.d.ts +24 -0
  95. package/dist/types/index.d.ts +18 -0
  96. package/dist/types/testUtils/msw-handlers.d.ts +28 -0
  97. package/dist/types/testUtils/msw-setup.d.ts +1 -0
  98. package/dist/types/testUtils/obsidian-fetch-adapter.d.ts +29 -0
  99. package/dist/types/testUtils/test-defaults.d.ts +17 -0
  100. package/dist/types/transport/fetch-with-retry.d.ts +4 -0
  101. package/dist/types/transport/http-client.d.ts +13 -0
  102. package/dist/types/transport/http-dispatcher.d.ts +10 -0
  103. package/dist/types/types/api-version.d.ts +6 -0
  104. package/dist/types/types/entities.d.ts +1288 -0
  105. package/dist/types/types/enums.d.ts +55 -0
  106. package/dist/types/types/errors.d.ts +6 -0
  107. package/dist/types/types/http.d.ts +54 -0
  108. package/dist/types/types/index.d.ts +6 -0
  109. package/dist/types/types/requests.d.ts +366 -0
  110. package/dist/types/utils/case-conversion.d.ts +8 -0
  111. package/dist/types/utils/index.d.ts +3 -0
  112. package/dist/types/utils/timestamp-conversion.d.ts +13 -0
  113. package/dist/types/utils/url-helpers.d.ts +88 -0
  114. package/dist/types/utils/uuidv7.d.ts +40 -0
  115. package/package.json +91 -8
@@ -0,0 +1,250 @@
1
+ import { type User } from '../types/entities.js';
2
+ import type { 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/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
+ * Updates the user's password.
164
+ *
165
+ * @param args - Password update arguments.
166
+ * @param args.newPassword - The new password.
167
+ * @param args.currentPassword - The user's existing password. Optional — sent for
168
+ * re-authentication when the account has a password set.
169
+ * @returns The updated user object.
170
+ */
171
+ updatePassword(args: {
172
+ newPassword: string;
173
+ currentPassword?: string;
174
+ }): Promise<User>;
175
+ /**
176
+ * Removes the user's avatar.
177
+ *
178
+ * @returns The updated user object.
179
+ */
180
+ removeAvatar(): Promise<User>;
181
+ /**
182
+ * Invalidates the current API token and returns the user with a fresh
183
+ * token.
184
+ *
185
+ * @returns The user object with the new token.
186
+ *
187
+ * @example
188
+ * ```typescript
189
+ * const user = await api.users.invalidateToken()
190
+ * console.log('New token:', user.token)
191
+ * ```
192
+ */
193
+ invalidateToken(): Promise<User>;
194
+ /**
195
+ * Validates that an arbitrary token is still active. Note this is sent
196
+ * as a GET — the token is read from the query string, not the
197
+ * Authorization header.
198
+ *
199
+ * @param token - The token to validate.
200
+ */
201
+ validateToken(token: string): Promise<void>;
202
+ /**
203
+ * Marks the user as active on a workspace (presence beacon).
204
+ *
205
+ * @param args - Heartbeat arguments.
206
+ * @param args.workspaceId - The workspace ID.
207
+ * @param args.platform - The platform identifier (e.g., 'mobile', 'desktop', 'api').
208
+ *
209
+ * @example
210
+ * ```typescript
211
+ * await api.users.heartbeat({ workspaceId: 123, platform: 'api' })
212
+ * ```
213
+ */
214
+ heartbeat(args: {
215
+ workspaceId: number;
216
+ platform: string;
217
+ }): Promise<void>;
218
+ /**
219
+ * Resets the user's presence for a workspace (marks the user as inactive).
220
+ *
221
+ * @param workspaceId - The workspace ID.
222
+ */
223
+ resetPresence(workspaceId: number): Promise<void>;
224
+ /**
225
+ * Checks whether an email address is registered (and verified).
226
+ *
227
+ * @param email - The email to check.
228
+ * @returns Object indicating whether the email exists and is verified.
229
+ */
230
+ checkEmail(email: string): Promise<EmailExistsResponse>;
231
+ /**
232
+ * Returns the current per-channel mail unsubscribe settings for the
233
+ * caller's primary email.
234
+ *
235
+ * @returns Object mapping email-type keys to their opt-out flag.
236
+ */
237
+ getUnsubscribeSettings(): Promise<Record<string, boolean>>;
238
+ /**
239
+ * Toggles per-email-type opt-out settings.
240
+ *
241
+ * @param settings - Object mapping email-type keys to their opt-out flag.
242
+ * @returns Status object with `"ok"` status.
243
+ */
244
+ updateUnsubscribeSettings(settings: Record<string, boolean>): Promise<{
245
+ status: string;
246
+ }>;
247
+ private get;
248
+ private post;
249
+ }
250
+ export {};
@@ -0,0 +1,147 @@
1
+ import { type WorkspaceUser } from '../types/entities.js';
2
+ import { UserType } from '../types/enums.js';
3
+ import type { GetUserByEmailArgs, GetUserByIdArgs, GetUserInfoArgs, GetUserLocalTimeArgs, GetWorkspaceUsersArgs } from '../types/requests.js';
4
+ import { BaseClient } from './base-client.js';
5
+ /**
6
+ * Client for `/api/v1/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
+ * @param args - The arguments for getting workspace users.
14
+ * @param args.workspaceId - The workspace ID.
15
+ * @param args.archived - Optional flag to filter archived users.
16
+ * @returns An array of workspace user objects.
17
+ *
18
+ * @example
19
+ * ```typescript
20
+ * const users = await api.workspaceUsers.getWorkspaceUsers({ workspaceId: 123 })
21
+ * users.forEach(u => console.log(u.fullName, u.userType))
22
+ * ```
23
+ */
24
+ getWorkspaceUsers(args: GetWorkspaceUsersArgs): Promise<WorkspaceUser[]>;
25
+ /**
26
+ * Returns a list of workspace user IDs for the given workspace id.
27
+ *
28
+ * @param workspaceId - The workspace ID.
29
+ * @returns An array of user IDs.
30
+ */
31
+ getWorkspaceUserIds(workspaceId: number): Promise<number[]>;
32
+ /**
33
+ * Gets a user by id.
34
+ *
35
+ * @param args - The arguments for getting a user by ID.
36
+ * @param args.workspaceId - The workspace ID.
37
+ * @param args.userId - The user's ID.
38
+ * @returns The workspace user object.
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * const user = await api.workspaceUsers.getUserById({ workspaceId: 123, userId: 456 })
43
+ * console.log(user.fullName, user.email)
44
+ * ```
45
+ */
46
+ getUserById(args: GetUserByIdArgs): Promise<WorkspaceUser>;
47
+ /**
48
+ * Gets a user by email.
49
+ *
50
+ * @param args - The arguments for getting a user by email.
51
+ * @param args.workspaceId - The workspace ID.
52
+ * @param args.email - The user's email.
53
+ * @returns The workspace user object.
54
+ *
55
+ * @example
56
+ * ```typescript
57
+ * const user = await api.workspaceUsers.getUserByEmail({
58
+ * workspaceId: 123,
59
+ * email: 'user@example.com',
60
+ * })
61
+ * ```
62
+ */
63
+ getUserByEmail(args: GetUserByEmailArgs): Promise<WorkspaceUser>;
64
+ /**
65
+ * Gets the user's info in the context of the workspace.
66
+ *
67
+ * @param args - The arguments for getting user info.
68
+ * @param args.workspaceId - The workspace ID.
69
+ * @param args.userId - The user's ID.
70
+ * @returns Information about the user in the workspace context.
71
+ */
72
+ getUserInfo(args: GetUserInfoArgs): Promise<Record<string, unknown>>;
73
+ /**
74
+ * Gets the user's local time (e.g., "2017-05-10 07:55:40").
75
+ *
76
+ * @param args - The arguments for getting user local time.
77
+ * @param args.workspaceId - The workspace ID.
78
+ * @param args.userId - The user's ID.
79
+ * @returns The user's local time as a string.
80
+ *
81
+ * @example
82
+ * ```typescript
83
+ * const localTime = await api.workspaceUsers.getUserLocalTime({
84
+ * workspaceId: 123,
85
+ * userId: 456,
86
+ * })
87
+ * console.log('User local time:', localTime)
88
+ * ```
89
+ */
90
+ getUserLocalTime(args: GetUserLocalTimeArgs): Promise<string>;
91
+ /**
92
+ * Adds a person to a workspace.
93
+ *
94
+ * @param args - The arguments for adding a user.
95
+ * @param args.workspaceId - The workspace ID.
96
+ * @param args.email - The user's email.
97
+ * @param args.userType - Optional user type (USER, GUEST, or ADMIN).
98
+ * @returns The created workspace user object.
99
+ */
100
+ addUser(args: {
101
+ workspaceId: number;
102
+ email: string;
103
+ userType?: UserType;
104
+ }): Promise<WorkspaceUser>;
105
+ /**
106
+ * Updates a person in a workspace.
107
+ *
108
+ * @param args - The arguments for updating a user.
109
+ * @param args.workspaceId - The workspace ID.
110
+ * @param args.userType - The user type (USER, GUEST, or ADMIN).
111
+ * @param args.email - Optional email of the user to update.
112
+ * @param args.userId - Optional user ID to update (use either email or userId).
113
+ * @returns The updated workspace user object.
114
+ */
115
+ updateUser(args: {
116
+ workspaceId: number;
117
+ userType: UserType;
118
+ email?: string;
119
+ userId?: number;
120
+ }): Promise<WorkspaceUser>;
121
+ /**
122
+ * Removes a person from a workspace.
123
+ *
124
+ * @param args - The arguments for removing a user.
125
+ * @param args.workspaceId - The workspace ID.
126
+ * @param args.email - Optional email of the user to remove.
127
+ * @param args.userId - Optional user ID to remove (use either email or userId).
128
+ */
129
+ removeUser(args: {
130
+ workspaceId: number;
131
+ email?: string;
132
+ userId?: number;
133
+ }): Promise<void>;
134
+ /**
135
+ * Sends a new workspace invitation to the selected user.
136
+ *
137
+ * @param args - The arguments for resending an invite.
138
+ * @param args.workspaceId - The workspace ID.
139
+ * @param args.email - The user's email.
140
+ * @param args.userId - Optional user ID.
141
+ */
142
+ resendInvite(args: {
143
+ workspaceId: number;
144
+ email: string;
145
+ userId?: number;
146
+ }): Promise<void>;
147
+ }
@@ -0,0 +1,152 @@
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/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
+ /**
66
+ * Gets all the user's workspaces.
67
+ *
68
+ * @returns An array of all workspaces the user belongs to.
69
+ *
70
+ * @example
71
+ * ```typescript
72
+ * const workspaces = await api.workspaces.getWorkspaces()
73
+ * workspaces.forEach(ws => console.log(ws.name))
74
+ * ```
75
+ */
76
+ getWorkspaces(): Promise<Workspace[]>;
77
+ /**
78
+ * Gets a single workspace object by id.
79
+ *
80
+ * @param id - The workspace ID.
81
+ * @returns The workspace object.
82
+ *
83
+ * @example
84
+ * ```typescript
85
+ * const workspace = await api.workspaces.getWorkspace(123)
86
+ * console.log(workspace.name)
87
+ * ```
88
+ */
89
+ getWorkspace(id: number): Promise<Workspace>;
90
+ /**
91
+ * Gets the user's default workspace.
92
+ *
93
+ * @returns The default workspace object.
94
+ *
95
+ * @example
96
+ * ```typescript
97
+ * const workspace = await api.workspaces.getDefaultWorkspace()
98
+ * console.log(workspace.name)
99
+ * ```
100
+ */
101
+ getDefaultWorkspace(): Promise<Workspace>;
102
+ /**
103
+ * Creates a new workspace.
104
+ *
105
+ * @param name - The name of the new workspace.
106
+ * @returns The created workspace object.
107
+ *
108
+ * @example
109
+ * ```typescript
110
+ * const workspace = await api.workspaces.createWorkspace('My Team')
111
+ * console.log('Created:', workspace.name)
112
+ * ```
113
+ */
114
+ createWorkspace(name: string): Promise<Workspace>;
115
+ /**
116
+ * Updates an existing workspace.
117
+ *
118
+ * @param id - The workspace ID.
119
+ * @param name - The new name for the workspace.
120
+ * @returns The updated workspace object.
121
+ *
122
+ * @example
123
+ * ```typescript
124
+ * const workspace = await api.workspaces.updateWorkspace(123, 'New Team Name')
125
+ * ```
126
+ */
127
+ updateWorkspace(id: number, name: string): Promise<Workspace>;
128
+ /**
129
+ * Removes a workspace and all its data (not recoverable).
130
+ *
131
+ * @param id - The workspace ID.
132
+ *
133
+ * @example
134
+ * ```typescript
135
+ * await api.workspaces.removeWorkspace(123)
136
+ * ```
137
+ */
138
+ removeWorkspace(id: number): Promise<void>;
139
+ /**
140
+ * Gets the public channels of a workspace.
141
+ *
142
+ * @param id - The workspace ID.
143
+ * @returns An array of public channel objects.
144
+ *
145
+ * @example
146
+ * ```typescript
147
+ * const channels = await api.workspaces.getPublicChannels(123)
148
+ * channels.forEach(ch => console.log(ch.name))
149
+ * ```
150
+ */
151
+ getPublicChannels(id: number): Promise<Channel[]>;
152
+ }
@@ -0,0 +1,62 @@
1
+ import { ChannelsClient } from './clients/channels-client.js';
2
+ import { CommentsClient } from './clients/comments-client.js';
3
+ import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
4
+ import { ConversationsClient } from './clients/conversations-client.js';
5
+ import { GroupsClient } from './clients/groups-client.js';
6
+ import { InboxClient } from './clients/inbox-client.js';
7
+ import { ReactionsClient } from './clients/reactions-client.js';
8
+ import { SearchClient } from './clients/search-client.js';
9
+ import { ThreadsClient } from './clients/threads-client.js';
10
+ import { UsersClient } from './clients/users-client.js';
11
+ import { WorkspaceUsersClient } from './clients/workspace-users-client.js';
12
+ import { WorkspacesClient } from './clients/workspaces-client.js';
13
+ import type { ApiVersion } from './types/api-version.js';
14
+ import type { CustomFetch } from './types/http.js';
15
+ export type CommsApiOptions = {
16
+ /** Optional custom API base URL. If not provided, defaults to Comms' standard API endpoint. */
17
+ baseUrl?: string;
18
+ /** Optional API version. Defaults to 'v1'. */
19
+ version?: ApiVersion;
20
+ /** Optional custom fetch implementation for cross-platform compatibility (e.g., Obsidian, React Native, Electron). */
21
+ customFetch?: CustomFetch;
22
+ };
23
+ /**
24
+ * The main API client for interacting with the Comms REST API.
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * import { CommsApi } from '@doist/comms-sdk'
29
+ *
30
+ * const api = new CommsApi('your-api-token')
31
+ * const user = await api.users.getSessionUser()
32
+ * ```
33
+ */
34
+ export declare class CommsApi {
35
+ users: UsersClient;
36
+ workspaces: WorkspacesClient;
37
+ workspaceUsers: WorkspaceUsersClient;
38
+ channels: ChannelsClient;
39
+ threads: ThreadsClient;
40
+ groups: GroupsClient;
41
+ conversations: ConversationsClient;
42
+ comments: CommentsClient;
43
+ conversationMessages: ConversationMessagesClient;
44
+ inbox: InboxClient;
45
+ reactions: ReactionsClient;
46
+ search: SearchClient;
47
+ /**
48
+ * Creates a new Comms API client.
49
+ *
50
+ * @param authToken - Your Comms API token.
51
+ * @param options - Optional configuration options.
52
+ */
53
+ constructor(authToken: string, options?: CommsApiOptions);
54
+ /**
55
+ * Drains the SDK's process-global connection pool. CLIs and scripts
56
+ * should `await api.close()` before exit so Node's event loop empties
57
+ * immediately instead of waiting ~4s on keep-alive. Affects every
58
+ * `CommsApi` and OAuth helper in the same process — it's a
59
+ * process-shutdown gesture, not an instance teardown. Browser-safe.
60
+ */
61
+ close(): Promise<void>;
62
+ }
@@ -0,0 +1,24 @@
1
+ import type { ApiVersion } from '../types/api-version.js';
2
+ /**
3
+ * Gets the base URI for Comms API requests.
4
+ *
5
+ * Preserves any path component on `domainBase` so callers can route through
6
+ * a proxy (e.g. `https://proxy.example.com/comms` → `.../comms/api/v1/`).
7
+ *
8
+ * @param version - API version. Defaults to 'v1'.
9
+ * @param domainBase - Custom domain base URL. Defaults to Comms' API domain.
10
+ * @returns Complete base URI with trailing slash (e.g., 'https://comms.todoist.com/api/v1/')
11
+ */
12
+ export declare function getCommsBaseUri(version?: ApiVersion, domainBase?: string): string;
13
+ export declare const ENDPOINT_USERS = "users";
14
+ export declare const ENDPOINT_WORKSPACES = "workspaces";
15
+ export declare const ENDPOINT_CHANNELS = "channels";
16
+ export declare const ENDPOINT_THREADS = "threads";
17
+ export declare const ENDPOINT_GROUPS = "groups";
18
+ export declare const ENDPOINT_CONVERSATIONS = "conversations";
19
+ export declare const ENDPOINT_COMMENTS = "comments";
20
+ export declare const ENDPOINT_NOTIFICATIONS = "notifications";
21
+ export declare const ENDPOINT_INBOX = "inbox";
22
+ export declare const ENDPOINT_REACTIONS = "reactions";
23
+ export declare const ENDPOINT_SEARCH = "search";
24
+ export declare const ENDPOINT_CONVERSATION_MESSAGES = "conversation_messages";
@@ -0,0 +1,18 @@
1
+ export * from './authentication.js';
2
+ export { ChannelsClient } from './clients/channels-client.js';
3
+ export { CommentsClient } from './clients/comments-client.js';
4
+ export { ConversationMessagesClient } from './clients/conversation-messages-client.js';
5
+ export { ConversationsClient } from './clients/conversations-client.js';
6
+ export { GroupsClient } from './clients/groups-client.js';
7
+ export { InboxClient } from './clients/inbox-client.js';
8
+ export { ReactionsClient } from './clients/reactions-client.js';
9
+ export { SearchClient } from './clients/search-client.js';
10
+ export { ThreadsClient } from './clients/threads-client.js';
11
+ export { UsersClient } from './clients/users-client.js';
12
+ export { WorkspaceUsersClient } from './clients/workspace-users-client.js';
13
+ export { WorkspacesClient } from './clients/workspaces-client.js';
14
+ export { CommsApi } from './comms-api.js';
15
+ export type { CommsApiOptions } from './comms-api.js';
16
+ export { closeDefaultDispatcher } from './transport/http-dispatcher.js';
17
+ export * from './types/index.js';
18
+ export * from './utils/index.js';
@@ -0,0 +1,28 @@
1
+ import { HttpResponse, http } from 'msw';
2
+ type JsonValue = string | number | boolean | null | JsonValue[] | {
3
+ [key: string]: JsonValue;
4
+ };
5
+ /**
6
+ * Creates a successful API response with the given data
7
+ */
8
+ export declare function createSuccessResponse(data: JsonValue): HttpResponse<import("msw").JsonBodyType>;
9
+ /**
10
+ * Creates an error API response
11
+ */
12
+ export declare function createErrorResponse(errorCode: string, errorMessage: string, status?: number): HttpResponse<import("msw").JsonBodyType>;
13
+ /**
14
+ * Helper to create API endpoint URL
15
+ */
16
+ export declare function apiUrl(path: string): string;
17
+ /**
18
+ * Creates a handler for a GET endpoint
19
+ */
20
+ export declare function createGetHandler(endpoint: string, responseData: JsonValue): import("msw").HttpHandler;
21
+ /**
22
+ * Creates a handler for a POST endpoint
23
+ */
24
+ export declare function createPostHandler(endpoint: string, responseData: JsonValue): import("msw").HttpHandler;
25
+ /**
26
+ * Export http from msw for custom handlers
27
+ */
28
+ export { http, HttpResponse };
@@ -0,0 +1 @@
1
+ export declare const server: import("msw/node").SetupServer;