@doist/comms-sdk 0.4.6 → 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/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/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/package.json

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