@todoist/comms-sdk 5.1.2 → 5.2.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/README.md CHANGED
@@ -96,7 +96,7 @@ import { getAuthorizationUrl, getAuthToken, CommsApi } from '@todoist/comms-sdk'
96
96
 
97
97
  const authUrl = getAuthorizationUrl(
98
98
  'your-client-id',
99
- ['user:read', 'channels:read'],
99
+ ['user:read', 'comms:channels:read'],
100
100
  'state-parameter',
101
101
  'https://yourapp.com/callback',
102
102
  )
@@ -16,65 +16,15 @@ function getAuthBaseUrl(baseUrl) {
16
16
  return base.endsWith('/') ? base.slice(0, -1) : base;
17
17
  }
18
18
  /**
19
- * OAuth scopes for the Comms API.
19
+ * Scope names from before Comms used Todoist as its authorisation server.
20
20
  *
21
- * @remarks
22
- * Request only the scopes your application needs:
23
- *
24
- * **User Scopes:**
25
- * - `user:read` - Access user's personal settings
26
- * - `user:write` - Access and update user's personal settings
27
- *
28
- * **Workspace Scopes:**
29
- * - `workspaces:read` - Access teams the user is part of
30
- * - `workspaces:write` - Access and update teams the user is part of
31
- *
32
- * **Channel Scopes:**
33
- * - `channels:read` - Access channels
34
- * - `channels:write` - Access and update channels
35
- * - `channels:remove` - Access, update, and delete channels
36
- *
37
- * **Thread Scopes:**
38
- * - `threads:read` - Access threads
39
- * - `threads:write` - Access and update threads
40
- * - `threads:remove` - Access, update, and delete threads
41
- *
42
- * **Comment Scopes:**
43
- * - `comments:read` - Access comments
44
- * - `comments:write` - Access and update comments
45
- * - `comments:remove` - Access, update, and delete comments
46
- *
47
- * **Group Scopes:**
48
- * - `groups:read` - Access groups
49
- * - `groups:write` - Access and update groups
50
- * - `groups:remove` - Access, update, and delete groups
21
+ * Todoist's authorisation server doesn't offer these, and the Comms API checks
22
+ * the `comms:*` scopes in {@link COMMS_SCOPES} instead.
51
23
  *
52
- * **Message Scopes:**
53
- * - `messages:read` - Access messages
54
- * - `messages:write` - Access and update messages
55
- * - `messages:remove` - Access, update, and delete messages
56
- *
57
- * **Reaction Scopes:**
58
- * - `reactions:read` - Access reactions
59
- * - `reactions:write` - Access and update reactions
60
- * - `reactions:remove` - Access, update, and delete reactions
61
- *
62
- * **Search Scopes:**
63
- * - `search:read` - Search
64
- *
65
- * **Attachment Scopes:**
66
- * - `attachments:read` - Access attachments
67
- * - `attachments:write` - Access and update attachments
68
- *
69
- * **Notification Scopes:**
70
- * - `notifications:read` - Read user's notifications settings
71
- * - `notifications:write` - Read and update user's notifications settings
24
+ * @deprecated Use the scopes in {@link COMMS_SCOPES}. The next major version
25
+ * removes these names from {@link COMMS_SCOPES} and {@link CommsScope}.
72
26
  */
73
- export const COMMS_SCOPES = [
74
- 'user:read',
75
- 'user:write',
76
- 'workspaces:read',
77
- 'workspaces:write',
27
+ export const LEGACY_COMMS_SCOPES = [
78
28
  'channels:read',
79
29
  'channels:write',
80
30
  'channels:remove',
@@ -99,6 +49,49 @@ export const COMMS_SCOPES = [
99
49
  'notifications:read',
100
50
  'notifications:write',
101
51
  ];
52
+ /**
53
+ * OAuth scopes for the Comms API, as granted by Todoist.
54
+ *
55
+ * @remarks
56
+ * Request only the scopes your application needs. Each scope is exact:
57
+ * `comms:content:write` doesn't include `comms:content:read`, so ask for both
58
+ * if you read and write.
59
+ *
60
+ * - `user:read` - Read the person's profile and settings
61
+ * - `user:write` - Update the person's profile, settings, and status
62
+ * - `workspaces:read` - Read workspaces, members, and groups
63
+ * - `workspaces:write` - Update workspaces, invite and remove members, manage groups
64
+ * - `comms:channels:read` - Read channels, including metadata and membership
65
+ * - `comms:channels:write` - Create and update channels, and manage their members
66
+ * - `comms:channels:delete` - Delete or archive channels
67
+ * - `comms:content:read` - Read threads, comments, reactions, and attachments
68
+ * - `comms:content:write` - Create and update threads, comments, reactions, and attachments
69
+ * - `comms:content:delete` - Delete threads, comments, reactions, and attachments
70
+ * - `comms:messages:read` - Read 1:1 and group chats and their messages
71
+ * - `comms:messages:write` - Send, update, and pin chat messages, and start and manage chats
72
+ * - `comms:messages:delete` - Delete chat messages and remove people from chats
73
+ *
74
+ * Reactions use the `comms:content:*` scopes, including on chat messages.
75
+ *
76
+ * The list also contains the deprecated {@link LEGACY_COMMS_SCOPES}, which
77
+ * the next major version removes.
78
+ */
79
+ export const COMMS_SCOPES = [
80
+ 'user:read',
81
+ 'user:write',
82
+ 'workspaces:read',
83
+ 'workspaces:write',
84
+ 'comms:channels:read',
85
+ 'comms:channels:write',
86
+ 'comms:channels:delete',
87
+ 'comms:content:read',
88
+ 'comms:content:write',
89
+ 'comms:content:delete',
90
+ 'comms:messages:read',
91
+ 'comms:messages:write',
92
+ 'comms:messages:delete',
93
+ ...LEGACY_COMMS_SCOPES,
94
+ ];
102
95
  /** Supported token endpoint authentication methods for dynamic client registration. */
103
96
  export const TOKEN_ENDPOINT_AUTH_METHODS = [
104
97
  'client_secret_post',
@@ -6,61 +6,50 @@ export type AuthOptions = {
6
6
  customFetch?: CustomFetch;
7
7
  };
8
8
  /**
9
- * OAuth scopes for the Comms API.
9
+ * Scope names from before Comms used Todoist as its authorisation server.
10
10
  *
11
- * @remarks
12
- * Request only the scopes your application needs:
13
- *
14
- * **User Scopes:**
15
- * - `user:read` - Access user's personal settings
16
- * - `user:write` - Access and update user's personal settings
17
- *
18
- * **Workspace Scopes:**
19
- * - `workspaces:read` - Access teams the user is part of
20
- * - `workspaces:write` - Access and update teams the user is part of
21
- *
22
- * **Channel Scopes:**
23
- * - `channels:read` - Access channels
24
- * - `channels:write` - Access and update channels
25
- * - `channels:remove` - Access, update, and delete channels
26
- *
27
- * **Thread Scopes:**
28
- * - `threads:read` - Access threads
29
- * - `threads:write` - Access and update threads
30
- * - `threads:remove` - Access, update, and delete threads
31
- *
32
- * **Comment Scopes:**
33
- * - `comments:read` - Access comments
34
- * - `comments:write` - Access and update comments
35
- * - `comments:remove` - Access, update, and delete comments
36
- *
37
- * **Group Scopes:**
38
- * - `groups:read` - Access groups
39
- * - `groups:write` - Access and update groups
40
- * - `groups:remove` - Access, update, and delete groups
11
+ * Todoist's authorisation server doesn't offer these, and the Comms API checks
12
+ * the `comms:*` scopes in {@link COMMS_SCOPES} instead.
41
13
  *
42
- * **Message Scopes:**
43
- * - `messages:read` - Access messages
44
- * - `messages:write` - Access and update messages
45
- * - `messages:remove` - Access, update, and delete messages
46
- *
47
- * **Reaction Scopes:**
48
- * - `reactions:read` - Access reactions
49
- * - `reactions:write` - Access and update reactions
50
- * - `reactions:remove` - Access, update, and delete reactions
51
- *
52
- * **Search Scopes:**
53
- * - `search:read` - Search
14
+ * @deprecated Use the scopes in {@link COMMS_SCOPES}. The next major version
15
+ * removes these names from {@link COMMS_SCOPES} and {@link CommsScope}.
16
+ */
17
+ export declare const LEGACY_COMMS_SCOPES: readonly ["channels:read", "channels:write", "channels:remove", "threads:read", "threads:write", "threads:remove", "comments:read", "comments:write", "comments:remove", "groups:read", "groups:write", "groups:remove", "messages:read", "messages:write", "messages:remove", "reactions:read", "reactions:write", "reactions:remove", "search:read", "attachments:read", "attachments:write", "notifications:read", "notifications:write"];
18
+ /**
19
+ * A scope name from before Comms used Todoist as its authorisation server.
54
20
  *
55
- * **Attachment Scopes:**
56
- * - `attachments:read` - Access attachments
57
- * - `attachments:write` - Access and update attachments
21
+ * @deprecated Use a {@link CommsScope} from the `comms:*`, `user:*` or
22
+ * `workspaces:*` scopes instead.
23
+ */
24
+ export type LegacyCommsScope = (typeof LEGACY_COMMS_SCOPES)[number];
25
+ /**
26
+ * OAuth scopes for the Comms API, as granted by Todoist.
58
27
  *
59
- * **Notification Scopes:**
60
- * - `notifications:read` - Read user's notifications settings
61
- * - `notifications:write` - Read and update user's notifications settings
28
+ * @remarks
29
+ * Request only the scopes your application needs. Each scope is exact:
30
+ * `comms:content:write` doesn't include `comms:content:read`, so ask for both
31
+ * if you read and write.
32
+ *
33
+ * - `user:read` - Read the person's profile and settings
34
+ * - `user:write` - Update the person's profile, settings, and status
35
+ * - `workspaces:read` - Read workspaces, members, and groups
36
+ * - `workspaces:write` - Update workspaces, invite and remove members, manage groups
37
+ * - `comms:channels:read` - Read channels, including metadata and membership
38
+ * - `comms:channels:write` - Create and update channels, and manage their members
39
+ * - `comms:channels:delete` - Delete or archive channels
40
+ * - `comms:content:read` - Read threads, comments, reactions, and attachments
41
+ * - `comms:content:write` - Create and update threads, comments, reactions, and attachments
42
+ * - `comms:content:delete` - Delete threads, comments, reactions, and attachments
43
+ * - `comms:messages:read` - Read 1:1 and group chats and their messages
44
+ * - `comms:messages:write` - Send, update, and pin chat messages, and start and manage chats
45
+ * - `comms:messages:delete` - Delete chat messages and remove people from chats
46
+ *
47
+ * Reactions use the `comms:content:*` scopes, including on chat messages.
48
+ *
49
+ * The list also contains the deprecated {@link LEGACY_COMMS_SCOPES}, which
50
+ * the next major version removes.
62
51
  */
63
- export declare const COMMS_SCOPES: readonly ["user:read", "user:write", "workspaces:read", "workspaces:write", "channels:read", "channels:write", "channels:remove", "threads:read", "threads:write", "threads:remove", "comments:read", "comments:write", "comments:remove", "groups:read", "groups:write", "groups:remove", "messages:read", "messages:write", "messages:remove", "reactions:read", "reactions:write", "reactions:remove", "search:read", "attachments:read", "attachments:write", "notifications:read", "notifications:write"];
52
+ export declare const COMMS_SCOPES: readonly ["user:read", "user:write", "workspaces:read", "workspaces:write", "comms:channels:read", "comms:channels:write", "comms:channels:delete", "comms:content:read", "comms:content:write", "comms:content:delete", "comms:messages:read", "comms:messages:write", "comms:messages:delete", "channels:read", "channels:write", "channels:remove", "threads:read", "threads:write", "threads:remove", "comments:read", "comments:write", "comments:remove", "groups:read", "groups:write", "groups:remove", "messages:read", "messages:write", "messages:remove", "reactions:read", "reactions:write", "reactions:remove", "search:read", "attachments:read", "attachments:write", "notifications:read", "notifications:write"];
64
53
  /**
65
54
  * Scopes determine what access a token has to the Comms API.
66
55
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@todoist/comms-sdk",
3
- "version": "5.1.2",
3
+ "version": "5.2.0",
4
4
  "description": "A TypeScript wrapper for the Comms REST API.",
5
5
  "author": "Doist developers",
6
6
  "homepage": "https://doist.github.io/comms-sdk-typescript/",