@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,55 @@
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 declare const EVERYONE: "EVERYONE";
11
+ export declare const EVERYONE_IN_THREAD: "EVERYONE_IN_THREAD";
12
+ /** Union of the two broadcast group markers. */
13
+ export declare const GROUP_ID_MARKERS: readonly ["EVERYONE", "EVERYONE_IN_THREAD"];
14
+ export type GroupIdMarker = (typeof GROUP_ID_MARKERS)[number];
15
+ /**
16
+ * A group identifier on the wire — either an opaque group ID or one of
17
+ * the {@link GROUP_ID_MARKERS} for a broadcast audience.
18
+ */
19
+ export type GroupId = string;
20
+ export declare const USER_TYPES: readonly ["USER", "GUEST", "ADMIN"];
21
+ /**
22
+ * The type of user in a workspace.
23
+ *
24
+ * @remarks
25
+ * Possible values:
26
+ * - `'USER'` - Regular user
27
+ * - `'GUEST'` - Guest user
28
+ * - `'ADMIN'` - Administrator
29
+ */
30
+ export type UserType = (typeof USER_TYPES)[number];
31
+ export declare const WORKSPACE_PLANS: readonly ["free", "unlimited", "business"];
32
+ /**
33
+ * The plan type for a workspace. Any string accepted; the listed values
34
+ * are the ones the backend exposes today.
35
+ */
36
+ export type WorkspacePlan = (typeof WORKSPACE_PLANS)[number] | (string & {});
37
+ export declare const NOTIFY_AUDIENCES: readonly ["channel", "thread"];
38
+ /**
39
+ * The audience to notify when posting a comment, in addition to any
40
+ * individual `recipients` or custom `groups`.
41
+ *
42
+ * @remarks
43
+ * Possible values:
44
+ * - `'channel'` - Notify everyone in the channel.
45
+ * - `'thread'` - Notify everyone who has interacted with the thread.
46
+ */
47
+ export type NotifyAudience = (typeof NOTIFY_AUDIENCES)[number];
48
+ /**
49
+ * Internal mapping from {@link NotifyAudience} to the broadcast marker IDs
50
+ * (`EVERYONE` / `EVERYONE_IN_THREAD`) that comment- and thread-creation
51
+ * endpoints use on the wire. SDK consumers should use {@link NotifyAudience}
52
+ * via `notifyAudience` on the request args rather than passing these IDs
53
+ * directly.
54
+ */
55
+ export declare const NOTIFY_AUDIENCE_GROUP_IDS: Readonly<Record<NotifyAudience, GroupId>>;
@@ -0,0 +1,57 @@
1
+ import { CustomError } from 'ts-custom-error';
2
+ export declare class CommsRequestError extends CustomError {
3
+ httpStatusCode?: number;
4
+ responseData?: unknown;
5
+ constructor(message: string, httpStatusCode?: number, responseData?: unknown, options?: ErrorOptions);
6
+ }
7
+ /**
8
+ * The numeric `error_code` the API sends in an error body, when there was one.
9
+ *
10
+ * @param error - The thrown value to inspect.
11
+ * @returns The code, or `null` when the error is not a
12
+ * {@link CommsRequestError} or carried no numeric `error_code`.
13
+ */
14
+ export declare function getCommsErrorCode(error: unknown): number | null;
15
+ /**
16
+ * The `error_string` the API sends alongside `error_code`, when there was one.
17
+ * It is a server-authored message rather than a stable contract, so branch on
18
+ * {@link getCommsErrorCode} and use this for display.
19
+ *
20
+ * @param error - The thrown value to inspect.
21
+ * @returns The message, or `null` when the error is not a
22
+ * {@link CommsRequestError} or carried no string `error_string`.
23
+ */
24
+ export declare function getCommsErrorString(error: unknown): string | null;
25
+ /**
26
+ * True when the request failed with a 404.
27
+ *
28
+ * @example
29
+ * ```typescript
30
+ * try {
31
+ * await api.threads.getThread(id)
32
+ * } catch (error) {
33
+ * if (isNotFound(error)) return null
34
+ * throw error
35
+ * }
36
+ * ```
37
+ */
38
+ export declare function isNotFound(error: unknown): boolean;
39
+ /**
40
+ * True when the request failed with a 409. The API uses this both for genuine
41
+ * conflicts and for a malformed id, so narrow with {@link isMalformedId}
42
+ * before reporting one as the other.
43
+ */
44
+ export declare function isConflict(error: unknown): boolean;
45
+ /**
46
+ * True when the API rejected an id as malformed: a 409 carrying `error_code`
47
+ * 217, which it sends both for a value that does not base58-decode to 16 bytes
48
+ * and for one whose version nibble is not 7. That is a bad reference rather
49
+ * than a conflict, so it usually deserves a different message from
50
+ * {@link isConflict}.
51
+ *
52
+ * @example
53
+ * ```typescript
54
+ * if (isMalformedId(error)) throw new Error(`Not a valid Comms id: ${ref}`)
55
+ * ```
56
+ */
57
+ export declare function isMalformedId(error: unknown): boolean;
@@ -0,0 +1,60 @@
1
+ export declare const HTTP_METHODS: readonly ["POST", "GET", "PUT", "PATCH", "DELETE"];
2
+ export type HttpMethod = (typeof HTTP_METHODS)[number];
3
+ export type HttpResponse<T = unknown> = {
4
+ data: T;
5
+ status: number;
6
+ headers: Record<string, string>;
7
+ };
8
+ /**
9
+ * Extra headers sent with every API request: either a fixed record, or a function
10
+ * the SDK calls once per request (retries reuse its result) for values that change
11
+ * between requests, such as a per-request ID or the command currently running.
12
+ */
13
+ export type CustomHeaders = Record<string, string> | (() => Record<string, string>);
14
+ export type RequestConfig = {
15
+ baseURL?: string;
16
+ headers?: Record<string, string>;
17
+ timeout?: number;
18
+ };
19
+ /**
20
+ * Custom fetch response interface for cross-platform HTTP clients.
21
+ * This minimal interface allows custom HTTP implementations (e.g., Obsidian's requestUrl,
22
+ * Electron's net module, React Native's networking) to work with the SDK.
23
+ */
24
+ export type CustomFetchResponse = {
25
+ ok: boolean;
26
+ status: number;
27
+ statusText: string;
28
+ headers: Record<string, string>;
29
+ text(): Promise<string>;
30
+ json(): Promise<unknown>;
31
+ };
32
+ /**
33
+ * Custom fetch function type for providing alternative HTTP implementations.
34
+ * This enables the SDK to work in restrictive environments like Obsidian plugins,
35
+ * browser extensions, Electron apps, React Native, and enterprise environments
36
+ * with specific networking requirements.
37
+ *
38
+ * @param url - The URL to fetch
39
+ * @param options - Standard RequestInit options plus optional timeout
40
+ * @returns A promise that resolves to a CustomFetchResponse
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * // Obsidian plugin example
45
+ * const obsidianFetch: CustomFetch = async (url, options) => {
46
+ * const response = await requestUrl({ url, method: options?.method, body: options?.body })
47
+ * return {
48
+ * ok: response.status >= 200 && response.status < 300,
49
+ * status: response.status,
50
+ * statusText: '',
51
+ * headers: response.headers,
52
+ * text: async () => response.text,
53
+ * json: async () => response.json,
54
+ * }
55
+ * }
56
+ * ```
57
+ */
58
+ export type CustomFetch = (url: string, options?: RequestInit & {
59
+ timeout?: number;
60
+ }) => Promise<CustomFetchResponse>;
@@ -0,0 +1,6 @@
1
+ export * from './api-version.js';
2
+ export * from './entities.js';
3
+ export * from './enums.js';
4
+ export * from './errors.js';
5
+ export * from './http.js';
6
+ export * from './requests.js';