@logto/client 2.2.0 → 2.2.2

package/lib/adapter/types.d.ts

@@ -22,13 +22,23 @@ export declare enum CacheKey {
      */
     Jwks = "jwks"
 }
+/**
+ * The storage object that allows the client to persist data.
+ *
+ * It's compatible with the `localStorage` API.
+ */
 export type Storage<Keys extends string> = {
     getItem(key: Keys): Promise<Nullable<string>>;
     setItem(key: Keys, value: string): Promise<void>;
     removeItem(key: Keys): Promise<void>;
 };
 export type InferStorageKey<S> = S extends Storage<infer Key> ? Key : never;
-export type Navigate = (url: string) => void;
+/** The navigation function that redirects the user to the specified URL. */
+export type Navigate = (url: string) => void | Promise<void>;
+/**
+ * The adapter object that allows the customizations of the client behavior
+ * for different environments.
+ */
 export type ClientAdapter = {
     requester: Requester;
     storage: Storage<StorageKey | PersistKey>;
@@ -39,7 +49,26 @@ export type ClientAdapter = {
      */
     unstable_cache?: Storage<CacheKey>;
     navigate: Navigate;
+    /**
+     * The function that generates a random state string.
+     *
+     * @returns The state string.
+     */
     generateState: () => string;
+    /**
+     * The function that generates a random code verifier string for PKCE.
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7636.html| RFC 7636}
+     * @returns The code verifier string.
+     */
     generateCodeVerifier: () => string;
+    /**
+     * The function that generates a code challenge string based on the code verifier
+     * for PKCE.
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7636.html| RFC 7636}
+     * @param codeVerifier The code verifier string.
+     * @returns The code challenge string.
+     */
     generateCodeChallenge: (codeVerifier: string) => Promise<string>;
 };

package/lib/errors.cjs

@@ -5,10 +5,12 @@ const logtoClientErrorCodes = Object.freeze({
     'sign_in_session.not_found': 'Sign-in session not found.',
     not_authenticated: 'Not authenticated.',
     fetch_user_info_failed: 'Unable to fetch user info. The access token may be invalid.',
+    user_cancelled: 'The user cancelled the action.',
 });
 class LogtoClientError extends Error {
     constructor(code, data) {
         super(logtoClientErrorCodes[code]);
+        this.name = 'LogtoClientError';
         this.code = code;
         this.data = data;
     }

package/lib/errors.d.ts

@@ -3,9 +3,11 @@ declare const logtoClientErrorCodes: Readonly<{
     'sign_in_session.not_found': "Sign-in session not found.";
     not_authenticated: "Not authenticated.";
     fetch_user_info_failed: "Unable to fetch user info. The access token may be invalid.";
+    user_cancelled: "The user cancelled the action.";
 }>;
 export type LogtoClientErrorCode = keyof typeof logtoClientErrorCodes;
 export declare class LogtoClientError extends Error {
+    name: string;
     code: LogtoClientErrorCode;
     data: unknown;
     constructor(code: LogtoClientErrorCode, data?: unknown);

package/lib/errors.js

@@ -3,10 +3,12 @@ const logtoClientErrorCodes = Object.freeze({
     'sign_in_session.not_found': 'Sign-in session not found.',
     not_authenticated: 'Not authenticated.',
     fetch_user_info_failed: 'Unable to fetch user info. The access token may be invalid.',
+    user_cancelled: 'The user cancelled the action.',
 });
 class LogtoClientError extends Error {
     constructor(code, data) {
         super(logtoClientErrorCodes[code]);
+        this.name = 'LogtoClientError';
         this.code = code;
         this.data = data;
     }

package/lib/index.cjs

@@ -14,6 +14,13 @@ var once = require('./utils/once.cjs');
 var types = require('./adapter/types.cjs');
 var requester = require('./utils/requester.cjs');
 
+/**
+ * The Logto base client class that provides the essential methods for
+ * interacting with the Logto server.
+ *
+ * It also provides an adapter object that allows the customizations of the
+ * client behavior for different environments.
+ */
 class LogtoClient {
     constructor(logtoConfig, adapter) {
         this.getOidcConfig = memoize.memoize(this.#getOidcConfig);
@@ -27,15 +34,37 @@ class LogtoClient {
         this.adapter = new index$1.ClientAdapterInstance(adapter);
         void this.loadAccessTokenMap();
     }
+    /**
+     * Check if the user is authenticated by checking if the ID token exists.
+     */
     async isAuthenticated() {
         return Boolean(await this.getIdToken());
     }
+    /**
+     * Get the Refresh Token from the storage.
+     */
     async getRefreshToken() {
         return this.adapter.storage.getItem('refreshToken');
     }
+    /**
+     * Get the ID Token from the storage. If you want to get the ID Token claims,
+     * use {@link getIdTokenClaims} instead.
+     */
     async getIdToken() {
         return this.adapter.storage.getItem('idToken');
     }
+    /**
+     * Get the Access Token from the storage. If the Access Token has expired, it
+     * will try to fetch a new one using the Refresh Token.
+     *
+     * If you want to get the Access Token claims, use {@link getAccessTokenClaims} instead.
+     *
+     * @param resource The resource that the Access Token is granted for. If not
+     * specified, the Access Token will be used for OpenID Connect or the default
+     * resource, as specified in the Logto Console.
+     * @returns The Access Token string.
+     * @throws LogtoClientError if the user is not authenticated.
+     */
     async getAccessToken(resource) {
         if (!(await this.getIdToken())) {
             throw new errors.LogtoClientError('not_authenticated');
@@ -54,6 +83,9 @@ class LogtoClient {
          */
         return this.getAccessTokenByRefreshToken(resource);
     }
+    /**
+     * Get the ID Token claims.
+     */
     async getIdTokenClaims() {
         const idToken = await this.getIdToken();
         if (!idToken) {
@@ -61,10 +93,27 @@ class LogtoClient {
         }
         return js.decodeIdToken(idToken);
     }
+    /**
+     * Get the Access Token claims for the specified resource.
+     *
+     * @param resource The resource that the Access Token is granted for. If not
+     * specified, the Access Token will be used for OpenID Connect or the default
+     * resource, as specified in the Logto Console.
+     */
     async getAccessTokenClaims(resource) {
         const accessToken = await this.getAccessToken(resource);
         return js.decodeAccessToken(accessToken);
     }
+    /**
+     * Get the user information from the Userinfo Endpoint.
+     *
+     * Note the Userinfo Endpoint will return more claims than the ID Token. See
+     * {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#fetch-user-information | Fetch user information}
+     * for more information.
+     *
+     * @returns The user information.
+     * @throws LogtoClientError if the user is not authenticated.
+     */
     async fetchUserInfo() {
         const { userinfoEndpoint } = await this.getOidcConfig();
         const accessToken = await this.getAccessToken();
@@ -73,6 +122,22 @@ class LogtoClient {
         }
         return js.fetchUserInfo(userinfoEndpoint, accessToken, this.adapter.requester);
     }
+    /**
+     * Start the sign-in flow with the specified redirect URI. The URI must be
+     * registered in the Logto Console.
+     *
+     * The user will be redirected to that URI after the sign-in flow is completed,
+     * and the client will be able to get the authorization code from the URI.
+     * To fetch the tokens from the authorization code, use {@link handleSignInCallback}
+     * after the user is redirected in the callback URI.
+     *
+     * @param redirectUri The redirect URI that the user will be redirected to after the sign-in flow is completed.
+     * @param interactionMode The interaction mode to be used for the authorization request. Note it's not
+     * a part of the OIDC standard, but a Logto-specific extension. Defaults to `signIn`.
+     *
+     * @see {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#sign-in | Sign in} for more information.
+     * @see {@link InteractionMode}
+     */
     async signIn(redirectUri, interactionMode) {
         const { appId: clientId, prompt, resources, scopes } = this.logtoConfig;
         const { authorizationEndpoint } = await this.getOidcConfig();
@@ -90,11 +155,21 @@ class LogtoClient {
             prompt,
             interactionMode,
         });
-        await this.setSignInSession({ redirectUri, codeVerifier, state });
-        await this.setRefreshToken(null);
-        await this.setIdToken(null);
-        this.adapter.navigate(signInUri);
+        await Promise.all([
+            this.setSignInSession({ redirectUri, codeVerifier, state }),
+            this.setRefreshToken(null),
+            this.setIdToken(null),
+        ]);
+        await this.adapter.navigate(signInUri);
     }
+    /**
+     * Check if the user is redirected from the sign-in page by checking if the
+     * current URL matches the redirect URI in the sign-in session.
+     *
+     * If there's no sign-in session, it will return `false`.
+     *
+     * @param url The current URL.
+     */
     async isSignInRedirected(url) {
         const signInSession = await this.getSignInSession();
         if (!signInSession) {
@@ -104,28 +179,59 @@ class LogtoClient {
         const { origin, pathname } = new URL(url);
         return `${origin}${pathname}` === redirectUri;
     }
+    /**
+     * Handle the sign-in callback by parsing the authorization code from the
+     * callback URI and exchanging it for the tokens.
+     *
+     * @param callbackUri The callback URI that the user is redirected to after the sign-in flow is completed.
+     * This URI must match the redirect URI specified in {@link signIn}.
+     * @throws LogtoClientError if the sign-in session is not found.
+     */
     async handleSignInCallback(callbackUri) {
-        const { logtoConfig, adapter } = this;
-        const { requester } = adapter;
+        const { requester } = this.adapter;
         const signInSession = await this.getSignInSession();
         if (!signInSession) {
             throw new errors.LogtoClientError('sign_in_session.not_found');
         }
         const { redirectUri, state, codeVerifier } = signInSession;
         const code = js.verifyAndParseCodeFromCallbackUri(callbackUri, redirectUri, state);
-        const { appId: clientId } = logtoConfig;
+        // NOTE: Will add scope to accessTokenKey when needed. (Linear issue LOG-1589)
+        const accessTokenKey = index$2.buildAccessTokenKey();
+        const { appId: clientId } = this.logtoConfig;
         const { tokenEndpoint } = await this.getOidcConfig();
-        const codeTokenResponse = await js.fetchTokenByAuthorizationCode({
+        const requestedAt = Math.round(Date.now() / 1000);
+        const { idToken, refreshToken, accessToken, scope, expiresIn } = await js.fetchTokenByAuthorizationCode({
             clientId,
             tokenEndpoint,
             redirectUri,
             codeVerifier,
             code,
         }, requester);
-        await this.verifyIdToken(codeTokenResponse.idToken);
-        await this.saveCodeToken(codeTokenResponse);
+        await this.verifyIdToken(idToken);
+        await this.setRefreshToken(refreshToken ?? null);
+        await this.setIdToken(idToken);
+        this.accessTokenMap.set(accessTokenKey, {
+            token: accessToken,
+            scope,
+            /** The `expiresAt` variable provides an approximate estimation of the actual `exp` property
+             * in the token claims. It is utilized by the client to determine if the cached access token
+             * has expired and when a new access token should be requested.
+             */
+            expiresAt: requestedAt + expiresIn,
+        });
+        await this.saveAccessTokenMap();
         await this.setSignInSession(null);
     }
+    /**
+     * Start the sign-out flow with the specified redirect URI. The URI must be
+     * registered in the Logto Console.
+     *
+     * It will also revoke all the tokens and clean up the storage.
+     *
+     * The user will be redirected that URI after the sign-out flow is completed.
+     * If the `postLogoutRedirectUri` is not specified, the user will be redirected
+     * to a default page.
+     */
     async signOut(postLogoutRedirectUri) {
         const { appId: clientId } = this.logtoConfig;
         const { endSessionEndpoint, revocationEndpoint } = await this.getOidcConfig();
@@ -144,10 +250,12 @@ class LogtoClient {
             clientId,
         });
         this.accessTokenMap.clear();
-        await this.setRefreshToken(null);
-        await this.setIdToken(null);
-        await this.adapter.storage.removeItem('accessToken');
-        this.adapter.navigate(url);
+        await Promise.all([
+            this.setRefreshToken(null),
+            this.setIdToken(null),
+            this.adapter.storage.removeItem('accessToken'),
+        ]);
+        await this.adapter.navigate(url);
     }
     async getSignInSession() {
         const jsonItem = await this.adapter.storage.getItem('signInSession');
@@ -177,6 +285,7 @@ class LogtoClient {
         const accessTokenKey = index$2.buildAccessTokenKey(resource);
         const { appId: clientId } = this.logtoConfig;
         const { tokenEndpoint } = await this.getOidcConfig();
+        const requestedAt = Math.round(Date.now() / 1000);
         const { accessToken, refreshToken, idToken, scope, expiresIn } = await js.fetchTokenByRefreshToken({
             clientId,
             tokenEndpoint,
@@ -186,7 +295,11 @@ class LogtoClient {
         this.accessTokenMap.set(accessTokenKey, {
             token: accessToken,
             scope,
-            expiresAt: Math.round(Date.now() / 1000) + expiresIn,
+            /** The `expiresAt` variable provides an approximate estimation of the actual `exp` property
+             * in the token claims. It is utilized by the client to determine if the cached access token
+             * has expired and when a new access token should be requested.
+             */
+            expiresAt: requestedAt + expiresIn,
         });
         await this.saveAccessTokenMap();
         await this.setRefreshToken(refreshToken);
@@ -202,15 +315,6 @@ class LogtoClient {
         const jwtVerifyGetKey = await this.getJwtVerifyGetKey();
         await js.verifyIdToken(idToken, appId, issuer, jwtVerifyGetKey);
     }
-    async saveCodeToken({ refreshToken, idToken, scope, accessToken, expiresIn, }) {
-        await this.setRefreshToken(refreshToken ?? null);
-        await this.setIdToken(idToken);
-        // NOTE: Will add scope to accessTokenKey when needed. (Linear issue LOG-1589)
-        const accessTokenKey = index$2.buildAccessTokenKey();
-        const expiresAt = Date.now() / 1000 + expiresIn;
-        this.accessTokenMap.set(accessTokenKey, { token: accessToken, scope, expiresAt });
-        await this.saveAccessTokenMap();
-    }
     async saveAccessTokenMap() {
         const data = {};
         for (const [key, accessToken] of this.accessTokenMap.entries()) {

package/lib/index.d.ts

@@ -10,6 +10,13 @@ export type { Storage, StorageKey, ClientAdapter } from './adapter/index.js';
 export { PersistKey, CacheKey } from './adapter/index.js';
 export { createRequester } from './utils/index.js';
 export * from './types/index.js';
+/**
+ * The Logto base client class that provides the essential methods for
+ * interacting with the Logto server.
+ *
+ * It also provides an adapter object that allows the customizations of the
+ * client behavior for different environments.
+ */
 export default class LogtoClient {
     #private;
     protected readonly logtoConfig: LogtoConfig;
@@ -26,16 +33,100 @@ export default class LogtoClient {
     protected readonly adapter: ClientAdapterInstance;
     protected readonly accessTokenMap: Map<string, AccessToken>;
     constructor(logtoConfig: LogtoConfig, adapter: ClientAdapter);
+    /**
+     * Check if the user is authenticated by checking if the ID token exists.
+     */
     isAuthenticated(): Promise<boolean>;
+    /**
+     * Get the Refresh Token from the storage.
+     */
     getRefreshToken(): Promise<Nullable<string>>;
+    /**
+     * Get the ID Token from the storage. If you want to get the ID Token claims,
+     * use {@link getIdTokenClaims} instead.
+     */
     getIdToken(): Promise<Nullable<string>>;
+    /**
+     * Get the Access Token from the storage. If the Access Token has expired, it
+     * will try to fetch a new one using the Refresh Token.
+     *
+     * If you want to get the Access Token claims, use {@link getAccessTokenClaims} instead.
+     *
+     * @param resource The resource that the Access Token is granted for. If not
+     * specified, the Access Token will be used for OpenID Connect or the default
+     * resource, as specified in the Logto Console.
+     * @returns The Access Token string.
+     * @throws LogtoClientError if the user is not authenticated.
+     */
     getAccessToken(resource?: string): Promise<string>;
+    /**
+     * Get the ID Token claims.
+     */
     getIdTokenClaims(): Promise<IdTokenClaims>;
+    /**
+     * Get the Access Token claims for the specified resource.
+     *
+     * @param resource The resource that the Access Token is granted for. If not
+     * specified, the Access Token will be used for OpenID Connect or the default
+     * resource, as specified in the Logto Console.
+     */
     getAccessTokenClaims(resource?: string): Promise<AccessTokenClaims>;
+    /**
+     * Get the user information from the Userinfo Endpoint.
+     *
+     * Note the Userinfo Endpoint will return more claims than the ID Token. See
+     * {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#fetch-user-information | Fetch user information}
+     * for more information.
+     *
+     * @returns The user information.
+     * @throws LogtoClientError if the user is not authenticated.
+     */
     fetchUserInfo(): Promise<UserInfoResponse>;
+    /**
+     * Start the sign-in flow with the specified redirect URI. The URI must be
+     * registered in the Logto Console.
+     *
+     * The user will be redirected to that URI after the sign-in flow is completed,
+     * and the client will be able to get the authorization code from the URI.
+     * To fetch the tokens from the authorization code, use {@link handleSignInCallback}
+     * after the user is redirected in the callback URI.
+     *
+     * @param redirectUri The redirect URI that the user will be redirected to after the sign-in flow is completed.
+     * @param interactionMode The interaction mode to be used for the authorization request. Note it's not
+     * a part of the OIDC standard, but a Logto-specific extension. Defaults to `signIn`.
+     *
+     * @see {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#sign-in | Sign in} for more information.
+     * @see {@link InteractionMode}
+     */
     signIn(redirectUri: string, interactionMode?: InteractionMode): Promise<void>;
+    /**
+     * Check if the user is redirected from the sign-in page by checking if the
+     * current URL matches the redirect URI in the sign-in session.
+     *
+     * If there's no sign-in session, it will return `false`.
+     *
+     * @param url The current URL.
+     */
     isSignInRedirected(url: string): Promise<boolean>;
+    /**
+     * Handle the sign-in callback by parsing the authorization code from the
+     * callback URI and exchanging it for the tokens.
+     *
+     * @param callbackUri The callback URI that the user is redirected to after the sign-in flow is completed.
+     * This URI must match the redirect URI specified in {@link signIn}.
+     * @throws LogtoClientError if the sign-in session is not found.
+     */
     handleSignInCallback(callbackUri: string): Promise<void>;
+    /**
+     * Start the sign-out flow with the specified redirect URI. The URI must be
+     * registered in the Logto Console.
+     *
+     * It will also revoke all the tokens and clean up the storage.
+     *
+     * The user will be redirected that URI after the sign-out flow is completed.
+     * If the `postLogoutRedirectUri` is not specified, the user will be redirected
+     * to a default page.
+     */
     signOut(postLogoutRedirectUri?: string): Promise<void>;
     protected getSignInSession(): Promise<Nullable<LogtoSignInSessionItem>>;
     protected setSignInSession(value: Nullable<LogtoSignInSessionItem>): Promise<void>;
@@ -43,7 +134,6 @@ export default class LogtoClient {
     private setRefreshToken;
     private getAccessTokenByRefreshToken;
     private verifyIdToken;
-    private saveCodeToken;
     private saveAccessTokenMap;
     private loadAccessTokenMap;
 }

package/lib/index.js

@@ -11,6 +11,13 @@ import { once } from './utils/once.js';
 import { PersistKey, CacheKey } from './adapter/types.js';
 export { createRequester } from './utils/requester.js';
 
+/**
+ * The Logto base client class that provides the essential methods for
+ * interacting with the Logto server.
+ *
+ * It also provides an adapter object that allows the customizations of the
+ * client behavior for different environments.
+ */
 class LogtoClient {
     constructor(logtoConfig, adapter) {
         this.getOidcConfig = memoize(this.#getOidcConfig);
@@ -24,15 +31,37 @@ class LogtoClient {
         this.adapter = new ClientAdapterInstance(adapter);
         void this.loadAccessTokenMap();
     }
+    /**
+     * Check if the user is authenticated by checking if the ID token exists.
+     */
     async isAuthenticated() {
         return Boolean(await this.getIdToken());
     }
+    /**
+     * Get the Refresh Token from the storage.
+     */
     async getRefreshToken() {
         return this.adapter.storage.getItem('refreshToken');
     }
+    /**
+     * Get the ID Token from the storage. If you want to get the ID Token claims,
+     * use {@link getIdTokenClaims} instead.
+     */
     async getIdToken() {
         return this.adapter.storage.getItem('idToken');
     }
+    /**
+     * Get the Access Token from the storage. If the Access Token has expired, it
+     * will try to fetch a new one using the Refresh Token.
+     *
+     * If you want to get the Access Token claims, use {@link getAccessTokenClaims} instead.
+     *
+     * @param resource The resource that the Access Token is granted for. If not
+     * specified, the Access Token will be used for OpenID Connect or the default
+     * resource, as specified in the Logto Console.
+     * @returns The Access Token string.
+     * @throws LogtoClientError if the user is not authenticated.
+     */
     async getAccessToken(resource) {
         if (!(await this.getIdToken())) {
             throw new LogtoClientError('not_authenticated');
@@ -51,6 +80,9 @@ class LogtoClient {
          */
         return this.getAccessTokenByRefreshToken(resource);
     }
+    /**
+     * Get the ID Token claims.
+     */
     async getIdTokenClaims() {
         const idToken = await this.getIdToken();
         if (!idToken) {
@@ -58,10 +90,27 @@ class LogtoClient {
         }
         return decodeIdToken(idToken);
     }
+    /**
+     * Get the Access Token claims for the specified resource.
+     *
+     * @param resource The resource that the Access Token is granted for. If not
+     * specified, the Access Token will be used for OpenID Connect or the default
+     * resource, as specified in the Logto Console.
+     */
     async getAccessTokenClaims(resource) {
         const accessToken = await this.getAccessToken(resource);
         return decodeAccessToken(accessToken);
     }
+    /**
+     * Get the user information from the Userinfo Endpoint.
+     *
+     * Note the Userinfo Endpoint will return more claims than the ID Token. See
+     * {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#fetch-user-information | Fetch user information}
+     * for more information.
+     *
+     * @returns The user information.
+     * @throws LogtoClientError if the user is not authenticated.
+     */
     async fetchUserInfo() {
         const { userinfoEndpoint } = await this.getOidcConfig();
         const accessToken = await this.getAccessToken();
@@ -70,6 +119,22 @@ class LogtoClient {
         }
         return fetchUserInfo(userinfoEndpoint, accessToken, this.adapter.requester);
     }
+    /**
+     * Start the sign-in flow with the specified redirect URI. The URI must be
+     * registered in the Logto Console.
+     *
+     * The user will be redirected to that URI after the sign-in flow is completed,
+     * and the client will be able to get the authorization code from the URI.
+     * To fetch the tokens from the authorization code, use {@link handleSignInCallback}
+     * after the user is redirected in the callback URI.
+     *
+     * @param redirectUri The redirect URI that the user will be redirected to after the sign-in flow is completed.
+     * @param interactionMode The interaction mode to be used for the authorization request. Note it's not
+     * a part of the OIDC standard, but a Logto-specific extension. Defaults to `signIn`.
+     *
+     * @see {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#sign-in | Sign in} for more information.
+     * @see {@link InteractionMode}
+     */
     async signIn(redirectUri, interactionMode) {
         const { appId: clientId, prompt, resources, scopes } = this.logtoConfig;
         const { authorizationEndpoint } = await this.getOidcConfig();
@@ -87,11 +152,21 @@ class LogtoClient {
             prompt,
             interactionMode,
         });
-        await this.setSignInSession({ redirectUri, codeVerifier, state });
-        await this.setRefreshToken(null);
-        await this.setIdToken(null);
-        this.adapter.navigate(signInUri);
+        await Promise.all([
+            this.setSignInSession({ redirectUri, codeVerifier, state }),
+            this.setRefreshToken(null),
+            this.setIdToken(null),
+        ]);
+        await this.adapter.navigate(signInUri);
     }
+    /**
+     * Check if the user is redirected from the sign-in page by checking if the
+     * current URL matches the redirect URI in the sign-in session.
+     *
+     * If there's no sign-in session, it will return `false`.
+     *
+     * @param url The current URL.
+     */
     async isSignInRedirected(url) {
         const signInSession = await this.getSignInSession();
         if (!signInSession) {
@@ -101,28 +176,59 @@ class LogtoClient {
         const { origin, pathname } = new URL(url);
         return `${origin}${pathname}` === redirectUri;
     }
+    /**
+     * Handle the sign-in callback by parsing the authorization code from the
+     * callback URI and exchanging it for the tokens.
+     *
+     * @param callbackUri The callback URI that the user is redirected to after the sign-in flow is completed.
+     * This URI must match the redirect URI specified in {@link signIn}.
+     * @throws LogtoClientError if the sign-in session is not found.
+     */
     async handleSignInCallback(callbackUri) {
-        const { logtoConfig, adapter } = this;
-        const { requester } = adapter;
+        const { requester } = this.adapter;
         const signInSession = await this.getSignInSession();
         if (!signInSession) {
             throw new LogtoClientError('sign_in_session.not_found');
         }
         const { redirectUri, state, codeVerifier } = signInSession;
         const code = verifyAndParseCodeFromCallbackUri(callbackUri, redirectUri, state);
-        const { appId: clientId } = logtoConfig;
+        // NOTE: Will add scope to accessTokenKey when needed. (Linear issue LOG-1589)
+        const accessTokenKey = buildAccessTokenKey();
+        const { appId: clientId } = this.logtoConfig;
         const { tokenEndpoint } = await this.getOidcConfig();
-        const codeTokenResponse = await fetchTokenByAuthorizationCode({
+        const requestedAt = Math.round(Date.now() / 1000);
+        const { idToken, refreshToken, accessToken, scope, expiresIn } = await fetchTokenByAuthorizationCode({
             clientId,
             tokenEndpoint,
             redirectUri,
             codeVerifier,
             code,
         }, requester);
-        await this.verifyIdToken(codeTokenResponse.idToken);
-        await this.saveCodeToken(codeTokenResponse);
+        await this.verifyIdToken(idToken);
+        await this.setRefreshToken(refreshToken ?? null);
+        await this.setIdToken(idToken);
+        this.accessTokenMap.set(accessTokenKey, {
+            token: accessToken,
+            scope,
+            /** The `expiresAt` variable provides an approximate estimation of the actual `exp` property
+             * in the token claims. It is utilized by the client to determine if the cached access token
+             * has expired and when a new access token should be requested.
+             */
+            expiresAt: requestedAt + expiresIn,
+        });
+        await this.saveAccessTokenMap();
         await this.setSignInSession(null);
     }
+    /**
+     * Start the sign-out flow with the specified redirect URI. The URI must be
+     * registered in the Logto Console.
+     *
+     * It will also revoke all the tokens and clean up the storage.
+     *
+     * The user will be redirected that URI after the sign-out flow is completed.
+     * If the `postLogoutRedirectUri` is not specified, the user will be redirected
+     * to a default page.
+     */
     async signOut(postLogoutRedirectUri) {
         const { appId: clientId } = this.logtoConfig;
         const { endSessionEndpoint, revocationEndpoint } = await this.getOidcConfig();
@@ -141,10 +247,12 @@ class LogtoClient {
             clientId,
         });
         this.accessTokenMap.clear();
-        await this.setRefreshToken(null);
-        await this.setIdToken(null);
-        await this.adapter.storage.removeItem('accessToken');
-        this.adapter.navigate(url);
+        await Promise.all([
+            this.setRefreshToken(null),
+            this.setIdToken(null),
+            this.adapter.storage.removeItem('accessToken'),
+        ]);
+        await this.adapter.navigate(url);
     }
     async getSignInSession() {
         const jsonItem = await this.adapter.storage.getItem('signInSession');
@@ -174,6 +282,7 @@ class LogtoClient {
         const accessTokenKey = buildAccessTokenKey(resource);
         const { appId: clientId } = this.logtoConfig;
         const { tokenEndpoint } = await this.getOidcConfig();
+        const requestedAt = Math.round(Date.now() / 1000);
         const { accessToken, refreshToken, idToken, scope, expiresIn } = await fetchTokenByRefreshToken({
             clientId,
             tokenEndpoint,
@@ -183,7 +292,11 @@ class LogtoClient {
         this.accessTokenMap.set(accessTokenKey, {
             token: accessToken,
             scope,
-            expiresAt: Math.round(Date.now() / 1000) + expiresIn,
+            /** The `expiresAt` variable provides an approximate estimation of the actual `exp` property
+             * in the token claims. It is utilized by the client to determine if the cached access token
+             * has expired and when a new access token should be requested.
+             */
+            expiresAt: requestedAt + expiresIn,
         });
         await this.saveAccessTokenMap();
         await this.setRefreshToken(refreshToken);
@@ -199,15 +312,6 @@ class LogtoClient {
         const jwtVerifyGetKey = await this.getJwtVerifyGetKey();
         await verifyIdToken(idToken, appId, issuer, jwtVerifyGetKey);
     }
-    async saveCodeToken({ refreshToken, idToken, scope, accessToken, expiresIn, }) {
-        await this.setRefreshToken(refreshToken ?? null);
-        await this.setIdToken(idToken);
-        // NOTE: Will add scope to accessTokenKey when needed. (Linear issue LOG-1589)
-        const accessTokenKey = buildAccessTokenKey();
-        const expiresAt = Date.now() / 1000 + expiresIn;
-        this.accessTokenMap.set(accessTokenKey, { token: accessToken, scope, expiresAt });
-        await this.saveAccessTokenMap();
-    }
     async saveAccessTokenMap() {
         const data = {};
         for (const [key, accessToken] of this.accessTokenMap.entries()) {

package/lib/types/index.d.ts

@@ -1,15 +1,51 @@
 import type { Prompt } from '@logto/js';
+/** The configuration object for the Logto client. */
 export type LogtoConfig = {
+    /**
+     * The endpoint for the Logto server, you can get it from the integration guide
+     * or the team settings page of the Logto Console.
+     *
+     * @example https://foo.logto.app
+     */
     endpoint: string;
+    /**
+     * The client ID of your application, you can get it from the integration guide
+     * or the application details page of the Logto Console.
+     */
     appId: string;
+    /**
+     * The client secret of your application, you can get it from the application
+     * details page of the Logto Console.
+     */
     appSecret?: string;
+    /**
+     * The scopes (permissions) that your application needs to access.
+     * Scopes that will be added by default: `openid`, `offline_access` and `profile`.
+     *
+     * If resources are specified, scopes will be applied to every resource.
+     *
+     * @see {@link https://docs.logto.io/docs/recipes/integrate-logto/vanilla-js/#fetch-user-information | Fetch user information}
+     * for more information of available scopes for user information.
+     */
     scopes?: string[];
+    /**
+     * The API resources that your application needs to access. You can specify
+     * multiple resources by providing an array of strings.
+     *
+     * @see {@link https://docs.logto.io/docs/recipes/rbac/ | RBAC} to learn more about how to use role-based access control (RBAC) to protect API resources.
+     */
     resources?: string[];
+    /**
+     * The prompt parameter to be used for the authorization request.
+     */
     prompt?: Prompt;
 };
 export type AccessToken = {
+    /** The access token string. */
     token: string;
+    /** The scopes that the access token is granted for. */
     scope: string;
+    /** The timestamp of the access token expiration. */
     expiresAt: number;
 };
 export declare const isLogtoSignInSessionItem: (data: unknown) => data is LogtoSignInSessionItem;

package/lib/utils/requester.cjs

@@ -2,6 +2,13 @@
 
 var js = require('@logto/js');
 
+/**
+ * A factory function that creates a requester by accepting a `fetch`-like function.
+ *
+ * @param fetchFunction A `fetch`-like function.
+ * @returns A requester function.
+ * @see {@link Requester}
+ */
 const createRequester = (fetchFunction) => {
     return async (...args) => {
         const response = await fetchFunction(...args);

package/lib/utils/requester.d.ts

@@ -1,2 +1,9 @@
 import type { Requester } from '@logto/js';
+/**
+ * A factory function that creates a requester by accepting a `fetch`-like function.
+ *
+ * @param fetchFunction A `fetch`-like function.
+ * @returns A requester function.
+ * @see {@link Requester}
+ */
 export declare const createRequester: (fetchFunction: typeof fetch) => Requester;

package/lib/utils/requester.js

@@ -1,5 +1,12 @@
 import { isLogtoRequestError, LogtoError, LogtoRequestError } from '@logto/js';
 
+/**
+ * A factory function that creates a requester by accepting a `fetch`-like function.
+ *
+ * @param fetchFunction A `fetch`-like function.
+ * @returns A requester function.
+ * @see {@link Requester}
+ */
 const createRequester = (fetchFunction) => {
     return async (...args) => {
         const response = await fetchFunction(...args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/client",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "type": "module",
   "main": "./lib/index.cjs",
   "module": "./lib/index.js",
@@ -21,24 +21,24 @@
     "directory": "packages/client"
   },
   "dependencies": {
-    "@logto/js": "^2.1.0",
+    "@logto/js": "^2.1.2",
     "@silverhand/essentials": "^2.6.2",
     "camelcase-keys": "^7.0.1",
     "jose": "^4.13.2"
   },
   "devDependencies": {
-    "@silverhand/eslint-config": "^3.0.1",
-    "@silverhand/ts-config": "^3.0.0",
+    "@silverhand/eslint-config": "^4.0.1",
+    "@silverhand/ts-config": "^4.0.0",
     "@swc/core": "^1.3.50",
     "@swc/jest": "^0.2.24",
     "@types/jest": "^29.5.0",
     "@types/node": "^18.0.0",
-    "eslint": "^8.38.0",
+    "eslint": "^8.44.0",
     "jest": "^29.5.0",
     "jest-matcher-specific-error": "^1.0.0",
     "lint-staged": "^13.0.0",
     "nock": "^13.3.0",
-    "prettier": "^2.8.7",
+    "prettier": "^3.0.0",
     "text-encoder": "^0.0.4",
     "type-fest": "^3.0.0",
     "typescript": "^5.0.0"