matrix-react-sdk/lib/src/Lifecycle.d.ts

SDK for matrix.org using React

import { MatrixClient } from "matrix-js-sdk/src/matrix";
import { AESEncryptedSecretStoragePayload } from "matrix-js-sdk/src/types";
import { QueryDict } from "matrix-js-sdk/src/utils";
import { IMatrixClientCreds } from "./MatrixClientPeg";
import { OidcClientStore } from "./stores/oidc/OidcClientStore";
export declare function setSessionLockNotStolen(): void;
/**
 * Handle the session lock being stolen. Stops any active Matrix Client, and aborts any ongoing client initialisation.
 */
export declare function onSessionLockStolen(): Promise<void>;
interface ILoadSessionOpts {
    enableGuest?: boolean;
    guestHsUrl?: string;
    guestIsUrl?: string;
    ignoreGuest?: boolean;
    defaultDeviceDisplayName?: string;
    fragmentQueryParams?: QueryDict;
}
/**
 * Called at startup, to attempt to build a logged-in Matrix session. It tries
 * a number of things:
 *
 * 1. if we have a guest access token in the fragment query params, it uses
 *    that.
 * 2. if an access token is stored in local storage (from a previous session),
 *    it uses that.
 * 3. it attempts to auto-register as a guest user.
 *
 * If any of steps 1-4 are successful, it will call {_doSetLoggedIn}, which in
 * turn will raise on_logged_in and will_start_client events.
 *
 * @param {object} [opts]
 * @param {object} [opts.fragmentQueryParams]: string->string map of the
 *     query-parameters extracted from the #-fragment of the starting URI.
 * @param {boolean} [opts.enableGuest]: set to true to enable guest access
 *     tokens and auto-guest registrations.
 * @param {string} [opts.guestHsUrl]: homeserver URL. Only used if enableGuest
 *     is true; defines the HS to register against.
 * @param {string} [opts.guestIsUrl]: homeserver URL. Only used if enableGuest
 *     is true; defines the IS to use.
 * @param {bool} [opts.ignoreGuest]: If the stored session is a guest account,
 *     ignore it and don't load it.
 * @param {string} [opts.defaultDeviceDisplayName]: Default display name to use
 *     when registering as a guest.
 * @returns {Promise} a promise which resolves when the above process completes.
 *     Resolves to `true` if we ended up starting a session, or `false` if we
 *     failed.
 */
export declare function loadSession(opts?: ILoadSessionOpts): Promise<boolean>;
/**
 * Gets the user ID of the persisted session, if one exists. This does not validate
 * that the user's credentials still work, just that they exist and that a user ID
 * is associated with them. The session is not loaded.
 * @returns {[string, boolean]} The persisted session's owner and whether the stored
 *     session is for a guest user, if an owner exists. If there is no stored session,
 *     return [null, null].
 */
export declare function getStoredSessionOwner(): Promise<[string, boolean] | [null, null]>;
/**
 * If query string includes OIDC authorization code flow parameters attempt to login using oidc flow
 * Else, we may be returning from SSO - attempt token login
 *
 * @param {Object} queryParams    string->string map of the
 *     query-parameters extracted from the real query-string of the starting
 *     URI.
 *
 * @param {string} defaultDeviceDisplayName
 * @param {string} fragmentAfterLogin path to go to after a successful login, only used for "Try again"
 *
 * @returns {Promise} promise which resolves to true if we completed the delegated auth login
 *      else false
 */
export declare function attemptDelegatedAuthLogin(queryParams: QueryDict, defaultDeviceDisplayName?: string, fragmentAfterLogin?: string): Promise<boolean>;
/**
 * @param {QueryDict} queryParams    string->string map of the
 *     query-parameters extracted from the real query-string of the starting
 *     URI.
 *
 * @param {string} defaultDeviceDisplayName
 * @param {string} fragmentAfterLogin path to go to after a successful login, only used for "Try again"
 *
 * @returns {Promise} promise which resolves to true if we completed the token
 *    login, else false
 */
export declare function attemptTokenLogin(queryParams: QueryDict, defaultDeviceDisplayName?: string, fragmentAfterLogin?: string): Promise<boolean>;
export interface IStoredSession {
    hsUrl: string;
    isUrl: string;
    hasAccessToken: boolean;
    accessToken: string | AESEncryptedSecretStoragePayload;
    hasRefreshToken: boolean;
    refreshToken?: string | AESEncryptedSecretStoragePayload;
    userId: string;
    deviceId: string;
    isGuest: boolean;
}
/**
 * Retrieves information about the stored session from the browser's storage. The session
 * may not be valid, as it is not tested for consistency here.
 * @returns {Object} Information about the session - see implementation for variables.
 */
export declare function getStoredSessionVars(): Promise<Partial<IStoredSession>>;
/** Attempt to restore the session from localStorage or indexeddb.
 *
 * @returns true if a session was found; false if no existing session was found.
 *
 * N.B. Lifecycle.js should not maintain any further localStorage state, we
 *      are moving towards using SessionStore to keep track of state related
 *      to the current session (which is typically backed by localStorage).
 *
 *      The plan is to gradually move the localStorage access done here into
 *      SessionStore to avoid bugs where the view becomes out-of-sync with
 *      localStorage (e.g. isGuest etc.)
 */
export declare function restoreSessionFromStorage(opts?: {
    ignoreGuest?: boolean;
}): Promise<boolean>;
/**
 * Transitions to a logged-in state using the given credentials.
 *
 * Starts the matrix client and all other react-sdk services that
 * listen for events while a session is logged in.
 *
 * Also stops the old MatrixClient and clears old credentials/etc out of
 * storage before starting the new client.
 *
 * @param {IMatrixClientCreds} credentials The credentials to use
 *
 * @returns {Promise} promise which resolves to the new MatrixClient once it has been started
 */
export declare function setLoggedIn(credentials: IMatrixClientCreds): Promise<MatrixClient>;
/**
 * Logs the current session out and transitions to the logged-out state
 * @param oidcClientStore store instance from SDKContext
 */
export declare function logout(oidcClientStore?: OidcClientStore): void;
export declare function softLogout(): void;
export declare function isSoftLogout(): boolean;
export declare function isLoggingOut(): boolean;
export declare function onLoggedOut(): Promise<void>;
/**
 * Stop all the background processes related to the current client.
 * @param {boolean} unsetClient True (default) to abandon the client
 * on MatrixClientPeg after stopping.
 */
export declare function stopMatrixClient(unsetClient?: boolean): void;
export {};