@todoist/comms-sdk 0.0.0-stage → 5.0.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.
- package/LICENSE +21 -0
- package/README.md +187 -2
- 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 +508 -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 +81 -5
|
@@ -0,0 +1,508 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { getFullCommsURL } from '../utils/url-helpers.js';
|
|
3
|
+
import { USER_TYPES } from './enums.js';
|
|
4
|
+
// EVERYONE / EVERYONE_IN_THREAD / GROUP_ID_MARKERS / GroupId / GroupIdMarker
|
|
5
|
+
// are defined in `./enums` (re-exported through `./index`) to keep this
|
|
6
|
+
// module from depending back on `./enums` for them. They're available
|
|
7
|
+
// from the same public surface (`@todoist/comms-sdk`) either way.
|
|
8
|
+
// Reusable schema for system messages that can be either a string or an
|
|
9
|
+
// object. Nullable — the backend returns `null` when there is no system
|
|
10
|
+
// message.
|
|
11
|
+
export const SystemMessageSchema = z.union([z.string(), z.unknown()]).nullable().optional();
|
|
12
|
+
/**
|
|
13
|
+
* Shared `{ status: "ok" }` response shape. Pinned to the literal `'ok'`
|
|
14
|
+
* so a regression on the backend (e.g. a status code change) surfaces as
|
|
15
|
+
* a parse error here instead of being silently typed away. Most write
|
|
16
|
+
* endpoints that don't return an entity use this — archive / unarchive /
|
|
17
|
+
* mark-read / mark-all-read / mute / clear-unread / etc.
|
|
18
|
+
*/
|
|
19
|
+
export const StatusOkSchema = z.object({ status: z.literal('ok') });
|
|
20
|
+
export const HookSubscribeResponseSchema = StatusOkSchema.extend({
|
|
21
|
+
id: z.number().int(),
|
|
22
|
+
});
|
|
23
|
+
// Attachment entity from API. Mirrors the canonical backend shape produced
|
|
24
|
+
// by `unify_attachments` / `validate_file_attachment_json`. Only
|
|
25
|
+
// `attachmentId` and `urlType` are guaranteed; everything else depends on
|
|
26
|
+
// the attachment kind (file vs image vs link preview vs unfurled GIF).
|
|
27
|
+
// Loose: unknown keys from the backend pass through rather than being
|
|
28
|
+
// stripped, so newly-added or off-spec fields stay accessible to callers.
|
|
29
|
+
const attachmentShape = {
|
|
30
|
+
attachmentId: z.string(),
|
|
31
|
+
urlType: z.string(),
|
|
32
|
+
title: z.string().nullable().optional(),
|
|
33
|
+
url: z.string().nullable().optional(),
|
|
34
|
+
fileName: z.string().nullable().optional(),
|
|
35
|
+
fileSize: z.number().int().nonnegative().nullable().optional(),
|
|
36
|
+
underlyingType: z.string().nullable().optional(),
|
|
37
|
+
description: z.string().nullable().optional(),
|
|
38
|
+
image: z.string().nullable().optional(),
|
|
39
|
+
imageWidth: z.number().int().nonnegative().nullable().optional(),
|
|
40
|
+
imageHeight: z.number().int().nonnegative().nullable().optional(),
|
|
41
|
+
duration: z.string().nullable().optional(),
|
|
42
|
+
uploadState: z.string().nullable().optional(),
|
|
43
|
+
video: z.string().nullable().optional(),
|
|
44
|
+
videoType: z.string().nullable().optional(),
|
|
45
|
+
videoAutoPlay: z.boolean().nullable().optional(),
|
|
46
|
+
};
|
|
47
|
+
export const AttachmentSchema = z.object(attachmentShape).loose();
|
|
48
|
+
// Request-side attachment schema. Unlike the loose response `AttachmentSchema`,
|
|
49
|
+
// this strips unknown keys so caller typos / off-spec fields are dropped instead
|
|
50
|
+
// of being forwarded on the wire. Use this for `*Args` request schemas.
|
|
51
|
+
export const RequestAttachmentSchema = z.object(attachmentShape);
|
|
52
|
+
// Clients that don't model `scope` can store `{}`, and the backend omits unset fields.
|
|
53
|
+
export const StatusEffectSchema = z.object({
|
|
54
|
+
scope: z.object({ mode: z.string().optional() }).optional(),
|
|
55
|
+
});
|
|
56
|
+
// Shared user status. It lives on the Todoist account, so Comms, Todoist and
|
|
57
|
+
// automations all see the same one. `activeUntil` is an RFC 3339 string, and an
|
|
58
|
+
// expired status is returned as `null` rather than as an expired object.
|
|
59
|
+
export const UserStatusSchema = z.object({
|
|
60
|
+
message: z.string(),
|
|
61
|
+
emoji: z.string().nullable().optional(),
|
|
62
|
+
activeUntil: z.string().nullable().optional(),
|
|
63
|
+
effects: z
|
|
64
|
+
.object({
|
|
65
|
+
pauseNotifications: StatusEffectSchema.optional(),
|
|
66
|
+
pauseActivity: StatusEffectSchema.optional(),
|
|
67
|
+
})
|
|
68
|
+
.optional(),
|
|
69
|
+
});
|
|
70
|
+
// Fields shared by `User` and `WorkspaceUser`. Profile fields
|
|
71
|
+
// (`fullName`, `imageId`, avatar URLs) are sourced from Todoist-ID.
|
|
72
|
+
export const BaseUserSchema = z.object({
|
|
73
|
+
id: z.number(),
|
|
74
|
+
fullName: z.string(),
|
|
75
|
+
shortName: z.string(),
|
|
76
|
+
firstName: z.string().nullable().optional(),
|
|
77
|
+
timezone: z.string(),
|
|
78
|
+
removed: z.boolean(),
|
|
79
|
+
imageId: z.string().nullable().optional(),
|
|
80
|
+
avatarUrls: z
|
|
81
|
+
.object({
|
|
82
|
+
s35: z.string(),
|
|
83
|
+
s60: z.string(),
|
|
84
|
+
s195: z.string(),
|
|
85
|
+
s640: z.string(),
|
|
86
|
+
})
|
|
87
|
+
.nullable()
|
|
88
|
+
.optional(),
|
|
89
|
+
restricted: z.boolean().nullable().optional(),
|
|
90
|
+
setupPending: z.boolean().nullable().optional(),
|
|
91
|
+
status: UserStatusSchema.nullable().optional(),
|
|
92
|
+
});
|
|
93
|
+
// User entity from API.
|
|
94
|
+
export const UserSchema = BaseUserSchema.extend({
|
|
95
|
+
email: z.email(),
|
|
96
|
+
clientId: z.string().nullable().optional(),
|
|
97
|
+
cometChannel: z.string().nullable().optional(),
|
|
98
|
+
lang: z.string(),
|
|
99
|
+
cometServer: z.string().nullable().optional(),
|
|
100
|
+
token: z.string().nullable().optional(),
|
|
101
|
+
scheduledBanners: z.array(z.string()).nullable().optional(),
|
|
102
|
+
});
|
|
103
|
+
// Workspace entity from API. `default_conversation` is a base58 UUIDv7
|
|
104
|
+
// string. `avatar_id` is kept (unlike the User rename to `image_id`,
|
|
105
|
+
// which is a User-only change per Comms_API_changes.md PR #125).
|
|
106
|
+
// `plan` is intentionally `z.string()` — see {@link WORKSPACE_PLANS}.
|
|
107
|
+
export const WorkspaceSchema = z.object({
|
|
108
|
+
id: z.number(),
|
|
109
|
+
name: z.string(),
|
|
110
|
+
defaultConversation: z.string().nullable().optional(),
|
|
111
|
+
creator: z.number(),
|
|
112
|
+
created: z.date(),
|
|
113
|
+
avatarId: z.string().nullable().optional(),
|
|
114
|
+
avatarUrls: z
|
|
115
|
+
.object({
|
|
116
|
+
s35: z.string(),
|
|
117
|
+
s60: z.string(),
|
|
118
|
+
s195: z.string(),
|
|
119
|
+
s640: z.string(),
|
|
120
|
+
})
|
|
121
|
+
.nullable()
|
|
122
|
+
.optional(),
|
|
123
|
+
plan: z.string().nullable().optional(),
|
|
124
|
+
/** Largest file `attachments.upload()` accepts in this workspace, in MiB (× 1024²). */
|
|
125
|
+
uploadLimitMb: z.number().nullable().optional(),
|
|
126
|
+
});
|
|
127
|
+
export const ChannelObjectSchema = z.object({
|
|
128
|
+
id: z.string(),
|
|
129
|
+
name: z.string(),
|
|
130
|
+
description: z.string().nullable().optional(),
|
|
131
|
+
creator: z.number(),
|
|
132
|
+
userIds: z.array(z.number()).nullable().optional(),
|
|
133
|
+
color: z.number().nullable().optional(),
|
|
134
|
+
public: z.boolean(),
|
|
135
|
+
workspaceId: z.number(),
|
|
136
|
+
archived: z.boolean(),
|
|
137
|
+
created: z.date(),
|
|
138
|
+
useDefaultRecipients: z.boolean().nullable().optional(),
|
|
139
|
+
defaultGroups: z.array(z.string()).nullable().optional(),
|
|
140
|
+
defaultRecipients: z.array(z.number()).nullable().optional(),
|
|
141
|
+
isFavorited: z.boolean().nullable().optional(),
|
|
142
|
+
icon: z.number().nullable().optional(),
|
|
143
|
+
version: z.number(),
|
|
144
|
+
filters: z.record(z.string(), z.string()).nullable().optional(),
|
|
145
|
+
});
|
|
146
|
+
export function createChannelSchema(linkBaseUrl) {
|
|
147
|
+
return ChannelObjectSchema.transform((data) => ({
|
|
148
|
+
...data,
|
|
149
|
+
url: getFullCommsURL({ workspaceId: data.workspaceId, channelId: data.id }, linkBaseUrl),
|
|
150
|
+
}));
|
|
151
|
+
}
|
|
152
|
+
export const ChannelSchema = createChannelSchema();
|
|
153
|
+
// Thread entity from API. `pinned` (boolean) and `pinnedDate` are both
|
|
154
|
+
// surfaced — `pinned` is kept for Zapier/webhook clients.
|
|
155
|
+
export const ThreadObjectSchema = z.object({
|
|
156
|
+
id: z.string(),
|
|
157
|
+
title: z.string(),
|
|
158
|
+
content: z.string(),
|
|
159
|
+
creator: z.number(),
|
|
160
|
+
creatorName: z.string().nullable().optional(),
|
|
161
|
+
channelId: z.string(),
|
|
162
|
+
workspaceId: z.number(),
|
|
163
|
+
actions: z.array(z.unknown()).nullable().optional(),
|
|
164
|
+
attachments: z.array(AttachmentSchema).nullable().optional(),
|
|
165
|
+
commentCount: z.number(),
|
|
166
|
+
closed: z.boolean().nullable().optional(),
|
|
167
|
+
directGroupMentions: z.array(z.string()).nullable().optional(),
|
|
168
|
+
directMentions: z.array(z.number()).nullable().optional(),
|
|
169
|
+
groups: z.array(z.string()).nullable().optional(),
|
|
170
|
+
lastEdited: z.date().nullable().optional(),
|
|
171
|
+
lastObjIndex: z.number().nullable().optional(),
|
|
172
|
+
lastUpdated: z.date(),
|
|
173
|
+
mutedUntil: z.date().nullable().optional(),
|
|
174
|
+
participants: z.array(z.number()).nullable().optional(),
|
|
175
|
+
// Backend wire shape only includes `pinned_ts` (epoch seconds or null);
|
|
176
|
+
// response normalization exposes that timestamp as `pinnedDate`.
|
|
177
|
+
pinned: z.boolean().optional(),
|
|
178
|
+
pinnedDate: z.date().nullable().optional(),
|
|
179
|
+
posted: z.date(),
|
|
180
|
+
reactions: z.record(z.string(), z.unknown()).nullable().optional(),
|
|
181
|
+
recipients: z.array(z.number()).nullable().optional(),
|
|
182
|
+
responders: z.array(z.number()).nullable().optional(),
|
|
183
|
+
snippet: z.string(),
|
|
184
|
+
snippetCreator: z.number(),
|
|
185
|
+
snippetMaskAvatarUrl: z.string().nullable().optional(),
|
|
186
|
+
snippetMaskPoster: z.string().nullable().optional(),
|
|
187
|
+
systemMessage: SystemMessageSchema,
|
|
188
|
+
toEmails: z.array(z.string()).nullable().optional(),
|
|
189
|
+
isArchived: z.boolean(),
|
|
190
|
+
isSaved: z.boolean().nullable().optional(),
|
|
191
|
+
inInbox: z.boolean().nullable().optional(),
|
|
192
|
+
lastComment: z
|
|
193
|
+
.object({
|
|
194
|
+
id: z.string(),
|
|
195
|
+
content: z.string(),
|
|
196
|
+
creator: z.number(),
|
|
197
|
+
creatorName: z.string(),
|
|
198
|
+
threadId: z.string(),
|
|
199
|
+
channelId: z.string(),
|
|
200
|
+
posted: z.date(),
|
|
201
|
+
systemMessage: SystemMessageSchema,
|
|
202
|
+
attachments: z.array(AttachmentSchema).nullable().optional(),
|
|
203
|
+
reactions: z.record(z.string(), z.array(z.number())).nullable().optional(),
|
|
204
|
+
actions: z.array(z.unknown()).nullable().optional(),
|
|
205
|
+
objIndex: z.number(),
|
|
206
|
+
lastEdited: z.date().nullable().optional(),
|
|
207
|
+
deleted: z.boolean(),
|
|
208
|
+
deletedBy: z.number().nullable().optional(),
|
|
209
|
+
directGroupMentions: z.array(z.string()).nullable().optional(),
|
|
210
|
+
directMentions: z.array(z.number()).nullable().optional(),
|
|
211
|
+
groups: z.array(z.string()).nullable().optional(),
|
|
212
|
+
recipients: z.array(z.number()).nullable().optional(),
|
|
213
|
+
toEmails: z.array(z.string()).nullable().optional(),
|
|
214
|
+
version: z.number(),
|
|
215
|
+
workspaceId: z.number(),
|
|
216
|
+
})
|
|
217
|
+
.nullable()
|
|
218
|
+
.optional(),
|
|
219
|
+
});
|
|
220
|
+
export function createThreadSchema(linkBaseUrl) {
|
|
221
|
+
return ThreadObjectSchema.transform((data) => ({
|
|
222
|
+
...data,
|
|
223
|
+
url: getFullCommsURL({
|
|
224
|
+
workspaceId: data.workspaceId,
|
|
225
|
+
channelId: data.channelId,
|
|
226
|
+
threadId: data.id,
|
|
227
|
+
}, linkBaseUrl),
|
|
228
|
+
}));
|
|
229
|
+
}
|
|
230
|
+
export const ThreadSchema = createThreadSchema();
|
|
231
|
+
// Group entity from API. The broadcast markers `EVERYONE` and
|
|
232
|
+
// `EVERYONE_IN_THREAD` can appear in place of a real `id` in group-bearing
|
|
233
|
+
// fields on threads/comments/channels.
|
|
234
|
+
export const GroupSchema = z.object({
|
|
235
|
+
id: z.string(),
|
|
236
|
+
name: z.string(),
|
|
237
|
+
description: z.string().nullable().optional(),
|
|
238
|
+
workspaceId: z.number(),
|
|
239
|
+
userIds: z.array(z.number()),
|
|
240
|
+
version: z.number(),
|
|
241
|
+
});
|
|
242
|
+
// Conversation entity from API.
|
|
243
|
+
export const ConversationObjectSchema = z.object({
|
|
244
|
+
id: z.string(),
|
|
245
|
+
workspaceId: z.number(),
|
|
246
|
+
userIds: z.array(z.number()),
|
|
247
|
+
messageCount: z.number().nullable().optional(),
|
|
248
|
+
lastObjIndex: z.number(),
|
|
249
|
+
snippet: z.string(),
|
|
250
|
+
snippetCreators: z.array(z.number()),
|
|
251
|
+
lastActive: z.date(),
|
|
252
|
+
mutedUntil: z.date().nullable().optional(),
|
|
253
|
+
archived: z.boolean(),
|
|
254
|
+
created: z.date(),
|
|
255
|
+
creator: z.number(),
|
|
256
|
+
title: z.string().nullable().optional(),
|
|
257
|
+
private: z.boolean().nullable().optional(),
|
|
258
|
+
lastMessage: z
|
|
259
|
+
.object({
|
|
260
|
+
// `id` may be string or number depending on the endpoint; coerced.
|
|
261
|
+
id: z.union([z.string(), z.number()]).transform(String),
|
|
262
|
+
content: z.string(),
|
|
263
|
+
creator: z.number(),
|
|
264
|
+
conversationId: z.string(),
|
|
265
|
+
posted: z.date(),
|
|
266
|
+
systemMessage: SystemMessageSchema,
|
|
267
|
+
attachments: z.array(AttachmentSchema).nullable().optional(),
|
|
268
|
+
reactions: z.record(z.string(), z.array(z.number())).nullable().optional(),
|
|
269
|
+
actions: z.array(z.unknown()).nullable().optional(),
|
|
270
|
+
objIndex: z.number().nullable().optional(),
|
|
271
|
+
lastEdited: z.date().nullable().optional(),
|
|
272
|
+
deleted: z.boolean().nullable().optional(),
|
|
273
|
+
directGroupMentions: z.array(z.string()).nullable().optional(),
|
|
274
|
+
directMentions: z.array(z.number()).nullable().optional(),
|
|
275
|
+
version: z.number().nullable().optional(),
|
|
276
|
+
workspaceId: z.number().nullable().optional(),
|
|
277
|
+
})
|
|
278
|
+
.nullable()
|
|
279
|
+
.optional(),
|
|
280
|
+
});
|
|
281
|
+
export function createConversationSchema(linkBaseUrl) {
|
|
282
|
+
return ConversationObjectSchema.transform((data) => ({
|
|
283
|
+
...data,
|
|
284
|
+
url: getFullCommsURL({ workspaceId: data.workspaceId, conversationId: data.id }, linkBaseUrl),
|
|
285
|
+
}));
|
|
286
|
+
}
|
|
287
|
+
export const ConversationSchema = createConversationSchema();
|
|
288
|
+
export const CommentObjectSchema = z.object({
|
|
289
|
+
id: z.string(),
|
|
290
|
+
content: z.string(),
|
|
291
|
+
creator: z.number(),
|
|
292
|
+
threadId: z.string(),
|
|
293
|
+
workspaceId: z.number(),
|
|
294
|
+
conversationId: z.string().nullable().optional(),
|
|
295
|
+
posted: z.date(),
|
|
296
|
+
lastEdited: z.date().nullable().optional(),
|
|
297
|
+
directMentions: z.array(z.number()).nullable().optional(),
|
|
298
|
+
directGroupMentions: z.array(z.string()).nullable().optional(),
|
|
299
|
+
systemMessage: SystemMessageSchema,
|
|
300
|
+
attachments: z.array(AttachmentSchema).nullable().optional(),
|
|
301
|
+
reactions: z.record(z.string(), z.unknown()).nullable().optional(),
|
|
302
|
+
objIndex: z.number().nullable().optional(),
|
|
303
|
+
creatorName: z.string().nullable().optional(),
|
|
304
|
+
channelId: z.string(),
|
|
305
|
+
recipients: z.array(z.number()).nullable().optional(),
|
|
306
|
+
groups: z.array(z.string()).nullable().optional(),
|
|
307
|
+
toEmails: z.array(z.string()).nullable().optional(),
|
|
308
|
+
deleted: z.boolean().nullable().optional(),
|
|
309
|
+
deletedBy: z.number().nullable().optional(),
|
|
310
|
+
version: z.number().nullable().optional(),
|
|
311
|
+
actions: z.array(z.unknown()).nullable().optional(),
|
|
312
|
+
});
|
|
313
|
+
export function createCommentSchema(linkBaseUrl) {
|
|
314
|
+
return CommentObjectSchema.transform((data) => ({
|
|
315
|
+
...data,
|
|
316
|
+
url: getFullCommsURL({
|
|
317
|
+
workspaceId: data.workspaceId,
|
|
318
|
+
channelId: data.channelId,
|
|
319
|
+
threadId: data.threadId,
|
|
320
|
+
commentId: data.id,
|
|
321
|
+
}, linkBaseUrl),
|
|
322
|
+
}));
|
|
323
|
+
}
|
|
324
|
+
export const CommentSchema = createCommentSchema();
|
|
325
|
+
export const WorkspaceUserSchema = BaseUserSchema.extend({
|
|
326
|
+
email: z.string().nullable().optional(),
|
|
327
|
+
userType: z.enum(USER_TYPES),
|
|
328
|
+
dateFormat: z.string().nullable().optional(),
|
|
329
|
+
theme: z.number().int().nullable().optional(),
|
|
330
|
+
timeFormat: z.string().nullable().optional(),
|
|
331
|
+
version: z.number(),
|
|
332
|
+
});
|
|
333
|
+
// Reduced user shape the backend substitutes when the viewer may not see a
|
|
334
|
+
// user's full profile — the user has been removed from the workspace, or the
|
|
335
|
+
// viewer is a guest with no visibility of them. `full_name` / `short_name`
|
|
336
|
+
// carry the first name only, and neither `timezone` nor `user_type` is sent,
|
|
337
|
+
// so those cannot be modelled on this branch.
|
|
338
|
+
export const RestrictedWorkspaceUserSchema = BaseUserSchema.omit({ timezone: true }).extend({
|
|
339
|
+
restricted: z.literal(true),
|
|
340
|
+
version: z.number(),
|
|
341
|
+
});
|
|
342
|
+
// A workspace user as the current viewer sees them. Endpoints that resolve a
|
|
343
|
+
// single user by id or email return either shape, discriminated by
|
|
344
|
+
// `restricted`; narrow with {@link isRestrictedWorkspaceUser}. Endpoints that
|
|
345
|
+
// list a workspace's own members always return the full shape.
|
|
346
|
+
export const VisibleWorkspaceUserSchema = z.union([
|
|
347
|
+
WorkspaceUserSchema,
|
|
348
|
+
RestrictedWorkspaceUserSchema,
|
|
349
|
+
]);
|
|
350
|
+
/**
|
|
351
|
+
* Narrows a {@link VisibleWorkspaceUser} to the reduced shape, which has no
|
|
352
|
+
* `timezone` and no `userType`.
|
|
353
|
+
*
|
|
354
|
+
* @param user - The user to check.
|
|
355
|
+
* @returns `true` when the viewer only gets the restricted profile.
|
|
356
|
+
*
|
|
357
|
+
* @example
|
|
358
|
+
* ```typescript
|
|
359
|
+
* const user = await api.workspaceUsers.getUserById({ workspaceId: 123, userId: 456 })
|
|
360
|
+
* const zone = isRestrictedWorkspaceUser(user) ? 'UTC' : user.timezone
|
|
361
|
+
* ```
|
|
362
|
+
*/
|
|
363
|
+
export function isRestrictedWorkspaceUser(user) {
|
|
364
|
+
return user.restricted === true;
|
|
365
|
+
}
|
|
366
|
+
// ConversationMessage entity from API. `id` is widened to `string | number`
|
|
367
|
+
// (coerced to a string post-parse) because the backend currently emits
|
|
368
|
+
// either shape depending on the endpoint; the URL/reaction helpers accept
|
|
369
|
+
// both.
|
|
370
|
+
export const ConversationMessageObjectSchema = z.object({
|
|
371
|
+
id: z.union([z.string(), z.number()]).transform(String),
|
|
372
|
+
content: z.string(),
|
|
373
|
+
creator: z.number(),
|
|
374
|
+
conversationId: z.string(),
|
|
375
|
+
posted: z.date(),
|
|
376
|
+
systemMessage: SystemMessageSchema,
|
|
377
|
+
attachments: z.array(AttachmentSchema).nullable().optional(),
|
|
378
|
+
reactions: z.record(z.string(), z.array(z.number())).nullable().optional(),
|
|
379
|
+
actions: z.array(z.unknown()).nullable().optional(),
|
|
380
|
+
objIndex: z.number().nullable().optional(),
|
|
381
|
+
lastEdited: z.date().nullable().optional(),
|
|
382
|
+
isDeleted: z.boolean().nullable().optional(),
|
|
383
|
+
directGroupMentions: z.array(z.string()).nullable().optional(),
|
|
384
|
+
directMentions: z.array(z.number()).nullable().optional(),
|
|
385
|
+
version: z.number().nullable().optional(),
|
|
386
|
+
workspaceId: z.number(),
|
|
387
|
+
});
|
|
388
|
+
export function createConversationMessageSchema(linkBaseUrl) {
|
|
389
|
+
return ConversationMessageObjectSchema.transform((data) => ({
|
|
390
|
+
...data,
|
|
391
|
+
url: getFullCommsURL({
|
|
392
|
+
workspaceId: data.workspaceId,
|
|
393
|
+
conversationId: data.conversationId,
|
|
394
|
+
messageId: data.id,
|
|
395
|
+
}, linkBaseUrl),
|
|
396
|
+
}));
|
|
397
|
+
}
|
|
398
|
+
export const ConversationMessageSchema = createConversationMessageSchema();
|
|
399
|
+
// InboxThread entity from API - returns full Thread objects with additional inbox metadata.
|
|
400
|
+
export function createInboxThreadObjectSchema(linkBaseUrl) {
|
|
401
|
+
return z.object({
|
|
402
|
+
id: z.string(),
|
|
403
|
+
title: z.string(),
|
|
404
|
+
content: z.string(),
|
|
405
|
+
creator: z.number(),
|
|
406
|
+
creatorName: z.string().nullable().optional(),
|
|
407
|
+
channelId: z.string(),
|
|
408
|
+
workspaceId: z.number(),
|
|
409
|
+
actions: z.array(z.unknown()).nullable().optional(),
|
|
410
|
+
attachments: z.array(AttachmentSchema).nullable().optional(),
|
|
411
|
+
commentCount: z.number(),
|
|
412
|
+
directGroupMentions: z.array(z.string()).nullable().optional(),
|
|
413
|
+
directMentions: z.array(z.number()).nullable().optional(),
|
|
414
|
+
groups: z.array(z.string()).nullable().optional(),
|
|
415
|
+
lastEdited: z.date().nullable().optional(),
|
|
416
|
+
lastObjIndex: z.number().nullable().optional(),
|
|
417
|
+
lastUpdated: z.date(),
|
|
418
|
+
mutedUntil: z.date().nullable().optional(),
|
|
419
|
+
participants: z.array(z.number()).nullable().optional(),
|
|
420
|
+
// Backend wire shape only includes `pinned_ts` (epoch seconds or null);
|
|
421
|
+
// response normalization exposes that timestamp as `pinnedDate`.
|
|
422
|
+
pinned: z.boolean().optional(),
|
|
423
|
+
pinnedDate: z.date().nullable().optional(),
|
|
424
|
+
posted: z.date(),
|
|
425
|
+
reactions: z.record(z.string(), z.array(z.number())).nullable().optional(),
|
|
426
|
+
recipients: z.array(z.number()).nullable().optional(),
|
|
427
|
+
snippet: z.string(),
|
|
428
|
+
snippetCreator: z.number(),
|
|
429
|
+
snippetMaskAvatarUrl: z.string().nullable().optional(),
|
|
430
|
+
snippetMaskPoster: z.string().nullable().optional(),
|
|
431
|
+
systemMessage: SystemMessageSchema,
|
|
432
|
+
isArchived: z.boolean(),
|
|
433
|
+
inInbox: z.boolean(),
|
|
434
|
+
isSaved: z.boolean().nullable().optional(),
|
|
435
|
+
closed: z.boolean(),
|
|
436
|
+
responders: z.array(z.number()).nullable().optional(),
|
|
437
|
+
lastComment: createCommentSchema(linkBaseUrl).nullable().optional(),
|
|
438
|
+
toEmails: z.array(z.string()).nullable().optional(),
|
|
439
|
+
version: z.number().nullable().optional(),
|
|
440
|
+
});
|
|
441
|
+
}
|
|
442
|
+
export function createInboxThreadSchema(linkBaseUrl) {
|
|
443
|
+
return createInboxThreadObjectSchema(linkBaseUrl).transform((data) => ({
|
|
444
|
+
...data,
|
|
445
|
+
url: getFullCommsURL({
|
|
446
|
+
workspaceId: data.workspaceId,
|
|
447
|
+
channelId: data.channelId,
|
|
448
|
+
threadId: data.id,
|
|
449
|
+
}, linkBaseUrl),
|
|
450
|
+
}));
|
|
451
|
+
}
|
|
452
|
+
export const InboxThreadSchema = createInboxThreadSchema();
|
|
453
|
+
// UnreadThread entity from API - simplified thread reference.
|
|
454
|
+
export const UnreadThreadSchema = z.object({
|
|
455
|
+
threadId: z.string(),
|
|
456
|
+
channelId: z.string(),
|
|
457
|
+
objIndex: z.number(),
|
|
458
|
+
directMention: z.boolean(),
|
|
459
|
+
});
|
|
460
|
+
// UnreadConversation entity from API - simplified conversation reference.
|
|
461
|
+
export const UnreadConversationSchema = z.object({
|
|
462
|
+
conversationId: z.string(),
|
|
463
|
+
objIndex: z.number(),
|
|
464
|
+
directMention: z.boolean(),
|
|
465
|
+
});
|
|
466
|
+
// SearchResult entity from API.
|
|
467
|
+
// The API emits 'thread' and 'conversation' results: a match inside a
|
|
468
|
+
// comment is returned as a 'thread' result with `commentId` set, and a match inside a
|
|
469
|
+
// message as a 'conversation' result with `messageId` set.
|
|
470
|
+
const searchResultBaseShape = {
|
|
471
|
+
/**
|
|
472
|
+
* Opaque search-result key in the form `thread_<threadId>` or
|
|
473
|
+
* `conversation_<conversationId>`. Unique per result; not a Comms object id — use
|
|
474
|
+
* `threadId`, `conversationId`, `commentId`, or `messageId` to reference objects.
|
|
475
|
+
*/
|
|
476
|
+
id: z.string(),
|
|
477
|
+
snippet: z.string(),
|
|
478
|
+
snippetCreatorId: z.number(),
|
|
479
|
+
snippetLastUpdated: z.date(),
|
|
480
|
+
channelId: z.string().nullable().optional(),
|
|
481
|
+
channelName: z.string().nullable().optional(),
|
|
482
|
+
channelColor: z.number().nullable().optional(),
|
|
483
|
+
title: z.string().nullable().optional(),
|
|
484
|
+
closed: z.boolean().nullable().optional(),
|
|
485
|
+
};
|
|
486
|
+
export const SEARCH_RESULT_TYPES = ['thread', 'conversation'];
|
|
487
|
+
export const ThreadSearchResultSchema = z.object({
|
|
488
|
+
...searchResultBaseShape,
|
|
489
|
+
type: z.literal('thread'),
|
|
490
|
+
/** The owning thread id. */
|
|
491
|
+
threadId: z.string(),
|
|
492
|
+
/** The matched comment id, set when the match is a comment. */
|
|
493
|
+
commentId: z.string().nullable().optional(),
|
|
494
|
+
});
|
|
495
|
+
export const ConversationSearchResultSchema = z.object({
|
|
496
|
+
...searchResultBaseShape,
|
|
497
|
+
type: z.literal('conversation'),
|
|
498
|
+
/** The owning conversation id. */
|
|
499
|
+
conversationId: z.string(),
|
|
500
|
+
/** The matched message id. Absent when the match is the conversation's title. */
|
|
501
|
+
messageId: z.union([z.string(), z.number()]).transform(String).nullable().optional(),
|
|
502
|
+
/** The conversation's members. */
|
|
503
|
+
userIds: z.array(z.number()).optional(),
|
|
504
|
+
});
|
|
505
|
+
export const SearchResultSchema = z.discriminatedUnion('type', [
|
|
506
|
+
ThreadSearchResultSchema,
|
|
507
|
+
ConversationSearchResultSchema,
|
|
508
|
+
]);
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Marker constants for the two "broadcast" group recipients. These appear
|
|
3
|
+
* in group-bearing fields (`Thread.groups`, `Comment.groups`,
|
|
4
|
+
* `Channel.defaultGroups`, `directGroupMentions`, etc.) in place of a
|
|
5
|
+
* real group ID and tell the backend to notify "everyone in the channel"
|
|
6
|
+
* or "everyone in the thread" respectively. Input and output are
|
|
7
|
+
* symmetric. Defined here (and not in `./entities`) so that `enums`
|
|
8
|
+
* stays leaf-level — `entities` imports from `enums`, never the reverse.
|
|
9
|
+
*/
|
|
10
|
+
export const EVERYONE = 'EVERYONE';
|
|
11
|
+
export const EVERYONE_IN_THREAD = 'EVERYONE_IN_THREAD';
|
|
12
|
+
/** Union of the two broadcast group markers. */
|
|
13
|
+
export const GROUP_ID_MARKERS = [EVERYONE, EVERYONE_IN_THREAD];
|
|
14
|
+
// User types for workspace users
|
|
15
|
+
export const USER_TYPES = ['USER', 'GUEST', 'ADMIN'];
|
|
16
|
+
// Workspace plans. The known values today are `'free'`, `'unlimited'`,
|
|
17
|
+
// and `'business'`, but the backend can introduce new plan names without
|
|
18
|
+
// coordinating a SDK release — so the schema accepts any string and the
|
|
19
|
+
// const array stays as a hint for autocomplete only.
|
|
20
|
+
export const WORKSPACE_PLANS = ['free', 'unlimited', 'business'];
|
|
21
|
+
// Audiences that comment-creating endpoints can target alongside (or instead
|
|
22
|
+
// of) individual `recipients` / custom `groups`.
|
|
23
|
+
export const NOTIFY_AUDIENCES = ['channel', 'thread'];
|
|
24
|
+
/**
|
|
25
|
+
* Internal mapping from {@link NotifyAudience} to the broadcast marker IDs
|
|
26
|
+
* (`EVERYONE` / `EVERYONE_IN_THREAD`) that comment- and thread-creation
|
|
27
|
+
* endpoints use on the wire. SDK consumers should use {@link NotifyAudience}
|
|
28
|
+
* via `notifyAudience` on the request args rather than passing these IDs
|
|
29
|
+
* directly.
|
|
30
|
+
*/
|
|
31
|
+
export const NOTIFY_AUDIENCE_GROUP_IDS = {
|
|
32
|
+
channel: EVERYONE,
|
|
33
|
+
thread: EVERYONE_IN_THREAD,
|
|
34
|
+
};
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { CustomError } from 'ts-custom-error';
|
|
2
|
+
export class CommsRequestError extends CustomError {
|
|
3
|
+
constructor(message, httpStatusCode, responseData, options) {
|
|
4
|
+
super(message, options);
|
|
5
|
+
this.httpStatusCode = httpStatusCode;
|
|
6
|
+
this.responseData = responseData;
|
|
7
|
+
}
|
|
8
|
+
}
|
|
9
|
+
function hasStatus(error, status) {
|
|
10
|
+
return error instanceof CommsRequestError && error.httpStatusCode === status;
|
|
11
|
+
}
|
|
12
|
+
function getResponseField(error, field) {
|
|
13
|
+
if (!(error instanceof CommsRequestError))
|
|
14
|
+
return undefined;
|
|
15
|
+
const data = error.responseData;
|
|
16
|
+
if (typeof data !== 'object' || data === null || !(field in data))
|
|
17
|
+
return undefined;
|
|
18
|
+
return data[field];
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The numeric `error_code` the API sends in an error body, when there was one.
|
|
22
|
+
*
|
|
23
|
+
* @param error - The thrown value to inspect.
|
|
24
|
+
* @returns The code, or `null` when the error is not a
|
|
25
|
+
* {@link CommsRequestError} or carried no numeric `error_code`.
|
|
26
|
+
*/
|
|
27
|
+
export function getCommsErrorCode(error) {
|
|
28
|
+
const code = getResponseField(error, 'error_code');
|
|
29
|
+
return typeof code === 'number' ? code : null;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The `error_string` the API sends alongside `error_code`, when there was one.
|
|
33
|
+
* It is a server-authored message rather than a stable contract, so branch on
|
|
34
|
+
* {@link getCommsErrorCode} and use this for display.
|
|
35
|
+
*
|
|
36
|
+
* @param error - The thrown value to inspect.
|
|
37
|
+
* @returns The message, or `null` when the error is not a
|
|
38
|
+
* {@link CommsRequestError} or carried no string `error_string`.
|
|
39
|
+
*/
|
|
40
|
+
export function getCommsErrorString(error) {
|
|
41
|
+
const message = getResponseField(error, 'error_string');
|
|
42
|
+
return typeof message === 'string' ? message : null;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* True when the request failed with a 404.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* ```typescript
|
|
49
|
+
* try {
|
|
50
|
+
* await api.threads.getThread(id)
|
|
51
|
+
* } catch (error) {
|
|
52
|
+
* if (isNotFound(error)) return null
|
|
53
|
+
* throw error
|
|
54
|
+
* }
|
|
55
|
+
* ```
|
|
56
|
+
*/
|
|
57
|
+
export function isNotFound(error) {
|
|
58
|
+
return hasStatus(error, 404);
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* True when the request failed with a 409. The API uses this both for genuine
|
|
62
|
+
* conflicts and for a malformed id, so narrow with {@link isMalformedId}
|
|
63
|
+
* before reporting one as the other.
|
|
64
|
+
*/
|
|
65
|
+
export function isConflict(error) {
|
|
66
|
+
return hasStatus(error, 409);
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* True when the API rejected an id as malformed: a 409 carrying `error_code`
|
|
70
|
+
* 217, which it sends both for a value that does not base58-decode to 16 bytes
|
|
71
|
+
* and for one whose version nibble is not 7. That is a bad reference rather
|
|
72
|
+
* than a conflict, so it usually deserves a different message from
|
|
73
|
+
* {@link isConflict}.
|
|
74
|
+
*
|
|
75
|
+
* @example
|
|
76
|
+
* ```typescript
|
|
77
|
+
* if (isMalformedId(error)) throw new Error(`Not a valid Comms id: ${ref}`)
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
80
|
+
export function isMalformedId(error) {
|
|
81
|
+
return isConflict(error) && getCommsErrorCode(error) === 217;
|
|
82
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const HTTP_METHODS = ['POST', 'GET', 'PUT', 'PATCH', 'DELETE'];
|