@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.
Files changed (93) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +187 -2
  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 +81 -5
@@ -0,0 +1,27 @@
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.0/`).
7
+ *
8
+ * @param version - API version. Defaults to 'v1.0'.
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.0/')
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";
25
+ export declare const ENDPOINT_ATTACHMENTS = "attachments";
26
+ export declare const ENDPOINT_FILES = "files";
27
+ export declare const ENDPOINT_HOOKS = "hooks";
@@ -0,0 +1,21 @@
1
+ export * from './authentication.js';
2
+ export * from './migration.js';
3
+ export { AttachmentsClient, IMAGE_READ_MIME_TYPES, ImageReadResultSchema, type ImageReadMimeType, type ImageReadResult, } from './clients/attachments-client.js';
4
+ export { ChannelsClient } from './clients/channels-client.js';
5
+ export { CommentsClient } from './clients/comments-client.js';
6
+ export { ConversationMessagesClient } from './clients/conversation-messages-client.js';
7
+ export { ConversationsClient } from './clients/conversations-client.js';
8
+ export { GroupsClient } from './clients/groups-client.js';
9
+ export { HooksClient } from './clients/hooks-client.js';
10
+ export { InboxClient } from './clients/inbox-client.js';
11
+ export { ReactionsClient } from './clients/reactions-client.js';
12
+ export { SearchClient } from './clients/search-client.js';
13
+ export { ThreadsClient } from './clients/threads-client.js';
14
+ export { UsersClient } from './clients/users-client.js';
15
+ export { WorkspaceUsersClient } from './clients/workspace-users-client.js';
16
+ export { WorkspacesClient } from './clients/workspaces-client.js';
17
+ export { CommsApi } from './comms-api.js';
18
+ export type { CommsApiOptions } from './comms-api.js';
19
+ export { closeDefaultDispatcher } from './transport/http-dispatcher.js';
20
+ export * from './types/index.js';
21
+ export * from './utils/index.js';
@@ -0,0 +1,78 @@
1
+ import { CommsRequestError } from './types/errors.js';
2
+ import type { CustomFetch } from './types/http.js';
3
+ export type MigrationOptions = {
4
+ /** Optional custom base URL for the Twist migration endpoint (testing/self-host). */
5
+ baseUrl?: string;
6
+ /** Optional custom fetch implementation for cross-platform compatibility. */
7
+ customFetch?: CustomFetch;
8
+ };
9
+ export type FetchNewCommsUrlArgs = {
10
+ /** A `twist.com` URL to translate to its Comms equivalent. */
11
+ oldUrl: string;
12
+ /** A Twist (not Comms) auth token. */
13
+ twistToken: string;
14
+ };
15
+ export type FetchNewCommsUrlsArgs = {
16
+ /** The `twist.com` URLs to translate to their Comms equivalents. */
17
+ oldUrls: string[];
18
+ /** A Twist (not Comms) auth token. */
19
+ twistToken: string;
20
+ };
21
+ /**
22
+ * Result of translating a single URL in a batch migration. Discriminated by the
23
+ * presence of `newUrl` (success) or `error` (failure).
24
+ */
25
+ export type MigrationResult = {
26
+ oldUrl: string;
27
+ newUrl: string;
28
+ error?: undefined;
29
+ } | {
30
+ oldUrl: string;
31
+ newUrl?: undefined;
32
+ error: CommsRequestError;
33
+ };
34
+ /**
35
+ * Translates a Twist URL to its equivalent Comms URL using Twist's
36
+ * `comms_migration/fetch_new_url` endpoint.
37
+ *
38
+ * Authenticates with a **Twist** token (external to the Comms SDK), so this is a
39
+ * standalone helper rather than a method on {@link CommsApi}.
40
+ *
41
+ * @example
42
+ * ```typescript
43
+ * const newUrl = await fetchNewCommsUrl({
44
+ * oldUrl: 'https://twist.com/a/123/ch/456/t/789',
45
+ * twistToken: process.env.TWIST_AUTH_TOKEN,
46
+ * })
47
+ * ```
48
+ *
49
+ * @returns The equivalent Comms URL.
50
+ * @throws {@link CommsRequestError} If the request fails. URLs that cannot be
51
+ * migrated surface as a thrown error too: `400` with `responseData.error.code`
52
+ * of `'invalid_url'`, or `404` with `'not_imported'`.
53
+ */
54
+ export declare function fetchNewCommsUrl(args: FetchNewCommsUrlArgs, options?: MigrationOptions): Promise<string>;
55
+ /**
56
+ * Translates multiple Twist URLs to their equivalent Comms URLs.
57
+ *
58
+ * URLs are processed **sequentially** to stay friendly to the rate-sensitive
59
+ * migration endpoint. A failure on one URL does not abort the run: each result
60
+ * carries either a `newUrl` (success) or a `CommsRequestError` (failure), in the
61
+ * same order as the input.
62
+ *
63
+ * @example
64
+ * ```typescript
65
+ * const results = await fetchNewCommsUrls({
66
+ * oldUrls: ['https://twist.com/a/1/ch/2/t/3', 'https://twist.com/bad'],
67
+ * twistToken: process.env.TWIST_AUTH_TOKEN,
68
+ * })
69
+ * for (const result of results) {
70
+ * if (result.newUrl) console.log(`${result.oldUrl} -> ${result.newUrl}`)
71
+ * else console.warn(`${result.oldUrl} failed`, result.error)
72
+ * }
73
+ * ```
74
+ *
75
+ * @returns One {@link MigrationResult} per input URL, in input order.
76
+ * @throws Re-throws any error that is not a {@link CommsRequestError}.
77
+ */
78
+ export declare function fetchNewCommsUrls(args: FetchNewCommsUrlsArgs, options?: MigrationOptions): Promise<MigrationResult[]>;
@@ -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;
@@ -0,0 +1,29 @@
1
+ import type { RequestUrlParam, RequestUrlResponse } from 'obsidian';
2
+ import type { CustomFetch } from '../types/http.js';
3
+ /**
4
+ * Creates a CustomFetch adapter for Obsidian's requestUrl API.
5
+ *
6
+ * This adapter bridges the gap between Obsidian's requestUrl interface and the
7
+ * standard fetch-like interface expected by the Comms API SDK.
8
+ *
9
+ * Key differences handled by this adapter:
10
+ * - Obsidian returns response data as properties (response.json, response.text)
11
+ * while the SDK expects methods (response.json(), response.text())
12
+ * - Obsidian's requestUrl bypasses CORS restrictions that would block standard fetch
13
+ * - Obsidian throws on HTTP errors by default; we set throw: false to handle manually
14
+ * - Obsidian doesn't provide statusText; we default to empty string
15
+ *
16
+ * @example
17
+ * ```typescript
18
+ * import { requestUrl } from 'obsidian'
19
+ * import { createObsidianFetchAdapter } from './obsidian-fetch-adapter.js'
20
+ *
21
+ * const api = new CommsApi('your-token', {
22
+ * customFetch: createObsidianFetchAdapter(requestUrl)
23
+ * })
24
+ * ```
25
+ *
26
+ * @param requestUrl - The Obsidian requestUrl function
27
+ * @returns A CustomFetch function compatible with the Comms API SDK
28
+ */
29
+ export declare function createObsidianFetchAdapter(requestUrl: (request: RequestUrlParam | string) => Promise<RequestUrlResponse>): CustomFetch;
@@ -0,0 +1,17 @@
1
+ import type { Channel, Comment, Conversation, Group, Thread, User, Workspace, WorkspaceUser } from '../types/entities.js';
2
+ export declare const TEST_API_TOKEN = "test-api-token";
3
+ export declare const TEST_API_BASE_URL: string;
4
+ export declare const TEST_CHANNEL_ID = "CQ7yksHFbYFrSPVTaHVCs";
5
+ export declare const TEST_THREAD_ID = "CQ7yksHFbYFrSPVTaHVCt";
6
+ export declare const TEST_COMMENT_ID = "7YpL3oZ4kZ9vP7Q1tR2sX41";
7
+ export declare const TEST_CONVERSATION_ID = "7YpL3oZ4kZ9vP7Q1tR2sX42";
8
+ export declare const TEST_MESSAGE_ID = "7YpL3oZ4kZ9vP7Q1tR2sX43";
9
+ export declare const TEST_GROUP_ID = "7YpL3oZ4kZ9vP7Q1tR2sX44";
10
+ export declare const mockUser: User;
11
+ export declare const mockWorkspace: Workspace;
12
+ export declare const mockChannel: Channel;
13
+ export declare const mockThread: Thread;
14
+ export declare const mockGroup: Group;
15
+ export declare const mockConversation: Conversation;
16
+ export declare const mockComment: Comment;
17
+ export declare const mockWorkspaceUser: WorkspaceUser;
@@ -0,0 +1,4 @@
1
+ import type { CustomFetch, HttpResponse } from '../types/http.js';
2
+ export declare function fetchWithRetry<T>(url: string, options: RequestInit & {
3
+ timeout?: number;
4
+ }, maxRetries?: number, customFetch?: CustomFetch): Promise<HttpResponse<T>>;
@@ -0,0 +1,14 @@
1
+ import type { CustomFetch, CustomHeaders, HttpMethod, HttpResponse } from '../types/http.js';
2
+ export declare function paramsSerializer(params: Record<string, unknown>): string;
3
+ export type RequestArgs = {
4
+ httpMethod: HttpMethod;
5
+ baseUri: string;
6
+ relativePath: string;
7
+ apiToken?: string;
8
+ payload?: Record<string, unknown>;
9
+ requestId?: string;
10
+ headers?: CustomHeaders;
11
+ customFetch?: CustomFetch;
12
+ };
13
+ export declare function request<T>(args: RequestArgs): Promise<HttpResponse<T>>;
14
+ export declare function isSuccess(response: HttpResponse): boolean;
@@ -0,0 +1,46 @@
1
+ import type { Dispatcher } from 'undici';
2
+ type UndiciFetch = typeof import('undici').fetch;
3
+ /**
4
+ * A dispatcher and the `fetch` that must be used with it. `fetch` is undici's
5
+ * own `fetch` on the full-undici Node path, or `undefined` (meaning: use the
6
+ * global `fetch`) on the Bun path. The two are cached together so callers can
7
+ * never observe a dispatcher paired with a mismatched `fetch` — see
8
+ * {@link getDefaultFetch} for why the pairing matters.
9
+ */
10
+ type DefaultTransport = {
11
+ dispatcher: Dispatcher;
12
+ fetch: UndiciFetch | undefined;
13
+ };
14
+ /**
15
+ * The default dispatcher and its paired `fetch`, as a single value so the two
16
+ * are always read consistently. Resolves to `undefined` outside Node (browser/
17
+ * edge), where callers use the global `fetch` with no dispatcher.
18
+ */
19
+ export declare function getDefaultTransport(): Promise<DefaultTransport | undefined>;
20
+ export declare function getDefaultDispatcher(): Promise<Dispatcher | undefined>;
21
+ /**
22
+ * Drains the default dispatcher's connection pool. CLIs and scripts should
23
+ * `await` this before exit so Node's event loop empties immediately instead
24
+ * of waiting ~4s on keep-alive. No-op in the browser branch.
25
+ */
26
+ export declare function closeDefaultDispatcher(): Promise<void>;
27
+ export declare function resetDefaultDispatcherForTests(): void;
28
+ /**
29
+ * The `fetch` implementation that must be used with the default dispatcher.
30
+ * Returns undici's own `fetch` on the full-undici Node path, or `undefined`
31
+ * (meaning: use the global `fetch`) in the browser/edge/Bun paths.
32
+ *
33
+ * Node's global `fetch` is backed by whatever undici version ships inside that
34
+ * Node release (6.x on Node 22 … 8.x on Node 26). Our dispatcher — and its
35
+ * `decompress` interceptor — comes from the npm `undici` package, which is a
36
+ * different version. Handing an npm-undici dispatcher to a mismatched built-in
37
+ * client makes gzip responses fail mid-stream with `terminated`. Sourcing
38
+ * `fetch` from the same npm `undici` keeps the whole request path on one
39
+ * version and removes the split.
40
+ *
41
+ * Only meaningful after {@link getDefaultTransport} has resolved, which is the
42
+ * one place that populates it.
43
+ */
44
+ export declare function getDefaultFetch(): UndiciFetch | undefined;
45
+ export declare function suppressExperimentalWarningsSync<T>(fn: () => T): T;
46
+ export {};
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Supported Comms API versions
3
+ */
4
+ export declare const API_VERSIONS: readonly ["v1.0"];
5
+ export type ApiVersion = (typeof API_VERSIONS)[number];
6
+ export declare const DEFAULT_API_VERSION: ApiVersion;