@doist/comms-sdk 0.4.5 → 0.5.0

package/README.md

@@ -103,6 +103,24 @@ const api = new CommsApi(tokenResponse.accessToken)
 const user = await api.users.getSessionUser()
 ```
 
+Access tokens expire (see `tokenResponse.expiresIn`). When they do, use the
+`refreshToken` from the original exchange to obtain a new one without sending
+the user back through the authorization flow:
+
+```typescript
+import { refreshAuthToken } from '@doist/comms-sdk'
+
+const refreshed = await refreshAuthToken({
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    refreshToken: tokenResponse.refreshToken,
+})
+
+// The server may rotate the refresh token — persist refreshed.refreshToken
+// when present, otherwise keep using the previous one.
+const api = new CommsApi(refreshed.accessToken)
+```
+
 ### Short-lived processes (CLIs, scripts)
 
 On Node, the SDK keeps a connection pool alive across requests so HTTP/2
@@ -122,7 +140,7 @@ try {
 
 `api.close()` drains the process-global pool, so it also covers code
 paths that only use the standalone OAuth helpers (`getAuthToken`,
-`revokeAuthToken`, `registerClient`). Those flows can also import
+`refreshAuthToken`, `revokeAuthToken`, `registerClient`). Those flows can also import
 `closeDefaultDispatcher` directly.
 
 ## Development

package/dist/cjs/authentication.js

@@ -4,11 +4,25 @@ exports.TOKEN_ENDPOINT_AUTH_METHODS = exports.COMMS_SCOPES = void 0;
 exports.getAuthStateParameter = getAuthStateParameter;
 exports.getAuthorizationUrl = getAuthorizationUrl;
 exports.getAuthToken = getAuthToken;
+exports.refreshAuthToken = refreshAuthToken;
 exports.revokeAuthToken = revokeAuthToken;
 exports.registerClient = registerClient;
 const uuid_1 = require("uuid");
 const http_client_1 = require("./transport/http-client");
 const errors_1 = require("./types/errors");
+/**
+ * Default origin of the Comms authorization server.
+ *
+ * The authorization server for Comms is Todoist (`todoist.com`), not the
+ * resource server (`comms.todoist.com`). Tokens are issued by Todoist and
+ * accepted by the Comms API. Paths match Todoist's published
+ * `/.well-known/oauth-authorization-server` metadata.
+ */
+const DEFAULT_AUTH_BASE_URL = 'https://todoist.com';
+function getAuthBaseUrl(baseUrl) {
+    const base = baseUrl ?? DEFAULT_AUTH_BASE_URL;
+    return base.endsWith('/') ? base.slice(0, -1) : base;
+}
 /**
  * OAuth scopes for the Comms API.
  *
@@ -113,7 +127,7 @@ function getAuthorizationUrl(clientId, scopes, state, redirectUri, baseUrl) {
     if (!scopes?.length) {
         throw new Error('At least one scope value is required.');
     }
-    const authBaseUrl = baseUrl ? `${baseUrl}/oauth` : 'https://comms.todoist.com/oauth';
+    const authBaseUrl = `${getAuthBaseUrl(baseUrl)}/oauth`;
     const scope = scopes.join(' ');
     const params = new URLSearchParams({
         client_id: clientId,
@@ -127,9 +141,7 @@ function getAuthorizationUrl(clientId, scopes, state, redirectUri, baseUrl) {
     return `${authBaseUrl}/authorize?${params.toString()}`;
 }
 async function getAuthToken(args, options) {
-    const tokenUrl = options?.baseUrl
-        ? `${options.baseUrl}/oauth/token`
-        : 'https://comms.todoist.com/oauth/token';
+    const tokenUrl = `${getAuthBaseUrl(options?.baseUrl)}/oauth/access_token`;
     const payload = {
         clientId: args.clientId,
         clientSecret: args.clientSecret,
@@ -149,10 +161,45 @@ async function getAuthToken(args, options) {
     }
     return response.data;
 }
+/**
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * @example
+ * ```typescript
+ * const { accessToken, refreshToken } = await refreshAuthToken({
+ *   clientId: 'client-id',
+ *   clientSecret: 'client-secret',
+ *   refreshToken: storedRefreshToken,
+ * })
+ * ```
+ *
+ * @returns The refreshed token. The response may include a new `refreshToken`
+ * (rotated by the server); persist it in place of the previous one when present.
+ * @throws {@link CommsRequestError} If the refresh fails
+ */
+async function refreshAuthToken(args, options) {
+    const tokenUrl = `${getAuthBaseUrl(options?.baseUrl)}/oauth/access_token`;
+    const payload = {
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+        refreshToken: args.refreshToken,
+        grantType: 'refresh_token',
+    };
+    const response = await (0, http_client_1.request)({
+        httpMethod: 'POST',
+        baseUri: tokenUrl,
+        relativePath: '',
+        payload,
+        customFetch: options?.customFetch,
+    });
+    if (!(0, http_client_1.isSuccess)(response) || !response.data?.accessToken) {
+        throw new errors_1.CommsRequestError('Authentication token refresh failed.', response.status, response.data);
+    }
+    return response.data;
+}
 async function revokeAuthToken(args, options) {
-    const revokeUrl = options?.baseUrl
-        ? `${options.baseUrl}/oauth/revoke`
-        : 'https://comms.todoist.com/oauth/revoke';
+    const revokeUrl = `${getAuthBaseUrl(options?.baseUrl)}/api/v1/revoke`;
     const response = await (0, http_client_1.request)({
         httpMethod: 'POST',
         baseUri: revokeUrl,
@@ -184,9 +231,7 @@ async function revokeAuthToken(args, options) {
  * @see {@link https://datatracker.ietf.org/doc/html/rfc7591 RFC 7591}
  */
 async function registerClient(args, options) {
-    const registerUrl = options?.baseUrl
-        ? `${options.baseUrl}/oauth/register`
-        : 'https://comms.todoist.com/oauth/register';
+    const registerUrl = `${getAuthBaseUrl(options?.baseUrl)}/oauth/register`;
     const response = await (0, http_client_1.request)({
         httpMethod: 'POST',
         baseUri: registerUrl,

package/dist/cjs/testUtils/test-defaults.js

@@ -35,7 +35,7 @@ exports.mockChannel = {
     archived: false,
     created: new Date('2021-01-01T00:00:00Z'),
     version: 0,
-    url: `https://comms.todoist.com/a/1/ch/${exports.TEST_CHANNEL_ID}/`,
+    url: `https://comms.todoist.com/1/ch/${exports.TEST_CHANNEL_ID}/`,
 };
 exports.mockThread = {
     id: exports.TEST_THREAD_ID,
@@ -51,7 +51,7 @@ exports.mockThread = {
     snippet: 'This is a test thread',
     snippetCreator: 1,
     isArchived: false,
-    url: `https://comms.todoist.com/a/1/ch/${exports.TEST_CHANNEL_ID}/t/${exports.TEST_THREAD_ID}/`,
+    url: `https://comms.todoist.com/1/ch/${exports.TEST_CHANNEL_ID}/t/${exports.TEST_THREAD_ID}/`,
 };
 exports.mockGroup = {
     id: exports.TEST_GROUP_ID,
@@ -72,7 +72,7 @@ exports.mockConversation = {
     archived: false,
     created: new Date('2021-01-01T00:00:00Z'),
     creator: 1,
-    url: `https://comms.todoist.com/a/1/msg/${exports.TEST_CONVERSATION_ID}/`,
+    url: `https://comms.todoist.com/1/msg/${exports.TEST_CONVERSATION_ID}/`,
 };
 exports.mockComment = {
     id: exports.TEST_COMMENT_ID,
@@ -82,7 +82,7 @@ exports.mockComment = {
     workspaceId: 1,
     channelId: exports.TEST_CHANNEL_ID,
     posted: new Date('2021-01-01T00:00:00Z'),
-    url: `https://comms.todoist.com/a/1/ch/${exports.TEST_CHANNEL_ID}/t/${exports.TEST_THREAD_ID}/c/${exports.TEST_COMMENT_ID}`,
+    url: `https://comms.todoist.com/1/ch/${exports.TEST_CHANNEL_ID}/t/${exports.TEST_THREAD_ID}/c/${exports.TEST_COMMENT_ID}`,
 };
 exports.mockWorkspaceUser = {
     id: 1,

package/dist/cjs/utils/url-helpers.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Helper functions for creating Comms permalinks (`https://comms.todoist.com/a/...`).
+ * Helper functions for creating Comms permalinks (`https://comms.todoist.com/...`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCommsURL = getCommsURL;
@@ -27,11 +27,11 @@ const COMMS_BASE_URL = 'https://comms.todoist.com';
  * @returns A relative URL path
  * @example
  * getCommsURL({ workspaceId: 1, channelId: '7Yp...', threadId: '7Yq...' })
- * // returns '/a/1/ch/7Yp.../t/7Yq.../'
+ * // returns '/1/ch/7Yp.../t/7Yq.../'
  */
 function getCommsURL(params) {
     const { workspaceId, channelId, conversationId, threadId, commentId, messageId, userId } = params;
-    let url = `/a/${workspaceId}/`;
+    let url = `/${workspaceId}/`;
     if (channelId) {
         url += `ch/${channelId}/`;
         if (threadId) {
@@ -90,44 +90,44 @@ function getCommentURL(params) {
 }
 /** Returns the URL for the threads root (channels view). */
 function getThreadsRootURL(workspaceId) {
-    return `/a/${workspaceId}/ch`;
+    return `/${workspaceId}/ch`;
 }
 /** Returns the URL for the inbox. */
 function getInboxURL(workspaceId, tab) {
     const tabParam = tab ? `/${tab}` : '';
-    return `/a/${workspaceId}/inbox${tabParam}`;
+    return `/${workspaceId}/inbox${tabParam}`;
 }
 /** Returns the URL for the messages/conversations root. */
 function getMessagesRootURL(workspaceId) {
-    return `/a/${workspaceId}/msg`;
+    return `/${workspaceId}/msg`;
 }
 /** Returns the URL for a user profile. */
 function getUserProfileURL(params) {
-    return `/a/${params.workspaceId}/people/u/${params.userId}`;
+    return `/${params.workspaceId}/people/u/${params.userId}`;
 }
 /** Returns the URL for the saved threads view. */
 function getSavedThreadsRootURL(workspaceId) {
-    return `/a/${workspaceId}/saved`;
+    return `/${workspaceId}/saved`;
 }
 /** Returns the URL for a saved thread. */
 function getSavedThreadURL(params) {
-    return `/a/${params.workspaceId}/saved/t/${params.threadId}`;
+    return `/${params.workspaceId}/saved/t/${params.threadId}`;
 }
 /** Returns the URL for the search root. */
 function getSearchRootURL(workspaceId) {
-    return `/a/${workspaceId}/search`;
+    return `/${workspaceId}/search`;
 }
 /** Returns the URL for a search with a query. */
 function getSearchQueryURL(params) {
-    return `/a/${params.workspaceId}/search?q=${decodeURIComponent(params.query)}`;
+    return `/${params.workspaceId}/search?q=${decodeURIComponent(params.query)}`;
 }
 /** Returns the URL for settings. */
 function getSettingsURL(params) {
     return params.initialLocation
-        ? `/a/${params.workspaceId}/settings/${params.initialLocation}`
-        : `/a/${params.workspaceId}/settings`;
+        ? `/${params.workspaceId}/settings/${params.initialLocation}`
+        : `/${params.workspaceId}/settings`;
 }
 /** Returns the URL for the team members root. */
 function getTeamMembersRootURL(workspaceId) {
-    return `/a/${workspaceId}/people/u`;
+    return `/${workspaceId}/people/u`;
 }

package/dist/esm/authentication.js

@@ -1,6 +1,19 @@
 import { v4 as uuid } from 'uuid';
 import { isSuccess, request } from './transport/http-client.js';
 import { CommsRequestError } from './types/errors.js';
+/**
+ * Default origin of the Comms authorization server.
+ *
+ * The authorization server for Comms is Todoist (`todoist.com`), not the
+ * resource server (`comms.todoist.com`). Tokens are issued by Todoist and
+ * accepted by the Comms API. Paths match Todoist's published
+ * `/.well-known/oauth-authorization-server` metadata.
+ */
+const DEFAULT_AUTH_BASE_URL = 'https://todoist.com';
+function getAuthBaseUrl(baseUrl) {
+    const base = baseUrl ?? DEFAULT_AUTH_BASE_URL;
+    return base.endsWith('/') ? base.slice(0, -1) : base;
+}
 /**
  * OAuth scopes for the Comms API.
  *
@@ -105,7 +118,7 @@ export function getAuthorizationUrl(clientId, scopes, state, redirectUri, baseUr
     if (!scopes?.length) {
         throw new Error('At least one scope value is required.');
     }
-    const authBaseUrl = baseUrl ? `${baseUrl}/oauth` : 'https://comms.todoist.com/oauth';
+    const authBaseUrl = `${getAuthBaseUrl(baseUrl)}/oauth`;
     const scope = scopes.join(' ');
     const params = new URLSearchParams({
         client_id: clientId,
@@ -119,9 +132,7 @@ export function getAuthorizationUrl(clientId, scopes, state, redirectUri, baseUr
     return `${authBaseUrl}/authorize?${params.toString()}`;
 }
 export async function getAuthToken(args, options) {
-    const tokenUrl = options?.baseUrl
-        ? `${options.baseUrl}/oauth/token`
-        : 'https://comms.todoist.com/oauth/token';
+    const tokenUrl = `${getAuthBaseUrl(options?.baseUrl)}/oauth/access_token`;
     const payload = {
         clientId: args.clientId,
         clientSecret: args.clientSecret,
@@ -141,10 +152,45 @@ export async function getAuthToken(args, options) {
     }
     return response.data;
 }
+/**
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * @example
+ * ```typescript
+ * const { accessToken, refreshToken } = await refreshAuthToken({
+ *   clientId: 'client-id',
+ *   clientSecret: 'client-secret',
+ *   refreshToken: storedRefreshToken,
+ * })
+ * ```
+ *
+ * @returns The refreshed token. The response may include a new `refreshToken`
+ * (rotated by the server); persist it in place of the previous one when present.
+ * @throws {@link CommsRequestError} If the refresh fails
+ */
+export async function refreshAuthToken(args, options) {
+    const tokenUrl = `${getAuthBaseUrl(options?.baseUrl)}/oauth/access_token`;
+    const payload = {
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+        refreshToken: args.refreshToken,
+        grantType: 'refresh_token',
+    };
+    const response = await request({
+        httpMethod: 'POST',
+        baseUri: tokenUrl,
+        relativePath: '',
+        payload,
+        customFetch: options?.customFetch,
+    });
+    if (!isSuccess(response) || !response.data?.accessToken) {
+        throw new CommsRequestError('Authentication token refresh failed.', response.status, response.data);
+    }
+    return response.data;
+}
 export async function revokeAuthToken(args, options) {
-    const revokeUrl = options?.baseUrl
-        ? `${options.baseUrl}/oauth/revoke`
-        : 'https://comms.todoist.com/oauth/revoke';
+    const revokeUrl = `${getAuthBaseUrl(options?.baseUrl)}/api/v1/revoke`;
     const response = await request({
         httpMethod: 'POST',
         baseUri: revokeUrl,
@@ -176,9 +222,7 @@ export async function revokeAuthToken(args, options) {
  * @see {@link https://datatracker.ietf.org/doc/html/rfc7591 RFC 7591}
  */
 export async function registerClient(args, options) {
-    const registerUrl = options?.baseUrl
-        ? `${options.baseUrl}/oauth/register`
-        : 'https://comms.todoist.com/oauth/register';
+    const registerUrl = `${getAuthBaseUrl(options?.baseUrl)}/oauth/register`;
     const response = await request({
         httpMethod: 'POST',
         baseUri: registerUrl,

package/dist/esm/testUtils/test-defaults.js

@@ -32,7 +32,7 @@ export const mockChannel = {
     archived: false,
     created: new Date('2021-01-01T00:00:00Z'),
     version: 0,
-    url: `https://comms.todoist.com/a/1/ch/${TEST_CHANNEL_ID}/`,
+    url: `https://comms.todoist.com/1/ch/${TEST_CHANNEL_ID}/`,
 };
 export const mockThread = {
     id: TEST_THREAD_ID,
@@ -48,7 +48,7 @@ export const mockThread = {
     snippet: 'This is a test thread',
     snippetCreator: 1,
     isArchived: false,
-    url: `https://comms.todoist.com/a/1/ch/${TEST_CHANNEL_ID}/t/${TEST_THREAD_ID}/`,
+    url: `https://comms.todoist.com/1/ch/${TEST_CHANNEL_ID}/t/${TEST_THREAD_ID}/`,
 };
 export const mockGroup = {
     id: TEST_GROUP_ID,
@@ -69,7 +69,7 @@ export const mockConversation = {
     archived: false,
     created: new Date('2021-01-01T00:00:00Z'),
     creator: 1,
-    url: `https://comms.todoist.com/a/1/msg/${TEST_CONVERSATION_ID}/`,
+    url: `https://comms.todoist.com/1/msg/${TEST_CONVERSATION_ID}/`,
 };
 export const mockComment = {
     id: TEST_COMMENT_ID,
@@ -79,7 +79,7 @@ export const mockComment = {
     workspaceId: 1,
     channelId: TEST_CHANNEL_ID,
     posted: new Date('2021-01-01T00:00:00Z'),
-    url: `https://comms.todoist.com/a/1/ch/${TEST_CHANNEL_ID}/t/${TEST_THREAD_ID}/c/${TEST_COMMENT_ID}`,
+    url: `https://comms.todoist.com/1/ch/${TEST_CHANNEL_ID}/t/${TEST_THREAD_ID}/c/${TEST_COMMENT_ID}`,
 };
 export const mockWorkspaceUser = {
     id: 1,

package/dist/esm/utils/url-helpers.js

@@ -1,5 +1,5 @@
 /**
- * Helper functions for creating Comms permalinks (`https://comms.todoist.com/a/...`).
+ * Helper functions for creating Comms permalinks (`https://comms.todoist.com/...`).
  */
 const COMMS_BASE_URL = 'https://comms.todoist.com';
 /**
@@ -8,11 +8,11 @@ const COMMS_BASE_URL = 'https://comms.todoist.com';
  * @returns A relative URL path
  * @example
  * getCommsURL({ workspaceId: 1, channelId: '7Yp...', threadId: '7Yq...' })
- * // returns '/a/1/ch/7Yp.../t/7Yq.../'
+ * // returns '/1/ch/7Yp.../t/7Yq.../'
  */
 export function getCommsURL(params) {
     const { workspaceId, channelId, conversationId, threadId, commentId, messageId, userId } = params;
-    let url = `/a/${workspaceId}/`;
+    let url = `/${workspaceId}/`;
     if (channelId) {
         url += `ch/${channelId}/`;
         if (threadId) {
@@ -71,44 +71,44 @@ export function getCommentURL(params) {
 }
 /** Returns the URL for the threads root (channels view). */
 export function getThreadsRootURL(workspaceId) {
-    return `/a/${workspaceId}/ch`;
+    return `/${workspaceId}/ch`;
 }
 /** Returns the URL for the inbox. */
 export function getInboxURL(workspaceId, tab) {
     const tabParam = tab ? `/${tab}` : '';
-    return `/a/${workspaceId}/inbox${tabParam}`;
+    return `/${workspaceId}/inbox${tabParam}`;
 }
 /** Returns the URL for the messages/conversations root. */
 export function getMessagesRootURL(workspaceId) {
-    return `/a/${workspaceId}/msg`;
+    return `/${workspaceId}/msg`;
 }
 /** Returns the URL for a user profile. */
 export function getUserProfileURL(params) {
-    return `/a/${params.workspaceId}/people/u/${params.userId}`;
+    return `/${params.workspaceId}/people/u/${params.userId}`;
 }
 /** Returns the URL for the saved threads view. */
 export function getSavedThreadsRootURL(workspaceId) {
-    return `/a/${workspaceId}/saved`;
+    return `/${workspaceId}/saved`;
 }
 /** Returns the URL for a saved thread. */
 export function getSavedThreadURL(params) {
-    return `/a/${params.workspaceId}/saved/t/${params.threadId}`;
+    return `/${params.workspaceId}/saved/t/${params.threadId}`;
 }
 /** Returns the URL for the search root. */
 export function getSearchRootURL(workspaceId) {
-    return `/a/${workspaceId}/search`;
+    return `/${workspaceId}/search`;
 }
 /** Returns the URL for a search with a query. */
 export function getSearchQueryURL(params) {
-    return `/a/${params.workspaceId}/search?q=${decodeURIComponent(params.query)}`;
+    return `/${params.workspaceId}/search?q=${decodeURIComponent(params.query)}`;
 }
 /** Returns the URL for settings. */
 export function getSettingsURL(params) {
     return params.initialLocation
-        ? `/a/${params.workspaceId}/settings/${params.initialLocation}`
-        : `/a/${params.workspaceId}/settings`;
+        ? `/${params.workspaceId}/settings/${params.initialLocation}`
+        : `/${params.workspaceId}/settings`;
 }
 /** Returns the URL for the team members root. */
 export function getTeamMembersRootURL(workspaceId) {
-    return `/a/${workspaceId}/people/u`;
+    return `/${workspaceId}/people/u`;
 }

package/dist/types/authentication.d.ts

@@ -78,6 +78,11 @@ export type AuthTokenResponse = {
     expiresIn?: number;
     scope?: string;
 };
+export type RefreshAuthTokenRequestArgs = {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+};
 export type RevokeAuthTokenRequestArgs = {
     clientId: string;
     clientSecret: string;
@@ -138,6 +143,24 @@ export declare function getAuthStateParameter(): string;
  */
 export declare function getAuthorizationUrl(clientId: string, scopes: CommsScope[], state: string, redirectUri?: string, baseUrl?: string): string;
 export declare function getAuthToken(args: AuthTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
+/**
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * @example
+ * ```typescript
+ * const { accessToken, refreshToken } = await refreshAuthToken({
+ *   clientId: 'client-id',
+ *   clientSecret: 'client-secret',
+ *   refreshToken: storedRefreshToken,
+ * })
+ * ```
+ *
+ * @returns The refreshed token. The response may include a new `refreshToken`
+ * (rotated by the server); persist it in place of the previous one when present.
+ * @throws {@link CommsRequestError} If the refresh fails
+ */
+export declare function refreshAuthToken(args: RefreshAuthTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
 export declare function revokeAuthToken(args: RevokeAuthTokenRequestArgs, options?: AuthOptions): Promise<boolean>;
 /**
  * Registers a new OAuth client via Dynamic Client Registration (RFC 7591).

package/dist/types/utils/url-helpers.d.ts

@@ -1,5 +1,5 @@
 /**
- * Helper functions for creating Comms permalinks (`https://comms.todoist.com/a/...`).
+ * Helper functions for creating Comms permalinks (`https://comms.todoist.com/...`).
  */
 export type CommsURLParams = {
     workspaceId: number;
@@ -16,7 +16,7 @@ export type CommsURLParams = {
  * @returns A relative URL path
  * @example
  * getCommsURL({ workspaceId: 1, channelId: '7Yp...', threadId: '7Yq...' })
- * // returns '/a/1/ch/7Yp.../t/7Yq.../'
+ * // returns '/1/ch/7Yp.../t/7Yq.../'
  */
 export declare function getCommsURL(params: CommsURLParams): string;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "0.4.5",
+    "version": "0.5.0",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",