@todoist/comms-sdk 0.0.1 → 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.
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 +508 -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,84 @@
1
+ /**
2
+ * The title a conversation shows when nobody has named it.
3
+ *
4
+ * The rules come from `@doist/sdk-kmp`, the shared implementation of Comms
5
+ * logic, so titles match the other Comms clients. The wording stays with each
6
+ * caller, which joins the names in the user's language.
7
+ */
8
+ import type { Conversation, WorkspaceUser } from '../types/entities.js';
9
+ /** The ways a conversation's title can be shown. */
10
+ export declare const CONVERSATION_TITLE_TYPES: readonly ["custom", "yourself", "one_to_one", "group", "untitled"];
11
+ /**
12
+ * How to show a {@link ConversationTitle}.
13
+ *
14
+ * @remarks
15
+ * Possible values:
16
+ * - `'custom'` - The conversation's own title, as the only name.
17
+ * - `'yourself'` - Only you are left: your name, as the only name.
18
+ * - `'one_to_one'` - A 1:1: the other person's full name, as the only name.
19
+ * - `'group'` - The names, then "N more" for `othersCount`, then "you" if `includesYou`.
20
+ * - `'untitled'` - There's no name to show, so show your own placeholder.
21
+ */
22
+ export type ConversationTitleType = (typeof CONVERSATION_TITLE_TYPES)[number];
23
+ /** A conversation's title, ready for the caller to word in the user's language. */
24
+ export type ConversationTitle = {
25
+ /** How to show the title. */
26
+ type: ConversationTitleType;
27
+ /** The names to show, in order. */
28
+ names: string[];
29
+ /** For a group, how many more people there are than `names`. */
30
+ othersCount: number;
31
+ /**
32
+ * For a group down to you and one other person, whether to add "you", as in
33
+ * "Bob J. and you", so it doesn't read like your 1:1 with them.
34
+ */
35
+ includesYou: boolean;
36
+ };
37
+ /**
38
+ * Works out the title a conversation shows, as the current user sees it.
39
+ *
40
+ * - A `title` with something visible in it wins: `custom`.
41
+ * - A 1:1 shows the other person's full name: `one_to_one`.
42
+ * - A group shows the others' short names in alphabetical order, ignoring case
43
+ * and accents: `group`. Past `maxNames`, it counts the rest in `othersCount`,
44
+ * though a single person over is named instead.
45
+ * - People removed from the workspace drop out of a group but stay in a 1:1.
46
+ * - A group down to you and one other person sets `includesYou`. Down to you
47
+ * alone, it shows your full name: `yourself`.
48
+ * - With no name to show, the type is `untitled`.
49
+ *
50
+ * `private` only tells a 1:1 from a group of two. Without it, as on a search
51
+ * result, two people read as a 1:1. Past two people the count decides, since
52
+ * chats imported from Twist can be private with three people in them.
53
+ *
54
+ * Someone in `userIds` who isn't in `users` reads as a name that hasn't loaded,
55
+ * so a group counts them rather than naming them.
56
+ *
57
+ * The wording stays with the caller: join `names`, "N more" for `othersCount`
58
+ * and "you" for `includesYou` with a list formatter in the user's language.
59
+ *
60
+ * @param args - The arguments for working out the title.
61
+ * @param args.conversation - The conversation's `title`, `userIds` and `private` flag.
62
+ * @param args.users - The users to take names from. Include people removed from the
63
+ * workspace, so a group can leave them out rather than count them.
64
+ * @param args.currentUserId - The ID of the user viewing the conversation.
65
+ * @param args.maxNames - How many names a group shows before it counts the rest.
66
+ * Defaults to 3, as the Comms apps show. Anything below 1 counts as 1.
67
+ * @returns A new title on every call.
68
+ *
69
+ * @example
70
+ * ```typescript
71
+ * const users = await api.workspaceUsers.getWorkspaceUsers({
72
+ * workspaceId: 123,
73
+ * includeRemoved: true,
74
+ * })
75
+ * const title = getConversationTitle({ conversation, users, currentUserId: me.id })
76
+ * // { type: 'group', names: ['Bob J.', 'Cara S.', 'Dan B.'], othersCount: 2, includesYou: false }
77
+ * ```
78
+ */
79
+ export declare function getConversationTitle(args: {
80
+ conversation: Pick<Conversation, 'title' | 'userIds' | 'private'>;
81
+ users: ReadonlyArray<Pick<WorkspaceUser, 'id' | 'fullName' | 'shortName' | 'removed'>>;
82
+ currentUserId: number;
83
+ maxNames?: number;
84
+ }): ConversationTitle;
@@ -0,0 +1,13 @@
1
+ import type { CustomHeaders } from '../types/http.js';
2
+ /**
3
+ * Merges header records left to right. HTTP header names are case-insensitive,
4
+ * so a later record replaces any earlier header with the same name whatever
5
+ * its case. Without this, a caller's `authorization` would sit alongside the
6
+ * SDK's `Authorization` and `fetch` would join the two into one value.
7
+ */
8
+ export declare function mergeHeaders(...sources: (Record<string, string> | undefined)[]): Record<string, string>;
9
+ /**
10
+ * Turns the `headers` option into the record to send with one request, calling
11
+ * it when it is a function so per-request values are fresh.
12
+ */
13
+ export declare function resolveCustomHeaders(headers: CustomHeaders | undefined): Record<string, string> | undefined;
@@ -0,0 +1,6 @@
1
+ export * from './case-conversion.js';
2
+ export * from './conversation-title.js';
3
+ export type { UploadFile } from './multipart-upload.js';
4
+ export * from './reply-recipients.js';
5
+ export * from './url-helpers.js';
6
+ export * from './uuidv7.js';
@@ -0,0 +1,59 @@
1
+ import type { CustomFetch, CustomHeaders } from '../types/http.js';
2
+ /**
3
+ * File content accepted by the upload helpers.
4
+ *
5
+ * - `Blob`/`File` — browser, or any runtime with a global `Blob` (Node 18+).
6
+ * - `Uint8Array` — raw bytes (requires `fileName`). A Node `Buffer` is a `Uint8Array`,
7
+ * so reading a file with `fs` and passing the result works without conversion.
8
+ *
9
+ * Both are universal types, so the published `.d.ts` stays free of Node-only globals
10
+ * (`Buffer`, `NodeJS.*`) and the helper pulls in no Node built-ins — keeping the browser
11
+ * bundle clean.
12
+ */
13
+ export type UploadFile = Blob | Uint8Array;
14
+ type UploadMultipartFileArgs = {
15
+ /** Base API URI with trailing slash, e.g. `https://comms.todoist.com/api/v1.0/`. */
16
+ baseUrl: string;
17
+ /** API token used for `Authorization: Bearer`. */
18
+ authToken: string;
19
+ /** Relative endpoint path, e.g. `attachments/upload`. */
20
+ endpoint: string;
21
+ /** File content to upload. */
22
+ file: UploadFile;
23
+ /** File name. Required for raw `Uint8Array` bytes; inferred from a `File`. */
24
+ fileName?: string;
25
+ /** MIME type. Defaults to the `Blob`'s type or one inferred from the file extension. */
26
+ contentType?: string;
27
+ /** Extra multipart fields to send alongside the file metadata fields. */
28
+ additionalFields?: Record<string, string | number | boolean | undefined | null>;
29
+ /**
30
+ * Network-error retry count. Defaults to `0` — unlike JSON requests, a retry here
31
+ * resends the entire file body, so large uploads aren't retried automatically.
32
+ */
33
+ maxRetries?: number;
34
+ /** Optional request ID for tracing. */
35
+ requestId?: string;
36
+ /** Optional headers sent with the request. Cannot override `Authorization`, `X-Request-Id` or `Content-Type`. */
37
+ headers?: CustomHeaders;
38
+ /** Optional custom fetch implementation. */
39
+ customFetch?: CustomFetch;
40
+ };
41
+ /**
42
+ * Determine a content-type from a filename extension. Falls back to
43
+ * `application/octet-stream` for unknown extensions.
44
+ */
45
+ export declare function getContentTypeFromFileName(fileName: string): string;
46
+ /**
47
+ * Upload a file using `multipart/form-data`.
48
+ *
49
+ * Encodes the request body as a `Blob` so it works unchanged in the browser and in
50
+ * Node.js, whichever `fetch` ends up sending it. The `file` part is sent alongside `file_name`,
51
+ * `file_size`, and `underlying_type` fields (the canonical Comms upload shape); any
52
+ * `additionalFields` are merged in and override the derived values. Authentication uses
53
+ * `Authorization: Bearer`, matching every other Comms SDK client.
54
+ *
55
+ * The response is JSON-parsed and camel-cased by {@link fetchWithRetry}; callers validate
56
+ * the returned shape with the appropriate schema.
57
+ */
58
+ export declare function uploadMultipartFile<T>(args: UploadMultipartFileArgs): Promise<T>;
59
+ export {};
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Who a new reply in a thread notifies by default.
3
+ *
4
+ * The rule comes from `@doist/sdk-kmp`, the shared implementation of Comms
5
+ * logic, so replies default to the same people as in the other Comms clients.
6
+ */
7
+ import type { Comment, Thread } from '../types/entities.js';
8
+ import { type NotifyAudience } from '../types/enums.js';
9
+ /** The people, groups and audience a new reply notifies by default. */
10
+ export type DefaultReplyRecipients = {
11
+ /** The IDs of the people to notify. Never includes the current user. */
12
+ recipients: number[];
13
+ /** The IDs of the groups to notify, without `EVERYONE` or `EVERYONE_IN_THREAD`. */
14
+ groups: string[];
15
+ /** Everyone in the channel or everyone who interacted with the thread, when notified. */
16
+ notifyAudience: NotifyAudience | null;
17
+ };
18
+ /**
19
+ * Works out who a new reply in a thread notifies by default, as the current
20
+ * user writes it.
21
+ *
22
+ * - The newest comment that counts sets the default: its author, and the
23
+ * people and groups it notified. Deleted comments, system messages (such as
24
+ * closing, reopening or moving the thread) and masked posts from
25
+ * integrations or imports don't count. A comment that notified one person
26
+ * does.
27
+ * - With no comment that counts, the thread sets it the same way, except that
28
+ * a thread to everyone in the channel defaults to everyone who interacted.
29
+ * - Closing a thread, or replying in a closed one, defaults to everyone who
30
+ * interacted, and nobody else.
31
+ * - The current user is never one of the people.
32
+ *
33
+ * Everyone in the channel and everyone who interacted come back as
34
+ * `notifyAudience` rather than in `groups`. If a comment notified both, the
35
+ * channel wins. The lists are always there, empty or not, so the result can be
36
+ * spread straight into `createComment` or `closeThread`.
37
+ *
38
+ * @param args - The arguments for working out the recipients.
39
+ * @param args.thread - The thread's `creator`, `recipients`, `groups` and `closed` flag.
40
+ * @param args.comments - The thread's comments, oldest first, as `getComments` returns them.
41
+ * @param args.currentUserId - The ID of the user writing the reply.
42
+ * @param args.isClosingThread - Whether the reply closes the thread. Defaults to `false`.
43
+ * @returns A new object on every call.
44
+ *
45
+ * @example
46
+ * ```typescript
47
+ * const comments = await api.comments.getComments({ threadId: thread.id })
48
+ * await api.comments.createComment({
49
+ * threadId: thread.id,
50
+ * content: 'On it',
51
+ * ...getDefaultReplyRecipients({ thread, comments, currentUserId: me.id }),
52
+ * })
53
+ * ```
54
+ */
55
+ export declare function getDefaultReplyRecipients(args: {
56
+ thread: Pick<Thread, 'creator' | 'recipients' | 'groups' | 'closed'>;
57
+ comments: ReadonlyArray<Pick<Comment, 'creator' | 'recipients' | 'groups' | 'deleted' | 'systemMessage'>>;
58
+ currentUserId: number;
59
+ isClosingThread?: boolean;
60
+ }): DefaultReplyRecipients;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Converts a Unix timestamp (in seconds) to a Date object.
3
+ * @param timestamp - Unix timestamp in seconds
4
+ * @returns Date object
5
+ */
6
+ export declare function timestampToDate(timestamp: number): Date;
7
+ /**
8
+ * Recursively transforms timestamp fields (ending in 'Ts') in an object to Date objects.
9
+ * Also renames converted fields by removing the 'Ts' suffix.
10
+ * @param obj - The object to transform
11
+ * @returns The transformed object with Date fields
12
+ */
13
+ export declare function transformTimestamps<T>(obj: T): T;
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Helper functions for creating Comms permalinks (`https://comms.todoist.com/...`).
3
+ *
4
+ * Paths come from `@doist/sdk-kmp`, the shared implementation of Comms link
5
+ * routes, so they stay in step with the other Comms clients. The path builders
6
+ * are used rather than the URL builders so that `getFullCommsURL` can keep
7
+ * serving an arbitrary base URL.
8
+ */
9
+ export type CommsURLParams = {
10
+ workspaceId: number;
11
+ channelId?: string;
12
+ conversationId?: string;
13
+ threadId?: string;
14
+ commentId?: string;
15
+ messageId?: string;
16
+ userId?: number;
17
+ };
18
+ /**
19
+ * Builds a relative Comms URL based on the provided parameters
20
+ * @param params - URL parameters including workspace, channel, conversation, thread, etc.
21
+ * @returns A relative URL path
22
+ * @example
23
+ * getCommsURL({ workspaceId: 1, channelId: '7Yp...', threadId: '7Yq...' })
24
+ * // returns '/1/ch/7Yp.../t/7Yq.../'
25
+ */
26
+ export declare function getCommsURL(params: CommsURLParams): string;
27
+ /**
28
+ * Builds a full Comms URL (with protocol and hostname) based on the provided parameters
29
+ * @param params - URL parameters including workspace, channel, conversation, thread, etc.
30
+ * @param baseUrl - Optional base URL (defaults to 'https://comms.todoist.com')
31
+ */
32
+ export declare function getFullCommsURL(params: CommsURLParams, baseUrl?: string): string;
33
+ /** Returns the URL for a thread in a channel. */
34
+ export declare function getThreadURL(params: {
35
+ workspaceId: number;
36
+ channelId: string;
37
+ threadId: string;
38
+ }): string;
39
+ /** Returns the URL for a channel. */
40
+ export declare function getChannelURL(params: {
41
+ workspaceId: number;
42
+ channelId: string;
43
+ }): string;
44
+ /** Returns the URL for a conversation. */
45
+ export declare function getConversationURL(params: {
46
+ workspaceId: number;
47
+ conversationId: string;
48
+ }): string;
49
+ /** Returns the URL for a specific message in a conversation. */
50
+ export declare function getMessageURL(params: {
51
+ workspaceId: number;
52
+ conversationId: string;
53
+ messageId: string;
54
+ }): string;
55
+ /** Returns the URL for a comment in a thread. */
56
+ export declare function getCommentURL(params: {
57
+ workspaceId: number;
58
+ channelId: string;
59
+ threadId: string;
60
+ commentId: string;
61
+ }): string;
62
+ /** Returns the URL for the threads root (channels view). */
63
+ export declare function getThreadsRootURL(workspaceId: number): string;
64
+ /** Returns the URL for the inbox. */
65
+ export declare function getInboxURL(workspaceId: number, tab?: 'done' | 'mentions'): string;
66
+ /** Returns the URL for the messages/conversations root. */
67
+ export declare function getMessagesRootURL(workspaceId: number): string;
68
+ /** Returns the URL for a user profile. */
69
+ export declare function getUserProfileURL(params: {
70
+ workspaceId: number;
71
+ userId: number;
72
+ }): string;
73
+ /** Returns the URL for the saved threads view. */
74
+ export declare function getSavedThreadsRootURL(workspaceId: number): string;
75
+ /** Returns the URL for a saved thread. */
76
+ export declare function getSavedThreadURL(params: {
77
+ workspaceId: number;
78
+ threadId: string;
79
+ }): string;
80
+ /** Returns the URL for a comment on a saved thread. */
81
+ export declare function getSavedThreadCommentURL(params: {
82
+ workspaceId: number;
83
+ threadId: string;
84
+ commentId: string;
85
+ }): string;
86
+ /** Returns the URL for the search root. */
87
+ export declare function getSearchRootURL(workspaceId: number): string;
88
+ /** Returns the URL for a search with a query. */
89
+ export declare function getSearchQueryURL(params: {
90
+ workspaceId: number;
91
+ query: string;
92
+ }): string;
93
+ /** Returns the URL for settings. */
94
+ export declare function getSettingsURL(params: {
95
+ workspaceId: number;
96
+ initialLocation?: string;
97
+ }): string;
98
+ /** Returns the URL for the team members root. */
99
+ export declare function getTeamMembersRootURL(workspaceId: number): string;
100
+ /** The kinds of Comms entity a URL can point at. */
101
+ export declare const COMMS_LINK_TYPES: readonly ["channel", "thread", "thread_comment", "inbox_thread", "inbox_thread_comment", "saved_thread", "saved_thread_comment", "conversation", "message"];
102
+ /** The kind of Comms entity a URL points at. */
103
+ export type CommsLinkType = (typeof COMMS_LINK_TYPES)[number];
104
+ /** The entity a Comms URL points at. */
105
+ export type CommsURLInfo = {
106
+ /** The kind of entity the URL points at. */
107
+ type: CommsLinkType;
108
+ /** The ID of the workspace the entity belongs to. */
109
+ workspaceId: string;
110
+ /** The ID of the channel, when the URL names one. */
111
+ channelId: string | null;
112
+ /** The ID of the thread, when the URL names one. */
113
+ threadId: string | null;
114
+ /** The ID of the comment, when the URL names one. */
115
+ commentId: string | null;
116
+ /** The ID of the conversation, when the URL names one. */
117
+ conversationId: string | null;
118
+ /** The ID of the message, when the URL names one. */
119
+ messageId: string | null;
120
+ /** Whether the URL points at a quoted reference rather than the entity itself. */
121
+ isQuoteReference: boolean;
122
+ };
123
+ /**
124
+ * Parse a Comms URL into the entity it points at.
125
+ *
126
+ * @param url The URL to parse.
127
+ * @returns The entity the URL points at, or `null` if it is not a Comms URL.
128
+ */
129
+ export declare function parseCommsURL(url: string): CommsURLInfo | null;
@@ -0,0 +1,42 @@
1
+ export declare class UuidV7Error extends Error {
2
+ constructor(message: string);
3
+ }
4
+ /** Encode a 16-byte UUID as a base58 string. */
5
+ export declare function encodeUuidToBase58(bytes: Uint8Array): string;
6
+ /**
7
+ * Decode a base58 string back into 16 UUID bytes. Throws {@link UuidV7Error}
8
+ * if the input is malformed or doesn't decode to exactly 16 bytes.
9
+ */
10
+ export declare function decodeBase58ToUuidBytes(value: string): Uint8Array;
11
+ /**
12
+ * Mint a fresh ID. Callers should generate one of these locally when
13
+ * creating a new channel / thread / comment / conversation / message /
14
+ * group — the backend requires the client to supply the ID on create.
15
+ */
16
+ export declare function generateId(): string;
17
+ /** Validate an existing entity ID without minting a replacement. */
18
+ export declare function resolveReferenceId(id: string, fieldName: string): string;
19
+ /**
20
+ * Resolve the `id` for a create-style API call: validate the caller-supplied
21
+ * value (throwing {@link UuidV7Error} before the request leaves the SDK) or
22
+ * mint a fresh one via {@link generateId}.
23
+ */
24
+ export declare function resolveCreateId(id: string | undefined): string;
25
+ /**
26
+ * Validate that a value matches the expected ID format (the decoded bytes
27
+ * have the v7 version nibble + RFC 4122/9562 variant bits). Does NOT
28
+ * validate the embedded timestamp — the backend may still reject a value
29
+ * that is too far in the future or past.
30
+ */
31
+ export declare function isValidUuidV7Base58(value: unknown): value is string;
32
+ /**
33
+ * Encode a canonical UUID string (hyphenated or not, any case) as a
34
+ * wire-format ID. Useful when interoperating with systems that hand you
35
+ * UUIDs in canonical form.
36
+ */
37
+ export declare function base58FromUuidString(uuid: string): string;
38
+ /**
39
+ * Inverse of {@link base58FromUuidString}: takes a wire-format ID and
40
+ * returns the canonical hyphenated UUID string.
41
+ */
42
+ export declare function uuidStringFromBase58(value: string): string;
package/package.json CHANGED
@@ -1,10 +1,82 @@
1
1
  {
2
- "name": "@todoist/comms-sdk",
3
- "version": "0.0.1",
4
- "description": "OIDC trusted publishing setup package for @todoist/comms-sdk",
5
- "keywords": [
6
- "oidc",
7
- "trusted-publishing",
8
- "setup"
9
- ]
2
+ "name": "@todoist/comms-sdk",
3
+ "version": "5.0.0",
4
+ "description": "A TypeScript wrapper for the Comms REST API.",
5
+ "author": "Doist developers",
6
+ "homepage": "https://doist.github.io/comms-sdk-typescript/",
7
+ "repository": "https://github.com/todoist/comms-sdk-typescript",
8
+ "publishConfig": {
9
+ "access": "public",
10
+ "provenance": true
11
+ },
12
+ "license": "MIT",
13
+ "type": "module",
14
+ "engines": {
15
+ "node": ">=24",
16
+ "npm": ">=11"
17
+ },
18
+ "types": "dist/types/index.d.ts",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./dist/types/index.d.ts",
22
+ "default": "./dist/esm/index.js"
23
+ }
24
+ },
25
+ "sideEffects": false,
26
+ "scripts": {
27
+ "clean": "rimraf dist",
28
+ "test": "vitest run",
29
+ "test:watch": "vitest",
30
+ "test:coverage": "vitest run --coverage",
31
+ "verify": "node .agents/scripts/verify.mjs",
32
+ "review:worktree": "node .agents/scripts/review-worktree.ts",
33
+ "build:esm": "npx tsc -p tsconfig.esm.json",
34
+ "build:fix-esm": "node scripts/fix-esm-imports.cjs",
35
+ "build:fix-dts": "node scripts/fix-dts-imports.cjs",
36
+ "build": "npm-run-all clean build:esm build:fix-esm build:fix-dts",
37
+ "type-check": "npm-run-all --parallel type-check:src type-check:tools",
38
+ "type-check:src": "tsc --noEmit",
39
+ "type-check:tools": "tsc --noEmit -p .agents/scripts",
40
+ "lint": "oxlint src .agents/scripts",
41
+ "format:check": "oxfmt --check",
42
+ "check": "npm-run-all lint format:check",
43
+ "check:fix": "oxlint src .agents/scripts --fix && oxfmt",
44
+ "attw": "attw --pack --ignore-rules cjs-resolves-to-esm",
45
+ "audit": "npm audit --audit-level=moderate",
46
+ "integrity-checks": "npm-run-all clean check test build attw",
47
+ "prepublishOnly": "npm run integrity-checks",
48
+ "prepare": "node -e \"require('fs').existsSync('.git') && require('child_process').execSync('lefthook install --reset-hooks-path', { stdio: 'inherit' })\" && npm run build"
49
+ },
50
+ "dependencies": {
51
+ "@doist/sdk-kmp": "0.6.0",
52
+ "camelcase": "9.0.0",
53
+ "ts-custom-error": "3.3.1",
54
+ "undici": "8.12.3",
55
+ "uuid": "11.1.1",
56
+ "zod": "4.6.6"
57
+ },
58
+ "devDependencies": {
59
+ "@arethetypeswrong/cli": "0.18.4",
60
+ "@semantic-release/changelog": "6.0.3",
61
+ "@semantic-release/git": "10.0.1",
62
+ "@types/node": "25.9.1",
63
+ "conventional-changelog-conventionalcommits": "9.3.1",
64
+ "lefthook": "2.2.2",
65
+ "msw": "2.14.6",
66
+ "npm-run-all2": "9.0.2",
67
+ "obsidian": "1.13.1",
68
+ "oxfmt": "0.56.0",
69
+ "oxlint": "1.71.0",
70
+ "rimraf": "6.1.3",
71
+ "semantic-release": "25.0.5",
72
+ "ts-node": "10.9.2",
73
+ "typescript": "5.9.3",
74
+ "vitest": "4.1.12"
75
+ },
76
+ "files": [
77
+ "dist/esm/**/*",
78
+ "dist/types/**/*",
79
+ "!dist/**/*.test.js",
80
+ "!dist/**/*.test.d.ts"
81
+ ]
10
82
  }