@todoist/comms-sdk 5.1.1 → 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
  )
@@ -1,4 +1,5 @@
1
1
  import { v4 as uuid } from 'uuid';
2
+ import { BASE_URI } from './consts/endpoints.js';
2
3
  import { isSuccess, request } from './transport/http-client.js';
3
4
  import { CommsRequestError } from './types/errors.js';
4
5
  /**
@@ -15,65 +16,15 @@ function getAuthBaseUrl(baseUrl) {
15
16
  return base.endsWith('/') ? base.slice(0, -1) : base;
16
17
  }
17
18
  /**
18
- * OAuth scopes for the Comms API.
19
+ * Scope names from before Comms used Todoist as its authorisation server.
19
20
  *
20
- * @remarks
21
- * Request only the scopes your application needs:
22
- *
23
- * **User Scopes:**
24
- * - `user:read` - Access user's personal settings
25
- * - `user:write` - Access and update user's personal settings
26
- *
27
- * **Workspace Scopes:**
28
- * - `workspaces:read` - Access teams the user is part of
29
- * - `workspaces:write` - Access and update teams the user is part of
30
- *
31
- * **Channel Scopes:**
32
- * - `channels:read` - Access channels
33
- * - `channels:write` - Access and update channels
34
- * - `channels:remove` - Access, update, and delete channels
35
- *
36
- * **Thread Scopes:**
37
- * - `threads:read` - Access threads
38
- * - `threads:write` - Access and update threads
39
- * - `threads:remove` - Access, update, and delete threads
40
- *
41
- * **Comment Scopes:**
42
- * - `comments:read` - Access comments
43
- * - `comments:write` - Access and update comments
44
- * - `comments:remove` - Access, update, and delete comments
45
- *
46
- * **Group Scopes:**
47
- * - `groups:read` - Access groups
48
- * - `groups:write` - Access and update groups
49
- * - `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.
50
23
  *
51
- * **Message Scopes:**
52
- * - `messages:read` - Access messages
53
- * - `messages:write` - Access and update messages
54
- * - `messages:remove` - Access, update, and delete messages
55
- *
56
- * **Reaction Scopes:**
57
- * - `reactions:read` - Access reactions
58
- * - `reactions:write` - Access and update reactions
59
- * - `reactions:remove` - Access, update, and delete reactions
60
- *
61
- * **Search Scopes:**
62
- * - `search:read` - Search
63
- *
64
- * **Attachment Scopes:**
65
- * - `attachments:read` - Access attachments
66
- * - `attachments:write` - Access and update attachments
67
- *
68
- * **Notification Scopes:**
69
- * - `notifications:read` - Read user's notifications settings
70
- * - `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}.
71
26
  */
72
- export const COMMS_SCOPES = [
73
- 'user:read',
74
- 'user:write',
75
- 'workspaces:read',
76
- 'workspaces:write',
27
+ export const LEGACY_COMMS_SCOPES = [
77
28
  'channels:read',
78
29
  'channels:write',
79
30
  'channels:remove',
@@ -98,6 +49,49 @@ export const COMMS_SCOPES = [
98
49
  'notifications:read',
99
50
  'notifications:write',
100
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
+ ];
101
95
  /** Supported token endpoint authentication methods for dynamic client registration. */
102
96
  export const TOKEN_ENDPOINT_AUTH_METHODS = [
103
97
  'client_secret_post',
@@ -110,6 +104,10 @@ export function getAuthStateParameter() {
110
104
  /**
111
105
  * Generates the authorization URL for the OAuth2 flow.
112
106
  *
107
+ * The URL carries the Comms API as its `resource` indicator
108
+ * ({@link https://datatracker.ietf.org/doc/html/rfc8707 RFC 8707}), so Todoist
109
+ * issues a token for Comms rather than a Todoist API token.
110
+ *
113
111
  * The `clientId` can be either a traditional client ID string (e.g. from
114
112
  * {@link registerClient}) or an HTTPS URL pointing to a client metadata document,
115
113
  * as defined in {@link https://drafts.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/ RFC draft-ietf-oauth-client-id-metadata-document}.
@@ -125,6 +123,7 @@ export function getAuthorizationUrl(clientId, scopes, state, redirectUri, baseUr
125
123
  response_type: 'code',
126
124
  scope,
127
125
  state,
126
+ resource: BASE_URI,
128
127
  });
129
128
  if (redirectUri) {
130
129
  params.append('redirect_uri', redirectUri);
@@ -1,5 +1,5 @@
1
1
  import { DEFAULT_API_VERSION } from '../types/api-version.js';
2
- const BASE_URI = 'https://comms.todoist.com';
2
+ export const BASE_URI = 'https://comms.todoist.com';
3
3
  /**
4
4
  * Gets the base URI for Comms API requests.
5
5
  *
@@ -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
41
- *
42
- * **Message Scopes:**
43
- * - `messages:read` - Access messages
44
- * - `messages:write` - Access and update messages
45
- * - `messages:remove` - Access, update, and delete messages
11
+ * Todoist's authorisation server doesn't offer these, and the Comms API checks
12
+ * the `comms:*` scopes in {@link COMMS_SCOPES} instead.
46
13
  *
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
  */
@@ -137,6 +126,10 @@ export declare function getAuthStateParameter(): string;
137
126
  /**
138
127
  * Generates the authorization URL for the OAuth2 flow.
139
128
  *
129
+ * The URL carries the Comms API as its `resource` indicator
130
+ * ({@link https://datatracker.ietf.org/doc/html/rfc8707 RFC 8707}), so Todoist
131
+ * issues a token for Comms rather than a Todoist API token.
132
+ *
140
133
  * The `clientId` can be either a traditional client ID string (e.g. from
141
134
  * {@link registerClient}) or an HTTPS URL pointing to a client metadata document,
142
135
  * as defined in {@link https://drafts.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/ RFC draft-ietf-oauth-client-id-metadata-document}.
@@ -1,4 +1,5 @@
1
1
  import type { ApiVersion } from '../types/api-version.js';
2
+ export declare const BASE_URI = "https://comms.todoist.com";
2
3
  /**
3
4
  * Gets the base URI for Comms API requests.
4
5
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@todoist/comms-sdk",
3
- "version": "5.1.1",
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/",