Class MonoCloudWebJSClient

constructor

• new MonoCloudWebJSClient(
      options: MonoCloudWebJSClientOptions,
  ): MonoCloudWebJSClient

  Initializes a new instance of MonoCloudWebJSClient.

  Parameters

  • options: MonoCloudWebJSClientOptions

    Configuration options for the client.

  Returns MonoCloudWebJSClient

  Example: Default Integration

  import { MonoCloudWebJSClient } from '@monocloud/auth-web-js';
  
  export const client = new MonoCloudWebJSClient({
    tenantDomain: 'https://<your-tenant>',
    clientId: '<your-client-id>',
  });
  Copy

  Example: Custom Storage & Router

  import { MonoCloudWebJSClient, MemoryStorage } from '@monocloud/auth-web-js';
  import { router } from './router';
  
  export const client = new MonoCloudWebJSClient({
    tenantDomain: 'https://<your-tenant>',
    clientId: '<your-client-id>',
    storage: new MemoryStorage(),
    postCallback: state => {
      router.push(state.returnUrl ?? '/dashboard');
    },
  });
  Copy

ReadonlyoidcClient

getSession

• getSession(): Promise<MonoCloudSession | undefined>

  Retrieves the current session object from the configured storage.

  Returns Promise<MonoCloudSession | undefined>

  The active session, or undefined if not authenticated.

  Example: Usage

  const session = await client.getSession();
  if (session) {
    console.log('User is logged in:', session.user);
  }
  Copy

getTokens

• getTokens(options?: GetTokensOptions): Promise<MonoCloudTokens>

  Retrieves the active tokens for the current session.

  If the access token is expired (or about to expire), this method automatically attempts to refresh it using the Refresh Token Grant before returning.

  Parameters

  • Optionaloptions: GetTokensOptions

    Options that control token retrieval (force refresh, scopes, resource).

  Returns Promise<MonoCloudTokens>

  The active tokens for the requested resource and scopes.

  Example: Get Default Tokens

  const tokens = await client.getTokens();
  console.log(tokens.accessToken);
  Copy

  Example: Force Refresh

  const tokens = await client.getTokens({ forceRefresh: true });
  Copy

  Example: Specific Resource

  const tokens = await client.getTokens({
    resource: 'https://api.example.com',
    scopes: 'read:data',
  });
  Copy

  Throws

  MonoCloudValidationError If no session exists or the access token cannot be located.

processCallback

• processCallback(): Promise<void>

  Processes the authentication callback from the authorization server.

  Call this once on application startup (typically in your entry point or router). It inspects the current URL together with the persisted callback state and automatically completes a pending sign-in or sign-out flow - there is no need to dispatch on the route yourself.

  Returns Promise<void>

  A promise that resolves when callback processing is complete.

  Example: Application Entry

  async function init() {
    // Complete any pending redirect callback before rendering.
    await client.processCallback();
  
    // Continue mounting the app.
  }
  
  init();
  Copy

refetchUserInfo

• refetchUserInfo(): Promise<void>

  Refetches user information from the UserInfo endpoint and updates the local session.

  The default access token (matching the client's configured default resource and authorized scopes) is used to call the UserInfo endpoint.

  Returns Promise<void>

  Example: Usage

  await client.refetchUserInfo();
  const session = await client.getSession();
  console.log('Updated user data:', session?.user);
  Copy

  Throws

  MonoCloudValidationError If the session is invalid or the default access token is missing.

refreshSession

• refreshSession(refreshOptions?: RefreshOptions): Promise<void>

  Refreshes the current user's session using the OAuth 2.0 Refresh Token Grant.

  Requires a session that includes a refresh token (obtained by including the offline_access scope at sign-in).

  To start a fresh, non-interactive authorization (for example, on app bootstrap when there is no local session yet) use signInSilent() instead.

  Parameters

  • OptionalrefreshOptions: RefreshOptions

    Optional configuration for the refresh flow.

  Returns Promise<void>

  A promise that resolves when the session has been refreshed.

  Example: Default

  await client.refreshSession();
  Copy

  Example: Resource-Scoped Refresh

  await client.refreshSession({
    refreshGrantOptions: {
      resource: 'https://api.example.com',
      scopes: 'read:data',
    },
  });
  Copy

  Throws

  MonoCloudValidationError If the session is invalid or missing a refresh token.

signIn

• signIn(signInOptions?: SignInOptions): Promise<void>

  Initiates the sign-in flow.

  Parameters

  • OptionalsignInOptions: SignInOptions

    Optional configuration for the sign-in request.

  Returns Promise<void>

  Example: Redirect Flow

  await client.signIn();
  Copy

  Example: Popup Flow

  await client.signIn({ mode: 'popup' });
  Copy

  Example: Sign Up

  await client.signIn({ signUp: true });
  Copy

signInSilent

• signInSilent(
      signInSilentOptions?: SignInSilentOptions,
  ): Promise<MonoCloudSession>

  Attempts to silently sign the user in using a hidden iframe and prompt=none.

  Useful for restoring a session at app bootstrap when the user is signed in at MonoCloud but no local session exists yet (for example, after opening a new tab or a hard refresh that cleared in-memory storage).

  The method runs a full authorization round-trip through a hidden iframe. If MonoCloud has a valid session it resolves to the new session. Otherwise it rejects with a MonoCloudOPError.

  Parameters

  • OptionalsignInSilentOptions: SignInSilentOptions

    Optional configuration for the silent sign-in request.

  Returns Promise<MonoCloudSession>

  The newly established session.

  Example: Usage

  import { MonoCloudOPError } from '@monocloud/auth-web-js';
  
  try {
    const session = await client.signInSilent();
    console.log('Restored session for:', session.user);
  } catch (error) {
    if (error instanceof MonoCloudOPError && error.error === 'login_required') {
      console.log('Not signed in');
    } else {
      throw error;
    }
  }
  Copy

  Throws

  MonoCloudOPError If the authorization server cannot satisfy the request - for example, because the user has no IdP session (login_required) or interaction is otherwise required.

  Throws

  MonoCloudJsError If the iframe cannot be created (for example, in a cross-origin-isolated context) or the authentication window times out.

signOut

• signOut(signOutOptions?: SignOutOptions): Promise<void>

  Initiates the sign-out flow.

  Clears the local session and, when federatedSignOut is enabled, also signs the user out of MonoCloud (Single Sign-Out).

  Parameters

  • OptionalsignOutOptions: SignOutOptions

    Optional configuration for the sign-out request.

  Returns Promise<void>

  A promise that resolves when the sign-out flow has been initiated (redirect mode) or completed (popup mode).

  Example: Standard Sign Out

  await client.signOut();
  Copy

  Example: Popup Sign Out

  await client.signOut({ mode: 'popup' });
  Copy