@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,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,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 {};
|