@scalekit-sdk/node 2.1.6 → 2.1.8

package/src/scalekit.ts

@@ -14,6 +14,7 @@ import UserClient from './user';
 import SessionClient from './session';
 import RoleClient from './role';
 import PermissionClient from './permission';
+import WebAuthnClient from './webauthn';
 import { IdpInitiatedLoginClaims, IdTokenClaim, User } from './types/auth';
 import { AuthenticationOptions, AuthenticationResponse, AuthorizationUrlOptions, GrantType, LogoutUrlOptions, RefreshTokenResponse ,TokenValidationOptions } from './types/scalekit';
 import { WebhookVerificationError, ScalekitValidateTokenFailureException } from './errors/base-exception';
@@ -24,14 +25,35 @@ const WEBHOOK_TOLERANCE_IN_SECONDS = 5 * 60; // 5 minutes
 const WEBHOOK_SIGNATURE_VERSION = "v1";
 
 /**
- * To initiate scalekit
- * @param {string} envUrl The environment url
- * @param {string} clientId The client id
- * @param {string} clientSecret The client secret
- * @returns {ScalekitClient} Returns the scalekit instance 
+ * Main Scalekit SDK client for interacting with all Scalekit API endpoints.
+ *
+ * TIP: You can use it as a singleton object - that is you can initialize it just once and use the same client variable wherever required.
+ *
+ * This is the primary entry point for interacting with Scalekit's authentication services,
+ * including SSO, SCIM, user management, roles, permissions, and passwordless authentication.
+ *
+ * You can find the Environment URL, Client ID and Client Secret in Scalekit Dashboard -> Developers (Settings) -> API Credentials
+ *
+ * @param {string} envUrl - The Scalekit environment URL (e.g., "https://yourorg.scalekit.com" or your configured custom domain like "https://auth.yourapp.ai")
+ * @param {string} clientId - Your Scalekit client ID from the Scalekit Dashboard
+ * @param {string} clientSecret - Your Scalekit client secret from the Scalekit Dashboard
+ *
  * @example
- * const scalekit = new Scalekit(envUrl, clientId, clientSecret);
-*/
+ * // Initialize the Scalekit client
+ * import { ScalekitClient } from '@scalekit-sdk/node';
+ *
+ * const scalekitClient = new ScalekitClient(
+ *   process.env.SCALEKIT_ENV_URL,
+ *   process.env.SCALEKIT_CLIENT_ID,
+ *   process.env.SCALEKIT_CLIENT_SECRET
+ * );
+ *
+ * // Access various client modules
+ * const organizations = await scalekitClient.organization.listOrganization();
+ * const users = await scalekitClient.user.listUsers();
+ *
+ * @see {@link https://docs.scalekit.com/apis/ | Scalekit API Documentation}
+ */
 export default class ScalekitClient {
   private readonly coreClient: CoreClient;
   private readonly grpcConnect: GrpcConnect;
@@ -45,6 +67,7 @@ export default class ScalekitClient {
   readonly role: RoleClient;
   readonly permission: PermissionClient;
   readonly auth: AuthClient;
+  readonly webauthn: WebAuthnClient;
   constructor(
     envUrl: string,
     clientId: string,
@@ -63,18 +86,9 @@ export default class ScalekitClient {
       this.grpcConnect,
       this.coreClient
     );
-    this.connection = new ConnectionClient(
-      this.grpcConnect,
-      this.coreClient
-    );
-    this.domain = new DomainClient(
-      this.grpcConnect,
-      this.coreClient
-    );
-    this.directory = new DirectoryClient(
-      this.grpcConnect,
-      this.coreClient
-    );
+    this.connection = new ConnectionClient(this.grpcConnect, this.coreClient);
+    this.domain = new DomainClient(this.grpcConnect, this.coreClient);
+    this.directory = new DirectoryClient(this.grpcConnect, this.coreClient);
     this.passwordless = new PasswordlessClient(
       this.grpcConnect,
       this.coreClient
@@ -99,45 +113,94 @@ export default class ScalekitClient {
       this.grpcConnect,
       this.coreClient
     );
+    this.webauthn = new WebAuthnClient(
+      this.grpcConnect,
+      this.coreClient
+    );
   }
 
   /**
-   * Returns the authorization url to initiate the authentication request.
-   * @param {string} redirectUri Redirect uri
-   * @param {AuthorizationUrlOptions} options Authorization url options
-   * @param {string[]} options.scopes Scopes to request from the user 
-   * @param {string} options.state State parameter
-   * @param {string} options.nonce Nonce parameter 
-   * @param {string} options.loginHint Login hint parameter
-   * @param {string} options.domainHint Domain hint parameter
-   * @param {string} options.connectionId Connection id parameter
-   * @param {string} options.organizationId Organization id parameter
-   * @param {string} options.provider Provider i.e. google, github, etc.
-   * @param {string} options.codeChallenge Code challenge parameter in case of PKCE
-   * @param {string} options.codeChallengeMethod Code challenge method parameter in case of PKCE
-   * @param {string} options.prompt Prompt parameter to control the authorization server's authentication behavior
-   * 
+   * Utility method to generate the OAuth 2.0 authorization URL to initiate the SSO authentication flow.
+   *
+   * This method doesn't make any network calls but instead generates a fully formed Authorization URL
+   * as a string that you can redirect your users to initiate authentication.
+   *
+   * @param {string} redirectUri - The URL where users will be redirected after authentication.
+   *                               Must match one of the redirect URIs configured in your Scalekit dashboard.
+   * @param {AuthorizationUrlOptions} [options] - Optional configuration for the authorization request
+   * @param {string[]} [options.scopes=['openid', 'profile', 'email']] - OAuth scopes to request. Default includes openid, profile, and email.
+   * @param {string} [options.state] - Opaque value to maintain state between request and callback. Used to prevent CSRF attacks.
+   * @param {string} [options.nonce] - String value used to associate a client session with an ID Token.
+   * @param {string} [options.loginHint] - Hint to the authorization server about the login identifier the user might use (e.g., email address).
+   * @param {string} [options.domainHint] - Domain hint to identify which organization's IdP to use for authentication.
+   * @param {string} [options.connectionId] - Specific SSO connection ID to use for authentication.
+   * @param {string} [options.organizationId] - Organization ID to authenticate against.
+   * @param {string} [options.provider] - Social login provider (e.g., 'google', 'github', 'microsoft').
+   * @param {string} [options.codeChallenge] - PKCE code challenge for enhanced security in public clients.
+   * @param {string} [options.codeChallengeMethod] - Method used to generate the code challenge (we support only 'S256').
+   * @param {string} [options.prompt] - Controls the authorization server's authentication behavior (e.g., 'login', 'consent', 'create').
+   *
+   * @returns {string} The complete authorization URL to redirect the user to
+   *
    * @example
-   * const scalekit = new Scalekit(envUrl, clientId, clientSecret);
-   * const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, { 
-   *   scopes: ['openid', 'profile'],
-   *   prompt: 'create'
-   * });
-   * @returns {string} authorization url
+   * // Initiate Enterprise SSO authentication for a given org_id
+   * const authUrl = scalekitClient.getAuthorizationUrl(
+   *   'https://yourapp.com/auth/callback',
+   *   {
+   *     state: 'random-state-value',
+   *     organizationId: 'org_123456'
+   *   }
+   * );
+   * // Redirect user to authUrl
+   *
+   * @example
+   * // Initiate Enterprise SSO authentication for a specific connection id
+   * // optionally, pass the loginhint to the 3rd party identity provider.
+   * const authUrl = scalekitClient.getAuthorizationUrl(
+   *   'https://yourapp.com/auth/callback',
+   *   {
+   *     connectionId: 'conn_abc123',
+   *     loginHint: 'user@company.com'
+   *   }
+   * );
+   *
+   * @example
+   * // Social login
+   * const authUrl = scalekitClient.getAuthorizationUrl(
+   *   'https://yourapp.com/auth/callback',
+   *   {
+   *     provider: 'google',
+   *     state: 'random-state'
+   *   }
+   * );
+   *
+   * @example
+   * // PKCE flow for public clients
+   * const authUrl = scalekitClient.getAuthorizationUrl(
+   *   'https://yourapp.com/auth/callback',
+   *   {
+   *     codeChallenge: 'your-code-challenge',
+   *     codeChallengeMethod: 'S256',
+   *     organizationId: 'org_123456'
+   *   }
+   * );
+   *
+   * @see {@link https://docs.scalekit.com/apis/#tag/api%20auth | Authentication API Documentation}
+   * @see {@link authenticateWithCode} - Use this method to exchange the authorization code for tokens
    */
   getAuthorizationUrl(
     redirectUri: string,
     options?: AuthorizationUrlOptions
   ): string {
     const defaultOptions: AuthorizationUrlOptions = {
-      scopes: ['openid', 'profile', 'email']
-    }
+      scopes: ["openid", "profile", "email"],
+    };
     options = {
       ...defaultOptions,
-      ...options
-    }
+      ...options,
+    };
     const qs = QueryString.stringify({
-      response_type: 'code',
+      response_type: "code",
       client_id: this.coreClient.clientId,
       redirect_uri: redirectUri,
       scope: options.scopes?.join(" "),
@@ -147,38 +210,99 @@ export default class ScalekitClient {
       ...(options.domainHint && { domain_hint: options.domainHint }),
       ...(options.domainHint && { domain: options.domainHint }),
       ...(options.connectionId && { connection_id: options.connectionId }),
-      ...(options.organizationId && { organization_id: options.organizationId }),
+      ...(options.organizationId && {
+        organization_id: options.organizationId,
+      }),
       ...(options.codeChallenge && { code_challenge: options.codeChallenge }),
-      ...(options.codeChallengeMethod && { code_challenge_method: options.codeChallengeMethod }),
+      ...(options.codeChallengeMethod && {
+        code_challenge_method: options.codeChallengeMethod,
+      }),
       ...(options.provider && { provider: options.provider }),
-      ...(options.prompt && { prompt: options.prompt })
-    })
+      ...(options.prompt && { prompt: options.prompt }),
+    });
 
-    return `${this.coreClient.envUrl}/${authorizeEndpoint}?${qs}`
+    return `${this.coreClient.envUrl}/${authorizeEndpoint}?${qs}`;
   }
 
   /**
-   * Authenticate with the code
-   * @param {string} code Code
-   * @param {string} redirectUri Redirect uri
-   * @param {AuthenticationOptions} options Code authentication options
-   * @param {string} options.codeVerifier Code verifier in case of PKCE
-   * @returns {Promise<AuthenticationResponse>} Returns user, id token and access token
+   * Exchanges an authorization code for access tokens and user information.
+   *
+   * This method completes the OAuth 2.0 authorization code flow by exchanging the code
+   * received in the callback for access tokens, ID tokens, and user profile information.
+   * Call this method in your redirect URI handler after receiving the authorization code.
+   *
+   * @param {string} code - The authorization code received in the callback URL after user authentication
+   * @param {string} redirectUri - The same redirect URI used in getAuthorizationUrl(). Must match exactly.
+   * @param {AuthenticationOptions} [options] - Optional authentication configuration
+   * @param {string} [options.codeVerifier] - PKCE code verifier to validate the code challenge (required if PKCE was used)
+   *
+   * @returns {Promise<AuthenticationResponse>} Authentication response containing:
+   *   - user: User profile information (email, name, organization, etc.)
+   *   - idToken: JWT ID token containing user claims
+   *   - accessToken: Access token for API authorization
+   *   - expiresIn: Token expiration time in seconds
+   *   - refreshToken: Refresh token for obtaining new access tokens
+   *
+   * @throws {Error} When the authorization code is invalid, expired, or already used
+   * @throws {Error} When the redirect URI doesn't match the one used in authorization
+   * @throws {Error} When PKCE code verifier is invalid or missing
+   *
+   * @example
+   * // Basic code exchange (server-side flow)
+   * app.get('/auth/callback', async (req, res) => {
+   *   const { code } = req.query;
+   *
+   *   try {
+   *     const result = await scalekitClient.authenticateWithCode(
+   *       code,
+   *       'https://yourapp.com/auth/callback'
+   *     );
+   *
+   *     // Store tokens securely
+   *     req.session.accessToken = result.accessToken;
+   *     req.session.user = result.user;
+   *
+   *     res.redirect('/dashboard');
+   *   } catch (error) {
+   *     console.error('Authentication failed:', error);
+   *     res.redirect('/login?error=auth_failed');
+   *   }
+   * });
+   *
+   * @example
+   * // PKCE flow (for public clients)
+   * app.get('/auth/callback', async (req, res) => {
+   *   const { code } = req.query;
+   *   const codeVerifier = req.session.codeVerifier; // Stored during authorization
+   *
+   *   const result = await scalekitClient.authenticateWithCode(
+   *     code,
+   *     'https://yourapp.com/auth/callback',
+   *     { codeVerifier }
+   *   );
+   *
+   *   // Use result.user, result.accessToken, etc.
+   * });
+   *
+   * @see {@link getAuthorizationUrl} - Generate the authorization URL first
+   * @see {@link validateAccessToken} - Validate tokens in subsequent requests
    */
   async authenticateWithCode(
     code: string,
     redirectUri: string,
-    options?: AuthenticationOptions,
+    options?: AuthenticationOptions
   ): Promise<AuthenticationResponse> {
-    const res = await this.coreClient.authenticate(QueryString.stringify({
-      code: code,
-      redirect_uri: redirectUri,
-      grant_type: GrantType.AuthorizationCode,
-      client_id: this.coreClient.clientId,
-      client_secret: this.coreClient.clientSecret,
-      ...(options?.codeVerifier && { code_verifier: options.codeVerifier })
-    }))
-    const { id_token, access_token, expires_in , refresh_token } = res.data;
+    const res = await this.coreClient.authenticate(
+      QueryString.stringify({
+        code: code,
+        redirect_uri: redirectUri,
+        grant_type: GrantType.AuthorizationCode,
+        client_id: this.coreClient.clientId,
+        client_secret: this.coreClient.clientSecret,
+        ...(options?.codeVerifier && { code_verifier: options.codeVerifier }),
+      })
+    );
+    const { id_token, access_token, expires_in, refresh_token } = res.data;
     const claims = jose.decodeJwt<IdTokenClaim>(id_token);
     const user = <User>{};
     for (const [k, v] of Object.entries(claims)) {
@@ -192,29 +316,83 @@ export default class ScalekitClient {
       idToken: id_token,
       accessToken: access_token,
       expiresIn: expires_in,
-      refreshToken: refresh_token
-    }
+      refreshToken: refresh_token,
+    };
   }
 
   /**
-  * Get the idp initiated login claims
-  * 
-  * @param {string} idpInitiatedLoginToken The idp_initiated_login query param from the URL
-  * @param {TokenValidationOptions} options Optional validation options for issuer and audience
-  * @returns {object} Returns the idp initiated login claims
-  */
-  async getIdpInitiatedLoginClaims(idpInitiatedLoginToken: string, options?: TokenValidationOptions): Promise<IdpInitiatedLoginClaims> {
-    return this.validateToken<IdpInitiatedLoginClaims>(idpInitiatedLoginToken, options);
+   * Extracts and validates claims from an IdP-initiated login token.
+   *
+   * Use this method when handling IdP-initiated SSO flows, where the authentication is
+   * initiated from the identity provider's portal rather than your application. This validates
+   * the token and returns the necessary information to initiate a new SP Initiated SSO workflow.
+   *
+   * @param {string} idpInitiatedLoginToken - The token received in the 'idp_initiated_login' query parameter
+   * @param {TokenValidationOptions} [options] - Optional token validation configuration
+   * @param {string} [options.issuer] - Expected token issuer for validation
+   * @param {string} [options.audience] - Expected token audience for validation
+   *
+   * @returns {Promise<IdpInitiatedLoginClaims>} Claims containing:
+   *   - connection_id: The SSO connection identifier
+   *   - organization_id: The organization identifier
+   *   - login_hint: User's email or login identifier
+   *   - relay_state: Optional state parameter from the IdP
+   *
+   * @throws {ScalekitValidateTokenFailureException} When token validation fails
+   *
+   * @example
+   * // Handle IdP-initiated login
+   * app.get('/auth/callback', async (req, res) => {
+   *   const { idp_initiated_login } = req.query;
+   *
+   *   if (idp_initiated_login) {
+   *     try {
+   *       const claims = await scalekitClient.getIdpInitiatedLoginClaims(idp_initiated_login);
+   *
+   *       // Redirect to authorization URL with the claims
+   *       const authUrl = scalekitClient.getAuthorizationUrl(
+   *         'https://yourapp.com/auth/callback',
+   *         {
+   *           connectionId: claims.connection_id,
+   *           organizationId: claims.organization_id,
+   *           loginHint: claims.login_hint,
+   *           ...(claims.relay_state && { state: claims.relay_state })
+   *         }
+   *       );
+   *
+   *       return res.redirect(authUrl);
+   *     } catch (error) {
+   *       console.error('IdP-initiated login failed:', error);
+   *       return res.redirect('/login?error=idp_login_failed');
+   *     }
+   *   }
+   *   // Handle normal callback flow...
+   * });
+   *
+   * @see {@link https://docs.scalekit.com/sso/guides/idp-init-sso/ | IdP-Initiated SSO Documentation}
+   * @see {@link getAuthorizationUrl} - Use the claims to construct the authorization URL
+   */
+  async getIdpInitiatedLoginClaims(
+    idpInitiatedLoginToken: string,
+    options?: TokenValidationOptions
+  ): Promise<IdpInitiatedLoginClaims> {
+    return this.validateToken<IdpInitiatedLoginClaims>(
+      idpInitiatedLoginToken,
+      options
+    );
   }
 
   /**
    * Validates the access token and returns a boolean result.
-   * 
+   *
    * @param {string} token The token to be validated.
    * @param {TokenValidationOptions} options Optional validation options for issuer, audience, and scopes
    * @return {Promise<boolean>} Returns true if the token is valid, false otherwise.
    */
-  async validateAccessToken(token: string, options?: TokenValidationOptions): Promise<boolean> {
+  async validateAccessToken(
+    token: string,
+    options?: TokenValidationOptions
+  ): Promise<boolean> {
     try {
       await this.validateToken(token, options);
       return true;
@@ -223,8 +401,6 @@ export default class ScalekitClient {
     }
   }
 
-
-
   /**
    * Returns the logout URL that can be used to log out the user.
    * @param {LogoutUrlOptions} options Logout URL options
@@ -232,7 +408,7 @@ export default class ScalekitClient {
    * @param {string} options.postLogoutRedirectUri URL to redirect after logout
    * @param {string} options.state Opaque value to maintain state between request and callback
    * @returns {string} The logout URL
-   * 
+   *
    * @example
    * const scalekit = new Scalekit(envUrl, clientId, clientSecret);
    * const logoutUrl = scalekit.getLogoutUrl({
@@ -243,48 +419,118 @@ export default class ScalekitClient {
   getLogoutUrl(options?: LogoutUrlOptions): string {
     const qs = QueryString.stringify({
       ...(options?.idTokenHint && { id_token_hint: options.idTokenHint }),
-      ...(options?.postLogoutRedirectUri && { post_logout_redirect_uri: options.postLogoutRedirectUri }),
-      ...(options?.state && { state: options.state })
+      ...(options?.postLogoutRedirectUri && {
+        post_logout_redirect_uri: options.postLogoutRedirectUri,
+      }),
+      ...(options?.state && { state: options.state }),
     });
 
-    return `${this.coreClient.envUrl}/${logoutEndpoint}${qs ? `?${qs}` : ''}`;
+    return `${this.coreClient.envUrl}/${logoutEndpoint}${qs ? `?${qs}` : ""}`;
   }
 
   /**
-   * Verify webhook payload
-   * 
-   * @param {string} secret The secret
-   * @param {Record<string, string>} headers The headers
-   * @param {string} payload The payload
-   * @return {boolean} Returns true if the payload is valid.
+   * Verifies the authenticity and integrity of webhook payloads from Scalekit.
+   *
+   * Use this method to validate webhook requests from Scalekit by verifying the HMAC signature.
+   * This ensures the webhook was sent by Scalekit and hasn't been tampered with. The method
+   * checks the signature and timestamp to prevent replay attacks (5-minute tolerance window).
+   *
+   * @param {string} secret - Your webhook signing secret from the Scalekit dashboard (format: 'whsec_...')
+   * @param {Record<string, string>} headers - The HTTP headers from the webhook request
+   * @param {string} payload - The raw webhook request body as a string
+   *
+   * @returns {boolean} Returns true if the webhook signature is valid
+   *
+   * @throws {WebhookVerificationError} When required headers are missing
+   * @throws {WebhookVerificationError} When the secret format is invalid
+   * @throws {WebhookVerificationError} When the signature doesn't match
+   * @throws {WebhookVerificationError} When the timestamp is too old (>5 minutes) or in the future
+   *
+   * @example
+   * // Express.js webhook handler
+   * app.post('/webhooks/scalekit', express.raw({ type: 'application/json' }), (req, res) => {
+   *   const secret = process.env.SCALEKIT_WEBHOOK_SECRET;
+   *   const headers = req.headers;
+   *   const payload = req.body.toString();
+   *
+   *   try {
+   *     const isValid = scalekitClient.verifyWebhookPayload(secret, headers, payload);
+   *
+   *     if (isValid) {
+   *       const event = JSON.parse(payload);
+   *
+   *       // Process the webhook event
+   *       switch (event.type) {
+   *         case 'user.created':
+   *           console.log('New user created:', event.data);
+   *           break;
+   *         case 'connection.enabled':
+   *           console.log('Connection enabled:', event.data);
+   *           break;
+   *       }
+   *
+   *       res.status(200).send('Webhook received');
+   *     }
+   *   } catch (error) {
+   *     console.error('Webhook verification failed:', error);
+   *     res.status(400).send('Invalid webhook signature');
+   *   }
+   * });
+   *
+   * @see {@link https://docs.scalekit.com/reference/webhooks/overview/ | Webhook Documentation}
+   * @see {@link verifyInterceptorPayload} - Similar method for interceptor payloads
    */
-  verifyWebhookPayload(secret: string, headers: Record<string, string>, payload: string): boolean {
-    const webhookId = headers['webhook-id'];
-    const webhookTimestamp = headers['webhook-timestamp'];
-    const webhookSignature = headers['webhook-signature'];
-    
-    return this.verifyPayloadSignature(secret, webhookId, webhookTimestamp, webhookSignature, payload);
+  verifyWebhookPayload(
+    secret: string,
+    headers: Record<string, string>,
+    payload: string
+  ): boolean {
+    const webhookId = headers["webhook-id"];
+    const webhookTimestamp = headers["webhook-timestamp"];
+    const webhookSignature = headers["webhook-signature"];
+
+    return this.verifyPayloadSignature(
+      secret,
+      webhookId,
+      webhookTimestamp,
+      webhookSignature,
+      payload
+    );
   }
 
   /**
-   * Verify interceptor payload
-   * 
-   * @param {string} secret The secret
-   * @param {Record<string, string>} headers The headers
-   * @param {string} payload The payload
-   * @return {boolean} Returns true if the payload is valid.
+   * Verifies the authenticity and integrity of interceptor payloads from Scalekit.
+   *
+   * Use this method to validate HTTP interceptor requests from Scalekit by verifying the HMAC signature.
+   * This ensures the interceptor payload was sent by Scalekit and hasn't been tampered with. The method
+   * checks the signature and timestamp to prevent replay attacks (5-minute tolerance window)
+   *
+   * @param {string} secret Your interceptor signing secret that you can copy from Scalekit Dashboard
+   * @param {Record<string, string>} headers The HTTP headers from the interceptor request
+   * @param {string} payload The raw interceptor request body as a string
+   * @return {boolean} Returns true if the interceptor payload is valid.
    */
-  verifyInterceptorPayload(secret: string, headers: Record<string, string>, payload: string): boolean {
-    const interceptorId = headers['interceptor-id'];
-    const interceptorTimestamp = headers['interceptor-timestamp'];
-    const interceptorSignature = headers['interceptor-signature'];
-    
-    return this.verifyPayloadSignature(secret, interceptorId, interceptorTimestamp, interceptorSignature, payload);
+  verifyInterceptorPayload(
+    secret: string,
+    headers: Record<string, string>,
+    payload: string
+  ): boolean {
+    const interceptorId = headers["interceptor-id"];
+    const interceptorTimestamp = headers["interceptor-timestamp"];
+    const interceptorSignature = headers["interceptor-signature"];
+
+    return this.verifyPayloadSignature(
+      secret,
+      interceptorId,
+      interceptorTimestamp,
+      interceptorSignature,
+      payload
+    );
   }
 
   /**
    * Common payload signature verification logic
-   * 
+   *
    * @param {string} secret The secret
    * @param {string} id The webhook/interceptor id
    * @param {string} timestamp The timestamp
@@ -292,62 +538,78 @@ export default class ScalekitClient {
    * @param {string} payload The payload
    * @return {boolean} Returns true if the payload signature is valid.
    */
-  private verifyPayloadSignature(secret: string, id: string, timestamp: string, signature: string, payload: string): boolean {
+  private verifyPayloadSignature(
+    secret: string,
+    id: string,
+    timestamp: string,
+    signature: string,
+    payload: string
+  ): boolean {
     if (!id || !timestamp || !signature) {
       throw new WebhookVerificationError("Missing required headers");
     }
-    
+
     const secretParts = secret.split("_");
     if (secretParts.length < 2) {
       throw new WebhookVerificationError("Invalid secret");
     }
-    
+
     try {
       const timestampDate = this.verifyTimestamp(timestamp);
-      const data = `${id}.${Math.floor(timestampDate.getTime() / 1000)}.${payload}`;
-      const secretBytes = Buffer.from(secretParts[1], 'base64');
+      const data = `${id}.${Math.floor(
+        timestampDate.getTime() / 1000
+      )}.${payload}`;
+      const secretBytes = Buffer.from(secretParts[1], "base64");
       const computedSignature = this.computeSignature(secretBytes, data);
       const receivedSignatures = signature.split(" ");
-      
+
       for (const versionedSignature of receivedSignatures) {
         const [version, receivedSignature] = versionedSignature.split(",");
         if (version !== WEBHOOK_SIGNATURE_VERSION) {
           continue;
         }
-        if (crypto.timingSafeEqual(Buffer.from(receivedSignature, 'base64'), Buffer.from(computedSignature, 'base64'))) {
+        if (
+          crypto.timingSafeEqual(
+            Buffer.from(receivedSignature, "base64"),
+            Buffer.from(computedSignature, "base64")
+          )
+        ) {
           return true;
         }
       }
 
-      throw new WebhookVerificationError("Invalid signature");
+      throw new WebhookVerificationError("Invalid Signature");
     } catch (error) {
       if (error instanceof WebhookVerificationError) {
         throw error;
       }
-      throw new WebhookVerificationError("Invalid signature");
+      throw new WebhookVerificationError("Invalid Signature");
     }
   }
 
   /**
-   * Validates a token and returns its payload if valid.
+   * Validates a token and returns the claims as json payload if valid.
    * Supports issuer, audience, and scope validation.
-   * 
+   *
    * @param {string} token The token to be validated
    * @param {TokenValidationOptions} options Optional validation options for issuer, audience, and scopes
    * @return {Promise<T>} Returns the token payload if valid
    * @throws {ScalekitValidateTokenFailureException} If token is invalid or missing required scopes
    */
-  async validateToken<T>(token: string, options?: TokenValidationOptions): Promise<T> {
+  async validateToken<T>(
+    token: string,
+    options?: TokenValidationOptions
+  ): Promise<T> {
     await this.coreClient.getJwks();
     const jwks = jose.createLocalJWKSet({
-      keys: this.coreClient.keys
-    })
+      keys: this.coreClient.keys,
+    });
     try {
       const { payload } = await jose.jwtVerify<T>(token, jwks, {
         ...(options?.issuer && { issuer: options.issuer }),
-        ...(options?.audience && { audience: options.audience })
+        ...(options?.audience && { audience: options.audience }),
       });
-      
+
       if (options?.requiredScopes && options.requiredScopes.length > 0) {
         this.verifyScopes(token, options.requiredScopes);
       }
@@ -360,7 +622,7 @@ export default class ScalekitClient {
 
   /**
    * Verify that the token contains the required scopes
-   * 
+   *
    * @param {string} token The token to verify
    * @param {string[]} requiredScopes The scopes that must be present in the token
    * @return {boolean} Returns true if all required scopes are present
@@ -369,19 +631,23 @@ export default class ScalekitClient {
   verifyScopes(token: string, requiredScopes: string[]): boolean {
     const payload = jose.decodeJwt(token);
     const scopes = this.extractScopesFromPayload(payload);
-    
-    const missingScopes = requiredScopes.filter(scope => !scopes.includes(scope));
-    
+
+    const missingScopes = requiredScopes.filter(
+      (scope) => !scopes.includes(scope)
+    );
+
     if (missingScopes.length > 0) {
-      throw new ScalekitValidateTokenFailureException(`Token missing required scopes: ${missingScopes.join(', ')}`);
+      throw new ScalekitValidateTokenFailureException(
+        `Token missing required scopes: ${missingScopes.join(", ")}`
+      );
     }
-    
+
     return true;
   }
 
   /**
    * Extract scopes from token payload
-   * 
+   *
    * @param {any} payload The token payload
    * @return {string[]} Array of scopes found in the token
    */
@@ -394,7 +660,7 @@ export default class ScalekitClient {
 
   /**
    * Verify the timestamp
-   * 
+   *
    * @param {string} timestampStr The timestamp string
    * @return {Date} Returns the timestamp
    */
@@ -416,36 +682,100 @@ export default class ScalekitClient {
 
   /**
    * Compute the signature
-   * 
+   *
    * @param {Buffer} secretBytes The secret bytes
    * @param {string} data The data to be signed
    * @return {string} Returns the signature
    */
   private computeSignature(secretBytes: Buffer, data: string): string {
-    return crypto.createHmac('sha256', secretBytes).update(data).digest('base64');
+    return crypto
+      .createHmac("sha256", secretBytes)
+      .update(data)
+      .digest("base64");
   }
 
   /**
-   * Refresh access token using a refresh token
-   * @param {string} refreshToken The refresh token to use
-   * @returns {Promise<RefreshTokenResponse>} Returns new access token, refresh token and other details
-   * @throws {Error} When authentication fails or response data is invalid
+   * Obtains a new access token using a refresh token.
+   *
+   * Use this method to get a new access token when the current one expires, without requiring
+   * the user to re-authenticate. This implements the OAuth 2.0 refresh token grant type.
+   * The method returns both a new access token and a new refresh token (token rotation).
+   *
+   * @param {string} refreshToken - The refresh token obtained from a previous authentication
+   *
+   * @returns {Promise<RefreshTokenResponse>} Response containing:
+   *   - accessToken: New access token for API authorization
+   *   - refreshToken: New refresh token (the old one is invalidated)
+   *
+   * @throws {Error} When the refresh token is missing
+   * @throws {Error} When the refresh token is invalid, expired, or revoked
+   * @throws {Error} When the authentication server response is invalid
+   *
+   * @example
+   * // Refresh tokens before they expire
+   * async function refreshUserToken(userId) {
+   *   try {
+   *     const oldRefreshToken = await getStoredRefreshToken(userId);
+   *
+   *     const result = await scalekitClient.refreshAccessToken(oldRefreshToken);
+   *
+   *     // Store the new tokens (old refresh token is now invalid)
+   *     await storeTokens(userId, {
+   *       accessToken: result.accessToken,
+   *       refreshToken: result.refreshToken
+   *     });
+   *
+   *     return result.accessToken;
+   *   } catch (error) {
+   *     console.error('Token refresh failed:', error);
+   *     // Redirect user to login
+   *     throw new Error('Please log in again');
+   *   }
+   * }
+   *
+   * @example
+   * // Automatic token refresh middleware
+   * app.use(async (req, res, next) => {
+   *   const accessToken = req.session.accessToken;
+   *   const refreshToken = req.session.refreshToken;
+   *
+   *   // Check if access token is expired (decode JWT and check exp claim)
+   *   if (isTokenExpired(accessToken) && refreshToken) {
+   *     try {
+   *       const result = await scalekitClient.refreshAccessToken(refreshToken);
+   *       req.session.accessToken = result.accessToken;
+   *       req.session.refreshToken = result.refreshToken;
+   *     } catch (error) {
+   *       return res.redirect('/login');
+   *     }
+   *   }
+   *   next();
+   * });
+   *
    */
-  async refreshAccessToken(refreshToken: string): Promise<RefreshTokenResponse> {
+  async refreshAccessToken(
+    refreshToken: string
+  ): Promise<RefreshTokenResponse> {
     if (!refreshToken) {
       throw new Error("Refresh token is required");
     }
 
     let res;
     try {
-      res = await this.coreClient.authenticate(QueryString.stringify({
-        grant_type: GrantType.RefreshToken,
-        client_id: this.coreClient.clientId,
-        client_secret: this.coreClient.clientSecret,
-        refresh_token: refreshToken
-      }));
+      res = await this.coreClient.authenticate(
+        QueryString.stringify({
+          grant_type: GrantType.RefreshToken,
+          client_id: this.coreClient.clientId,
+          client_secret: this.coreClient.clientSecret,
+          refresh_token: refreshToken,
+        })
+      );
     } catch (error) {
-      throw new Error(`Failed to refresh token: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      throw new Error(
+        `Failed to refresh token: ${
+          error instanceof Error ? error.message : "Unknown error"
+        }`
+      );
     }
 
     if (!res || !res.data) {
@@ -464,8 +794,7 @@ export default class ScalekitClient {
 
     return {
       accessToken: access_token,
-      refreshToken: refresh_token
+      refreshToken: refresh_token,
     };
   }
 }
-