@openpass/openpass-js-sdk/dist/types/src/types.d.ts

OpenPass SSO JavaScript SDK

import { SdkError } from "./auth/error/errors";
import { QUICK_AUTH_MESSAGE_TYPE } from "./auth/constants";
export interface OpenPassClientAuth {
    signInWithRedirect(options: RedirectSignInOptions): Promise<void>;
    isAuthenticationRedirect(): boolean;
    handleAuthenticationRedirect(): Promise<SignInResponse>;
    signInWithPopup(options: PopupSignInOptions): Promise<SignInResponse>;
    renderInlineSignInForm(options: InlineSignInOptions): void;
    cleanupInlineSignInForm(): void;
    renderSignInButton(options: SignInButtonOptions): void;
}
export type PopupSuccessCallback = (response: SignInResponse) => void;
export type PopupFailedCallback = (error: SdkError) => void;
export type PopupSignInInitiatedCallback = () => void;
export type VisibilityChangedCallback = (data: VisibilityChangedData) => void;
export type OpenPassOptions = {
    /**
     * The client ID of the application.
     */
    clientId: string;
    /**
     * The base URL of the OpenPass API.
     */
    baseUrl?: string;
};
export type SignInClientState = Record<string, string>;
export type CustomQueryParameter = {
    /**
     * Name of the extra query parameter to send in the request
     */
    name: string;
    /**
     * Value of the extra query parameter
     */
    value: string;
};
export type SignInOptionsBase = {
    /**
     * Can be used to maintain the state between the sign-in request and callback.
     */
    clientState?: SignInClientState;
    /**
     * A hint for the login email address identifier the user might log in with.
     */
    loginHint?: string;
    /**
     * If silentAuth feature can be attempted (if the user has a session and has consented)
     */
    trySilentAuth?: boolean;
    /**
     * If the user already has a session
     */
    hasSession?: boolean;
    /**
     * If a login hint is provided, this can be set to true to prevent the user from changing the sign-in email address.
     */
    disableLoginHintEditing?: boolean;
    /**
     * Extra query parameters to be sent to the authorization request
     */
    customQueryParameters?: Array<CustomQueryParameter>;
    /**
     * If set to true and client is authorized, a new user can sign-in without OTP.
     */
    allowUnverifiedEmail?: boolean;
};
export type RedirectSignInOptions = SignInOptionsBase & {
    /**
     * Specifies the URL to which the user will be redirected.
     */
    redirectUrl: string;
};
export type PopupSignInOptions = SignInOptionsBase & {
    /**
     * Specifies an optional fallback URL to which the user will be redirected to if the popup window fails to open.
     */
    redirectUrl?: string;
};
export type SignInResponse = {
    /**
     * The client state that was stored when initiating the authentication flow.
     * Note: This is useful for the redirect authentication flow, to be able to store optional client state and retrieve it when the sign-in completes.
     */
    clientState?: SignInClientState;
    /**
     * The originating window URI that the user was on when the authentication flow was initiated.
     * Note: This is useful for the redirect authentication flow to be able to redirect the user back to the page that initiated the sign-in.
     */
    originatingUri: string;
} & OpenPassTokens;
export interface OpenPassTokens {
    /**
     * The decoded ID token, which contains the user's identity details (including their email address).
     */
    idToken: IdToken;
    /**
     *  The raw ID token string (JWT) which contains the user's identity details (including their email address).
     */
    rawIdToken: string;
    /**
     *  The access token, which can be used to do Bearer authorization against APIs.
     */
    accessToken: string;
    /**
     *  Deprecated: Use `accessToken` instead.
     *  The raw access token string, which can be used to do Bearer authorization against APIs.
     */
    rawAccessToken: string;
    /**
     *  The refresh token, which can be used to refresh an expired access token.
     */
    refreshToken: string;
    /**
     * The token type, which is always "Bearer".
     */
    tokenType: string;
    /**
     * When the access token expires in seconds
     */
    expiresIn: number;
}
export type IdToken = {
    /**
     * The token issuer
     */
    iss?: string;
    /**
     * The subject, i.e. the user's unique identifier
     */
    sub?: string;
    /**
     * The audience that the token is intended for, i.e. the client ID
     */
    aud?: string[] | string;
    /**
     * The token expiry time, as the number of seconds since the Unix epoch
     */
    exp?: number;
    /**
     * The token not-before time, as the number of seconds since the Unix epoch
     */
    nbf?: number;
    /**
     * The token issue time, as the number of seconds since the Unix epoch
     */
    iat?: number;
    /**
     * A unique identifier for the JWT
     */
    jti?: string;
    /**
     * The user's email address
     */
    email?: string;
    /**
     * The user's first name
     */
    given_name?: string;
    /**
     * The user's last name
     */
    family_name?: string;
};
export type AuthenticationModeType = "redirect" | "popup";
export type InlineSignInButtonTextOption = "continue" | "signin";
export type VisibilityType = "displayOnInit" | "displayOnInitIfSessionActive" | "hideOnInit";
export type QuickAuthVisibility = "visible" | "hidden";
export type InlineSignInOptions = {
    /**
     * Specifies the ID of the HTML element where the sign-in form is inserted. This is usually a div element large enough to wrap around the sign-in form.
     */
    parentContainerElementId: string;
    /**
     * This determines how the sign-in process is handled, either by redirecting the user to a new page or opening a popup window.
     */
    authenticationMode: AuthenticationModeType;
    /**
     * The client state that was stored when initiating the authentication flow.
     * Note: This is useful for the redirect authentication flow, to be able to store optional client state and retrieve it when the sign-in completes.
     */
    clientState?: SignInClientState;
    /**
     * Specifies the text that appears on the sign-in button.
     */
    signinButtonTextOption?: InlineSignInButtonTextOption;
    /**
     * Sets the background color of the inline sign-in form iFrame. Defaults to OpenPass colours if not specified.
     */
    signinButtonBackgroundColorHex?: string;
    /**
     * Sets the border radius of the sign-in button. Defaults to "pill" styling if not specified (fully rounded sides).
     */
    signinButtonBorderRadiusInPixels?: number;
    /**
     * Hides application logo on the sign in form. Defaults to false if not specified.
     */
    hideSignInFormApplicationLogo?: boolean;
    /**
     * Hides the sign-in form header text. Defaults to false if not specified.
     */
    hideSignInFormHeaderText?: boolean;
    /**
     * Sets the width of the inline sign-in form iFrame. Defaults to 100% if not specified.
     */
    widthInPixels?: number;
    /**
     * Sets the height of the inline sign-in form iFrame. Defaults to 100% if not specified.
     */
    heightInPixels?: number;
    /**
     * Enables dark mode for the inline sign-in form. Defaults to false if not specified.
     */
    darkModeEnabled?: boolean;
    /**
     * Applies only to the popup option. This function is called when sign-in is successful. It receives a SignInResponse object as a parameter.
     * @param response
     */
    popupSuccessCallback?: PopupSuccessCallback;
    /**
     * Applies only to the popup option. This function is called when sign-in fails. It receives an SdkError object as a parameter, which contains the error.
     * @param error
     * @returns
     */
    popupFailureCallback?: PopupFailedCallback;
    /**
     * Applies only to the popup option. This function is called when the sign-in is initiated (i.e. the user clicks the sign-in button).
     * @returns
     */
    popupSignInInitiatedCallback?: PopupSignInInitiatedCallback;
    /**
     * Extra query parameters to be sent to the authorization request
     */
    customQueryParameters?: Array<CustomQueryParameter>;
    /**
     * If set to true and client is authorized, a new user can sign-in without OTP.
     */
    allowUnverifiedEmail?: boolean;
} & /**
 * Specifies the URL to which the user will be redirected based on the authentication mode:
 */ (/**
 * - Required when `authenticationMode` is set to "redirect". This URL determines where the user is redirected after the sign-in process.
 */ {
    authenticationMode: "redirect";
    redirectUrl: string;
}
/**
 * - Optional when `authenticationMode` is set to "popup". It acts as a fallback URL if the popup window fails to open.
 */
 | {
    authenticationMode: "popup";
    redirectUrl?: string;
});
export type QuickAuthSignInOptions = {
    /**
     * Specifies the ID of the HTML element where the sign-in form is inserted. This is usually a div element large enough to wrap around the sign-in form.
     */
    parentContainerElementId: string;
    /**
     * This determines how the sign-in process is handled, either by redirecting the user to a new page or opening a popup window.
     */
    authenticationMode: AuthenticationModeType;
    /**
     * Specifies the URL to which the user will be redirected when the authentication mode is set to redirect, if authentication mode is set to popup, this becomes an optional field.
     */
    redirectUrl?: string;
    /**
     * The client state that was stored when initiating the authentication flow.
     * Note: This is useful for the redirect authentication flow, to be able to store optional client state and retrieve it when the sign-in completes.
     */
    clientState?: SignInClientState;
    /**
     * Applies only to the popup option. This function is called when sign-in is successful. It receives a SignInResponse object as a parameter.
     * @param response
     */
    popupSuccessCallback?: PopupSuccessCallback;
    /**
     * Applies only to the popup option. This function is called when sign-in fails. It receives an SdkError object as a parameter, which contains the error.
     * @param error
     * @returns
     */
    popupFailureCallback?: PopupFailedCallback;
    /**
     * @deprecated. Ignored if `visibility` is set, or if `show` is set to true or false then this implies `visibility` is set to `displayOnInit` or `hideOnInit` respectively.
     *
     * Determines wether we render the quick-auth sign-in or not.
     */
    show?: boolean;
    /**
     * Determines the visibility of the quick-auth sign-in form. Defaults to `displayOnInit`.
     *
     * Values:
     * - `displayOnInit` - The quick-auth dialog becomes visible on render.
     * - `displayOnInitIfSessionActive` - The quick-auth dialog becomes visible on render if the user has an active session.
     * - `hideOnInit` - The quick-auth dialog is hidden on render. It can be manually displayed by calling `showQuickAuthSignIn`.
     */
    visibility?: VisibilityType;
    /**
     * This callback returns the visibility state of the quick-auth sign-in form.
     *
     * The callback contains a object with a `visibility` property that can be one of the following values:
     * - `visible` - The quick-auth dialog becomes visible.
     * - `hidden` - The quick-auth dialog becomes or stays hidden.
     */
    visibilityChangedCallback?: VisibilityChangedCallback;
    /**
     * The delay in milliseconds before the quick-auth sign-in form is displayed when `render` is called.
     *
     * Notes:
     * - The quick-auth dialog will only show on render if visibility is set to `displayOnInit` or `displayOnInitIfSessionActive`.
     * - Manually calling `showQuickAuthSignIn` or `hideQuickAuthSignIn` will display the quick-auth dialog instantly.
     *
     * Defaults to 1000ms.
     */
    delayMs?: number;
    /**
     * Extra query parameters to be sent to the authorization request
     */
    customQueryParameters?: Array<CustomQueryParameter>;
    /**
     * If set to true and client is authorized, a new user can sign-in without OTP.
     */
    allowUnverifiedEmail?: boolean;
};
export type QuickAuthInitMessage = {
    type: typeof QUICK_AUTH_MESSAGE_TYPE.Init;
    /**
     * Indicates whether current user has active session
     */
    hasSession: boolean;
    /**
     * The width of signin popup
     */
    popupWidth: number;
    /**
     * The height of signin popup
     */
    popupHeight: number;
};
export type QuickAuthPopupSizeParams = {
    width: number;
    height: number;
};
export type SignInButtonText = "signin_with" | "signin" | "continue_with";
export type SignInButtonShape = "standard" | "icon";
export type SignInButtonShapeVariant = "pill" | "rectangle" | "square" | "circle";
export type SignInButtonSize = "x-large" | "large" | "medium" | "small";
export type SignInButtonTheme = "openpass" | "light" | "dark";
export type SignInButtonOptions = {
    /**
     * Specifies the ID of the HTML element where the sign-in button is inserted. This is usually a div element large enough to wrap around the sign-in button.
     */
    parentContainerElementId: string;
    /**
     * This determines how the sign-in process is handled, either by redirecting the user to a new page or opening a popup window.
     */
    authenticationMode: AuthenticationModeType;
    /**
     * Specifies the URL to which the user will be redirected when the authentication mode is set to redirect, or optional if set to popup to enable fallback mode to the redirect flow if the popup window fails to open.
     */
    redirectUrl?: string;
    /**
     * An optional hint for the login email address identifier the user might log in with.
     */
    loginHint?: string;
    /**
     * Applies only to the popup option. This function is called when sign-in is successful. It receives a SignInResponse object as a parameter.
     * @param response
     */
    popupSuccessCallback?: PopupSuccessCallback;
    /**
     * Applies only to the popup option. This function is called when sign-in fails. It receives an SdkError object as a parameter, which contains the error.
     * @param error
     * @returns
     */
    popupFailedCallback?: PopupFailedCallback;
    /**
     * The client state that was stored when initiating the authentication flow.
     * Note: This is useful for the redirect authentication flow, to be able to store optional client state and retrieve it when the sign-in completes.
     */
    clientState?: SignInClientState;
    /**
     * Specifies the shape of the button. Defaults to 'standard'.
     */
    shape?: SignInButtonShape;
    /**
     * The shape variant of the button. Defaults to 'pill'.
     */
    shapeVariant?: SignInButtonShapeVariant;
    /**
     * The size of the button. Defaults to 'large'.
     */
    size?: SignInButtonSize;
    /**
     * The text that appears on the button. Defaults to 'signin_with'.
     */
    text?: SignInButtonText;
    /**
     * The theme of the button. Defaults to 'openpass'.
     */
    theme?: SignInButtonTheme;
    /**
     * Additional width to apply to the button.
     */
    additionalWidth?: number;
    /**
     * Extra query parameters to be sent to the authorization request
     */
    customQueryParameters?: Array<CustomQueryParameter>;
    /**
     * If set to true and client is authorized, a new user can sign-in without OTP.
     */
    allowUnverifiedEmail?: boolean;
};
export type AuthorizeDeviceOptions = {
    /**
     * A hint for the login email address identifier the user might log in with.
     */
    loginHint?: string;
    disableLoginHintEditing?: boolean;
};
export type DeviceTokenOptions = {
    /**
     * The device code which was returned from the authorizeDevice method.
     */
    deviceCode: string;
};
export type AuthorizeDeviceData = {
    deviceCode: string;
    userCode: string;
    verificationUri: string;
    verificationUriComplete: string;
    expiresIn: number;
    interval: number;
};
export type DeviceTokenWithStatus = {
    status: "ok" | "slow_down" | "authorization_pending";
    tokens?: OpenPassTokens;
};
export type VisibilityChangedData = {
    visibility: QuickAuthVisibility;
};