@doist/todoist-sdk 10.4.1 → 10.5.0

package/README.md

@@ -104,6 +104,27 @@ await revokeToken(args, {
 const { accessToken } = await getAuthToken(args, baseUrl)
 ```
 
+When the authorization server issues a `refreshToken`, use `refreshAuthToken`
+to obtain a new access token once the current one expires, without sending the
+user back through the authorization flow:
+
+```typescript
+const refreshed = await refreshAuthToken({
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    refreshToken: storedRefreshToken,
+})
+
+// The server may rotate the refresh token — persist refreshed.refreshToken
+// when present, otherwise keep using the previous one.
+```
+
+> **Note:** Refresh tokens are only issued to OAuth apps that have them enabled
+> (the default for new apps). Apps without them receive a long-lived access
+> token, so `getAuthToken` returns no `refreshToken` and there is nothing to
+> refresh. For public clients (`tokenEndpointAuthMethod: 'none'`), omit
+> `clientSecret` when calling `refreshAuthToken`.
+
 ### Important Notes
 
 - All existing transforms (snake_case ↔ camelCase) work automatically with custom fetch

package/dist/cjs/authentication.js

@@ -15,6 +15,7 @@ exports.TOKEN_ENDPOINT_AUTH_METHODS = exports.PERMISSIONS = void 0;
 exports.getAuthStateParameter = getAuthStateParameter;
 exports.getAuthorizationUrl = getAuthorizationUrl;
 exports.getAuthToken = getAuthToken;
+exports.refreshAuthToken = refreshAuthToken;
 exports.revokeToken = revokeToken;
 exports.migratePersonalToken = migratePersonalToken;
 exports.registerClient = registerClient;
@@ -108,32 +109,74 @@ function getAuthorizationUrl({ clientId, permissions, state, baseUrl, }) {
  * @returns The access token response
  * @throws {@link TodoistRequestError} If the token exchange fails
  */
-async function getAuthToken(args, options) {
+/**
+ * Posts a payload to the OAuth token endpoint and returns the token response,
+ * mapping any failure to a {@link TodoistRequestError} with `errorMessage`.
+ * Shared by {@link getAuthToken} and {@link refreshAuthToken}.
+ */
+async function requestAuthToken(payload, errorMessage, options) {
     var _a;
-    if (typeof options === 'string') {
-        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
-    }
-    const baseUrl = options === null || options === void 0 ? void 0 : options.baseUrl;
-    const customFetch = options === null || options === void 0 ? void 0 : options.customFetch;
     try {
         const response = await (0, http_client_1.request)({
             httpMethod: 'POST',
-            baseUri: (0, endpoints_1.getAuthBaseUri)(baseUrl),
+            baseUri: (0, endpoints_1.getAuthBaseUri)(options === null || options === void 0 ? void 0 : options.baseUrl),
             relativePath: endpoints_1.ENDPOINT_GET_TOKEN,
             apiToken: undefined,
-            payload: args,
-            customFetch,
+            payload,
+            customFetch: options === null || options === void 0 ? void 0 : options.customFetch,
         });
         if (response.status !== 200 || !((_a = response.data) === null || _a === void 0 ? void 0 : _a.accessToken)) {
-            throw new types_1.TodoistRequestError('Authentication token exchange failed.', response.status, response.data);
+            throw new types_1.TodoistRequestError(errorMessage, response.status, response.data);
         }
         return response.data;
     }
     catch (error) {
         // Re-throw with custom message for authentication failures
         const err = error;
-        throw new types_1.TodoistRequestError('Authentication token exchange failed.', err.httpStatusCode, err.responseData);
+        throw new types_1.TodoistRequestError(errorMessage, err.httpStatusCode, err.responseData);
+    }
+}
+async function getAuthToken(args, options) {
+    if (typeof options === 'string') {
+        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
+    }
+    return requestAuthToken(Object.assign({}, args), 'Authentication token exchange failed.', options);
+}
+/**
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * Only relevant for OAuth apps that have refresh tokens enabled (the default for
+ * new apps). Apps without them never receive a `refreshToken` from
+ * {@link getAuthToken}, so they have nothing to pass here — their access tokens
+ * are long-lived instead.
+ *
+ * Omit `clientSecret` for public clients registered with
+ * `tokenEndpointAuthMethod: 'none'`.
+ *
+ * @example
+ * ```typescript
+ * const { accessToken, refreshToken } = await refreshAuthToken({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   refreshToken: storedRefreshToken,
+ * })
+ * ```
+ *
+ * @returns The refreshed token. The server rotates the refresh token, so the
+ * response carries a new `refreshToken` — persist it in place of the old one.
+ * @throws {@link TodoistRequestError} If the refresh fails
+ */
+async function refreshAuthToken(args, options) {
+    const payload = {
+        clientId: args.clientId,
+        refreshToken: args.refreshToken,
+        grantType: 'refresh_token',
+    };
+    if (args.clientSecret !== undefined) {
+        payload.clientSecret = args.clientSecret;
     }
+    return requestAuthToken(payload, 'Authentication token refresh failed.', options);
 }
 /**
  * Revokes a token using the RFC 7009 OAuth 2.0 Token Revocation standard.

package/dist/esm/authentication.js

@@ -99,32 +99,74 @@ export function getAuthorizationUrl({ clientId, permissions, state, baseUrl, })
  * @returns The access token response
  * @throws {@link TodoistRequestError} If the token exchange fails
  */
-export async function getAuthToken(args, options) {
+/**
+ * Posts a payload to the OAuth token endpoint and returns the token response,
+ * mapping any failure to a {@link TodoistRequestError} with `errorMessage`.
+ * Shared by {@link getAuthToken} and {@link refreshAuthToken}.
+ */
+async function requestAuthToken(payload, errorMessage, options) {
     var _a;
-    if (typeof options === 'string') {
-        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
-    }
-    const baseUrl = options === null || options === void 0 ? void 0 : options.baseUrl;
-    const customFetch = options === null || options === void 0 ? void 0 : options.customFetch;
     try {
         const response = await request({
             httpMethod: 'POST',
-            baseUri: getAuthBaseUri(baseUrl),
+            baseUri: getAuthBaseUri(options === null || options === void 0 ? void 0 : options.baseUrl),
             relativePath: ENDPOINT_GET_TOKEN,
             apiToken: undefined,
-            payload: args,
-            customFetch,
+            payload,
+            customFetch: options === null || options === void 0 ? void 0 : options.customFetch,
         });
         if (response.status !== 200 || !((_a = response.data) === null || _a === void 0 ? void 0 : _a.accessToken)) {
-            throw new TodoistRequestError('Authentication token exchange failed.', response.status, response.data);
+            throw new TodoistRequestError(errorMessage, response.status, response.data);
         }
         return response.data;
     }
     catch (error) {
         // Re-throw with custom message for authentication failures
         const err = error;
-        throw new TodoistRequestError('Authentication token exchange failed.', err.httpStatusCode, err.responseData);
+        throw new TodoistRequestError(errorMessage, err.httpStatusCode, err.responseData);
+    }
+}
+export async function getAuthToken(args, options) {
+    if (typeof options === 'string') {
+        throw new TypeError('Passing baseUrl as a string is no longer supported. Use an options object instead: getAuthToken(args, { baseUrl })');
+    }
+    return requestAuthToken(Object.assign({}, args), 'Authentication token exchange failed.', options);
+}
+/**
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * Only relevant for OAuth apps that have refresh tokens enabled (the default for
+ * new apps). Apps without them never receive a `refreshToken` from
+ * {@link getAuthToken}, so they have nothing to pass here — their access tokens
+ * are long-lived instead.
+ *
+ * Omit `clientSecret` for public clients registered with
+ * `tokenEndpointAuthMethod: 'none'`.
+ *
+ * @example
+ * ```typescript
+ * const { accessToken, refreshToken } = await refreshAuthToken({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   refreshToken: storedRefreshToken,
+ * })
+ * ```
+ *
+ * @returns The refreshed token. The server rotates the refresh token, so the
+ * response carries a new `refreshToken` — persist it in place of the old one.
+ * @throws {@link TodoistRequestError} If the refresh fails
+ */
+export async function refreshAuthToken(args, options) {
+    const payload = {
+        clientId: args.clientId,
+        refreshToken: args.refreshToken,
+        grantType: 'refresh_token',
+    };
+    if (args.clientSecret !== undefined) {
+        payload.clientSecret = args.clientSecret;
     }
+    return requestAuthToken(payload, 'Authentication token refresh failed.', options);
 }
 /**
  * Revokes a token using the RFC 7009 OAuth 2.0 Token Revocation standard.

package/dist/types/authentication.d.ts

@@ -74,6 +74,31 @@ export type AuthTokenRequestArgs = {
 export type AuthTokenResponse = {
     accessToken: string;
     tokenType: string;
+    /**
+     * Refresh token for use with {@link refreshAuthToken}.
+     *
+     * Only present when the OAuth app has refresh tokens enabled — the default
+     * for new apps, and immutable once on. Apps without it receive a long-lived
+     * access token and no refresh token.
+     */
+    refreshToken?: string;
+    /** Access token lifetime in seconds. */
+    expiresIn?: number;
+    /** Space-separated granted scopes, when returned. */
+    scope?: string;
+};
+/**
+ * Parameters required to exchange a refresh token for a new access token.
+ * @see https://developer.todoist.com/api/v1/#tag/Authorization/OAuth
+ */
+export type RefreshTokenRequestArgs = {
+    clientId: string;
+    /**
+     * Client secret. Required for confidential clients; omit for public clients
+     * registered with `tokenEndpointAuthMethod: 'none'`.
+     */
+    clientSecret?: string;
+    refreshToken: string;
 };
 /**
  * Parameters required to revoke a token using RFC 7009 compliant endpoint.
@@ -148,22 +173,33 @@ export declare function getAuthorizationUrl({ clientId, permissions, state, base
     state: string;
     baseUrl?: string;
 }): string;
+export declare function getAuthToken(args: AuthTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
 /**
- * Exchanges an authorization code for an access token.
+ * Exchanges a refresh token for a new access token using the OAuth2
+ * `refresh_token` grant.
+ *
+ * Only relevant for OAuth apps that have refresh tokens enabled (the default for
+ * new apps). Apps without them never receive a `refreshToken` from
+ * {@link getAuthToken}, so they have nothing to pass here — their access tokens
+ * are long-lived instead.
+ *
+ * Omit `clientSecret` for public clients registered with
+ * `tokenEndpointAuthMethod: 'none'`.
  *
  * @example
  * ```typescript
- * const { accessToken } = await getAuthToken({
+ * const { accessToken, refreshToken } = await refreshAuthToken({
  *   clientId: 'your-client-id',
  *   clientSecret: 'your-client-secret',
- *   code: authCode
+ *   refreshToken: storedRefreshToken,
  * })
  * ```
  *
- * @returns The access token response
- * @throws {@link TodoistRequestError} If the token exchange fails
+ * @returns The refreshed token. The server rotates the refresh token, so the
+ * response carries a new `refreshToken` — persist it in place of the old one.
+ * @throws {@link TodoistRequestError} If the refresh fails
  */
-export declare function getAuthToken(args: AuthTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
+export declare function refreshAuthToken(args: RefreshTokenRequestArgs, options?: AuthOptions): Promise<AuthTokenResponse>;
 /**
  * Revokes a token using the RFC 7009 OAuth 2.0 Token Revocation standard.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/todoist-sdk",
-    "version": "10.4.1",
+    "version": "10.5.0",
     "description": "The official TypeScript SDK for the Todoist REST API.",
     "author": "Doist developers",
     "repository": "https://github.com/Doist/todoist-sdk-typescript",