Matrix JavaScript SDK

https://matrix-org.github.io/matrix-js-sdk/
Admin
Matrix JavaScript SDK is a client-server SDK for JavaScript and TypeScript that enables building...
Tokens:13,325
Snippets:91
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Start Matrix Client with Initial Sync Limit

Source: https://matrix-org.github.io/matrix-js-sdk/index

Shows how to start the Matrix client after creation, specifying an initial sync limit to control the amount of historical data fetched during the first sync.

```JavaScript
await client.startClient({ initialSyncLimit: 10 });
```

--------------------------------

### Install SDK Dependencies

Source: https://matrix-org.github.io/matrix-js-sdk/index

Installs all required dependencies for the Matrix JavaScript SDK using Yarn package manager. This command should be run first when setting up a development environment or after cloning the repository. Requires Node.js and Yarn to be installed on the system.

```shell
$ yarn install
```

--------------------------------

### Listen for Matrix Events and Typing Changes

Source: https://matrix-org.github.io/matrix-js-sdk/index

Demonstrates how to listen for low-level MatrixEvents and specific RoomMember typing events using the SDK's EventEmitter. It also shows how to start the client connection.

```javascript
import * as sdk from "matrix-js-sdk";

// Assuming client is an instance of MatrixClient
const client = sdk.createClient({
    baseUrl: "http://localhost:8008",
    accessToken: "YOUR_ACCESS_TOKEN",
    userId: "@your_user_id:localhost",
});

// Listen for low-level MatrixEvents
client.on(sdk.ClientEvent.Event, function (event) {
    console.log(event.getType());
});

// Listen for typing changes
client.on(sdk.RoomMemberEvent.Typing, function (event, member) {
    if (member.typing) {
        console.log(member.name + " is typing...");
    } else {
        console.log(member.name + " stopped typing.");
    }
});

// start the client to setup the connection to the server
client.startClient();
```

--------------------------------

### Key Backup (JavaScript)

Source: https://matrix-org.github.io/matrix-js-sdk/index

This snippet illustrates how to check and create a key backup, ensuring that encryption keys are securely stored and recoverable.

```JavaScript
// Check if we have a key backup.
// If checkKeyBackupAndEnable returns null, there is no key backup.
const hasKeyBackup = (await matrixClient.getCrypto().checkKeyBackupAndEnable()) !== null;

// Create the key backup
await matrixClient.getCrypto().resetKeyBackup();
```

--------------------------------

### Listen for Sync Completion Event

Source: https://matrix-org.github.io/matrix-js-sdk/index

Registers a one‑time listener for the `sync` event to detect when the client is prepared. Logs the state and exits on unexpected states.

```JavaScript
client.once(ClientEvent.sync, function (state, prevState, res) {
    if (state === "PREPARED") {
        console.log("prepared");
    } else {
        console.log(state);
        process.exit(1);
    }
});
```

--------------------------------

### Listen for Incoming Room Message Events

Source: https://matrix-org.github.io/matrix-js-sdk/index

Sets up a listener for timeline events, filters for message events, and logs the message body when received.

```JavaScript
client.on(RoomEvent.Timeline, function (event, room, toStartOfTimeline) {
    if (event.getType() !== "m.room.message") {
        return; // only use messages
    }
    console.log(event.event.content.body);
});
```

--------------------------------

### Automatically Join Rooms on Invite

Source: https://matrix-org.github.io/matrix-js-sdk/index

This example shows how to automatically join a room when an invitation is received. It listens for the 'MyMembership' event on rooms and calls `joinRoom` if the membership is an invite.

```javascript
import * as sdk from "matrix-js-sdk";

const myUserId = "@example:localhost";
const myAccessToken = "QGV4YW1wbGU6bG9jYWxob3N0.qPEvLuYfNBjxikiCjP";
const matrixClient = sdk.createClient({
    baseUrl: "http://localhost:8008",
    accessToken: myAccessToken,
    userId: myUserId,
});

matrixClient.on(sdk.RoomEvent.MyMembership, function (room, membership, prevMembership) {
    if (membership === sdk.KnownMembership.Invite) {
        matrixClient.joinRoom(room.roomId).then(function () {
            console.log("Auto-joined %s", room.roomId);
        });
    }
});

matrixClient.startClient();
```

--------------------------------

### Bootstrap Cross-Signing (JavaScript)

Source: https://matrix-org.github.io/matrix-js-sdk/index

This snippet demonstrates bootstrapping cross-signing for device verification. It includes the required callback for uploading device signing keys to the server.

```JavaScript
matrixClient.getCrypto().bootstrapCrossSigning({
    authUploadDeviceSigningKeys: async (makeRequest) => {
        return makeRequest(authDict);
    },
});
```

--------------------------------

### Import SDK and List Public Rooms with matrix-js-sdk

Source: https://matrix-org.github.io/matrix-js-sdk/index

Demonstrates importing the Matrix JavaScript SDK, creating a client instance, and retrieving the list of public rooms. Uses the `publicRooms` method with a callback to handle error and data.

```JavaScript
import * as sdk from "matrix-js-sdk";
const client = sdk.createClient({ baseUrl: "https://matrix.org" });
client.publicRooms(function (err, data) {
    console.log("Public Rooms: %s", JSON.stringify(data));
});
```

--------------------------------

### Generate API Documentation (Shell)

Source: https://matrix-org.github.io/matrix-js-sdk/index

This snippet details how to generate and locally serve the API documentation for the Matrix JS SDK using Yarn and Python. It sets up a local web server to view the generated documentation.

```Shell
$ yarn gendoc
$ cd docs
$ python -m http.server 8005
```

--------------------------------

### Print Messages from All Rooms

Source: https://matrix-org.github.io/matrix-js-sdk/index

This snippet demonstrates how to print messages from all rooms the client is in. It filters for events of type 'm.room.message' and avoids printing paginated results. It assumes a basic client setup.

```javascript
import * as sdk from "matrix-js-sdk";

const myUserId = "@example:localhost";
const myAccessToken = "QGV4YW1wbGU6bG9jYWxob3N0.qPEvLuYfNBjxikiCjP";
const matrixClient = sdk.createClient({
    baseUrl: "http://localhost:8008",
    accessToken: myAccessToken,
    userId: myUserId,
});

matrixClient.on(sdk.RoomEvent.Timeline, function (event, room, toStartOfTimeline) {
    if (toStartOfTimeline) {
        return; // don't print paginated results
    }
    if (event.getType() !== "m.room.message") {
        return; // only print messages
    }
    console.log(
        // the room name will update with m.room.name events automatically
        "(%s) %s :: %s",
        room.name,
        event.getSender(),
        event.getContent().body,
    );
});

matrixClient.startClient();

// Example output:
// (My Room) @megan:localhost :: Hello world
// (My Room) @megan:localhost :: how are you?
// (My Room) @example:localhost :: I am good
// (My Room) @example:localhost :: change the room name
// (My New Room) @megan:localhost :: done
```

--------------------------------

### Download Authenticated Media with matrix-js-sdk

Source: https://matrix-org.github.io/matrix-js-sdk/index

Generates an authenticated media URL using `mxcUrlToHttp` and fetches the media with an Authorization header containing the client's access token.

```JavaScript
const downloadUrl = client.mxcUrlToHttp(
    /*mxcUrl=*/ "mxc://example.org/abc123",
    /*width=*/ undefined,
    /*height=*/ undefined,
    /*resizeMethod=*/ undefined,
    /*allowDirectLinks=*/ false,
    /*allowRedirects=*/ true,
    /*useAuthentication=*/ true
);
const img = await fetch(downloadUrl, {
    headers: {
        Authorization: `Bearer ${client.getAccessToken()}`,
    },
});
// Do something with `img`.
```

--------------------------------

### Initialize End-to-End Encryption (JavaScript)

Source: https://matrix-org.github.io/matrix-js-sdk/index

This snippet demonstrates the initialization of end-to-end encryption support within a Matrix client. It uses the `initRustCrypto` function, and it is important to configure Indexed DB if running outside of a browser context.

```JavaScript
// Create a new matrix client
const matrixClient = sdk.createClient({
    baseUrl: "http://localhost:8008",
    accessToken: myAccessToken,
    userId: myUserId,
});

// Initialize to enable end-to-end encryption support.
await matrixClient.initRustCrypto();
```

--------------------------------

### Iterate Stored Timeline Events for All Rooms

Source: https://matrix-org.github.io/matrix-js-sdk/index

Uses the in‑memory store to iterate over each room's timeline events, printing each raw event object to the console.

```JavaScript
Object.keys(client.store.rooms).forEach((roomId) => {
    client.getRoom(roomId).timeline.forEach((t) => {
        console.log(t.event);
    });
});
```

--------------------------------

### Bootstrap Secret Storage (JavaScript)

Source: https://matrix-org.github.io/matrix-js-sdk/index

This snippet showcases how to bootstrap the secret storage for end-to-end encryption. It defines callbacks for obtaining and creating secret storage keys, providing user prompts for key management.

```JavaScript
const matrixClient = sdk.createClient({
    ...,
    cryptoCallbacks: {
        getSecretStorageKey: async (keys) => {
            // This function should prompt the user to enter their secret storage key.
            return mySecretStorageKeys;
        },
    },
});

matrixClient.getCrypto().bootstrapSecretStorage({
    // This function will be called if a new secret storage key (aka recovery key) is needed.
    // You should prompt the user to save the key somewhere, because they will need it to unlock secret storage in future.
    createSecretStorageKey: async () => {
        return mySecretStorageKey;
    },
});
```

--------------------------------

### Build Browser Version

Source: https://matrix-org.github.io/matrix-js-sdk/index

Compiles the Matrix JavaScript SDK into a browser-ready bundle from source. This command processes the SDK codebase and generates distribution files suitable for web browser usage. Typically used during development before testing in browser environments.

```shell
$ yarn build
```

--------------------------------

### Initialize Rust Crypto Migration with createClient

Source: https://matrix-org.github.io/matrix-js-sdk/index

Configures MatrixClient for automatic migration from legacy crypto to Rust crypto stack. Requires providing legacy cryptoStore and pickleKey parameters during client creation. The migration executes automatically when initRustCrypto() is called, transferring existing device data to the new crypto implementation.

```javascript
// You should provide the legacy crypto store and the pickle key to the matrix client in order to migrate the data.
const matrixClient = sdk.createClient({
    cryptoStore: myCryptoStore,
    pickleKey: myPickleKey,
    baseUrl: "http://localhost:8008",
    accessToken: myAccessToken,
    userId: myUserId,
});

// The migration will be done automatically when you call `initRustCrypto`.
await matrixClient.initRustCrypto();
```

--------------------------------

### Listen to Legacy Crypto Migration Progress Events

Source: https://matrix-org.github.io/matrix-js-sdk/index

Monitors migration progress from legacy crypto store to Rust crypto implementation. Subscribes to CryptoEvent.LegacyCryptoStoreMigrationProgress events to track migration status. Migration completion is indicated when progress and total values both equal -1, allowing applications to provide user feedback during the migration process.

```javascript
// When progress === total === -1, the migration is finished.
matrixClient.on(CryptoEvent.LegacyCryptoStoreMigrationProgress, (progress, total) => {
    ...
});
```

--------------------------------

### Send a Text Message to a Room

Source: https://matrix-org.github.io/matrix-js-sdk/index

Creates a message payload and uses `sendEvent` to post a simple text message to a specified room, handling any error via a callback.

```JavaScript
const content = {
    body: "message text",
    msgtype: "m.text",
};
client("roomId", "m.room.message", content, "", (err, res) => {
    console.log(err);
});
```

--------------------------------

### Run Code Linting

Source: https://matrix-org.github.io/matrix-js-sdk/index

Executes linting tools to enforce code style and quality standards across the Matrix JavaScript SDK codebase. Identifies potential errors, formatting issues, and deviations from project coding conventions. Should be run before committing changes to maintain code consistency.

```shell
$ yarn lint
```

--------------------------------

### Run SDK Tests

Source: https://matrix-org.github.io/matrix-js-sdk/index

Executes the Jest test suite for the Matrix JavaScript SDK. Runs all unit tests, integration tests, and validation checks to ensure code quality and functionality. Essential for verifying changes before committing or submitting pull requests.

```shell
$ yarn test
```

--------------------------------

### Listen for Room Membership Changes (JavaScript)

Source: https://matrix-org.github.io/matrix-js-sdk/index

This snippet shows how to listen for RoomStateEvent.Members events, allowing you to track changes in room membership. The code retrieves the room and its members, and logs the room name and membership details of each member.

```JavaScript
matrixClient.on(RoomStateEvent.Members, function (event, state, member) {
    const room = matrixClient.getRoom(state.roomId);
    if (!room) {
        return;
    }
    const memberList = state.getMembers();
    console.log(room.name);
    console.log(Array(room.name.length + 1).join("=")); // underline
    for (var i = 0; i < memberList.length; i++) {
        console.log("(%s) %s", memberList[i].membership, memberList[i].name);
    }
});

matrixClient.startClient();
```

--------------------------------

### Initiating Key Verification (TypeScript)

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Enables starting key verification flows within the Matrix JS SDK. `scanQRCode` begins a verification process using data from a scanned QR code, while `startVerification` initiates verification through a specified method, commonly used for emoji-based verification. Both return a `Verifier` object to manage the ongoing process.

```typescript
/**
 * Start a QR code verification by providing a scanned QR code for this verification flow.
 * Validates the QR code, and if it is ok, sends an `m.key.verification.start` event with `method` set to `m.reciprocate.v1`, to tell the other side the scan was successful.
 * See also VerificationRequest#startVerification which can be used to start other verification methods.
 * @param qrCodeData The decoded QR code.
 * @returns A verifier; call `.verify()` on it to wait for the other side to complete the verification flow.
 */
scanQRCode(qrCodeData: Uint8ClampedArray): Promise<Verifier>;

/**
 * Send an `m.key.verification.start` event to start verification via a particular method.
 * This is normally used when starting a verification via emojis (ie, `method` is set to `m.sas.v1`).
 * @param method The name of the verification method to use.
 * @returns The verifier which will do the actual verification.
 */
startVerification(method: string): Promise<Verifier>;
```

--------------------------------

### VerificationRequest Interface Definition

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Defines the structure and methods for handling verification requests in matrix-js-sdk. It includes properties to get request status and details, and methods to interact with the verification process.

```typescript
interface VerificationRequest {
get accepting(): boolean;
get cancellationCode(): null | string;
get cancellingUserId(): undefined | string;
get chosenMethod(): null | string;
get declining(): boolean;
get initiatedByMe(): boolean;
get isSelfVerification(): boolean;
get methods(): string[];
get otherDeviceId(): undefined | string;
get otherUserId(): string;
get pending(): boolean;
get phase(): VerificationPhase;
get roomId(): undefined | string;
get timeout(): null | number;
get transactionId(): undefined | string;
get verifier(): undefined | Verifier;
accept(): Promise<void>;
addListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this;
cancel(params?: { code?: string; reason?: string }): Promise<void>;
emit<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): boolean;
emit<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): boolean;
emitPromised<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): Promise<boolean>;
emitPromised<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): Promise<boolean>;
generateQRCode(): Promise<undefined | Uint8ClampedArray<ArrayBufferLike>>;
listenerCount(event: EventEmitterEvents | Change): number;
listeners(event: EventEmitterEvents | Change): Function[];
off<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this;
on<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this;
once<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this;
otherPartySupportsMethod(method: string): boolean;
prependListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this;
prependOnceListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this;
rawListeners(event: EventEmitterEvents | Change): Function[];
removeAllListeners(event?: EventEmitterEvents | Change): this;
removeListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this;
scanQRCode(qrCodeData: Uint8ClampedArray): Promise<Verifier>;
startVerification(method: string): Promise<Verifier>;
}
```

--------------------------------

### Get Specific Key Information from Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Fetches the key information for a given key ID. If no key ID is provided, it defaults to the current default key ID. Returns an array containing the key ID and its information, or null if the key is not found.

```typescript
getKey(keyId?: null | string): Promise<null | SecretStorageKeyTuple>
```

--------------------------------

### Get Secret from Server-Side Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Retrieves and decrypts a secret from server-side storage. It uses the SecretStorageCallbacks#getSecretStorageKey to obtain the necessary decryption key. Returns the decrypted secret or undefined if not found.

```typescript
get(name: keyof SecretStorageAccountDataEvents): Promise<undefined | string>
```

--------------------------------

### SecretStorageCallbacks Interface Definition

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/matrix.SecretStorage

Defines the callback interface for retrieving secret storage encryption keys. It includes a method for getting a key based on provided key descriptions and a secret name. The callback is used during secret storage and retrieval operations.

```TypeScript
interface SecretStorageCallbacks {
  getSecretStorageKey?: (
    keys: { keys: Record<string, SecretStorageKeyDescription> },
    name: string,
  ) => Promise<null | [string, Uint8Array<ArrayBufferLike>]>;
}
```

--------------------------------

### Get Default Key ID for Secret Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Retrieves the current default key ID used for encrypting secrets. This is the key that will be used by default if no specific key ID is provided for encryption operations.

```typescript
getDefaultKeyId(): Promise<null | string>
```

--------------------------------

### generateQRCode

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Generates data for a QR code allowing verification. Returns `undefined` if not in the verification ready phase.

```APIDOC
## generateQRCode

### Description
Generates the data for a QR code allowing the other device to verify this one, if it supports it.
Only returns data once `phase` is VerificationPhase.Ready and the other party can scan a QR code; otherwise returns `undefined`.

### Method
Promise

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- N/A

### Request Example
N/A

### Response
#### Success Response (200)
- `Uint8ClampedArray<ArrayBufferLike>` - QR code data

#### Response Example
N/A
```

--------------------------------

### prependOnceListener

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Adds a one-time listener function to the beginning of the listeners array for a given event.

```APIDOC
## prependOnceListener

### Description
Adds a **one-time**`listener` function for the event named `event` to the _beginning_ of the listeners array. The next time `event` is triggered, this listener is removed, and then invoked.

### Method
this

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- **event** (string) - The name of the event.
- **listener** (Listener) - The callback function

### Request Example
N/A

### Response
#### Success Response (200)
- **this** (EventEmitter) - A reference to the event emitter, for chaining.

#### Response Example
N/A
```

--------------------------------

### prependListener

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Adds a listener function to the beginning of the listeners array for a given event.

```APIDOC
## prependListener

### Description
Adds the `listener` function to the _beginning_ of the listeners array for the event named `event`.

### Method
this

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- **event** (string) - The name of the event.
- **listener** (Listener) - The callback function

### Request Example
N/A

### Response
#### Success Response (200)
- **this** (EventEmitter) - A reference to the event emitter, for chaining.

#### Response Example
N/A
```

--------------------------------

### Constructor for ServerSideSecretStorageImpl

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Constructs a new ServerSideSecretStorageImpl instance. It takes an account data adapter and callbacks for secret storage operations. While typically managed by MatrixClient, it can be instantiated directly for custom callback configurations.

```typescript
new ServerSideSecretStorageImpl(
  accountDataAdapter: AccountDataClient,
  callbacks: SecretStorageCallbacks,
): ServerSideSecretStorageImpl
```

--------------------------------

### once

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Adds a one-time listener function for a given event.

```APIDOC
## once

### Description
Adds a **one-time** `listener` function for the event named `event`. The next time `event` is triggered, this listener is removed and then invoked.

### Method
this

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- **event** (string) - The name of the event.
- **listener** (Listener) - The callback function

### Request Example
N/A

### Response
#### Success Response (200)
- **this** (EventEmitter) - A reference to the event emitter, for chaining.

#### Response Example
N/A
```

--------------------------------

### listeners

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Returns a copy of the array of listeners for a given event.

```APIDOC
## listeners

### Description
Returns a copy of the array of listeners for the event named `event`.

### Method
Function[]

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **Function[]** (array) - An array of listeners

#### Response Example
N/A
```

--------------------------------

### Promise-based event emission in TypeScript

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix

Similar to emit but uses Promise.all to call all listeners and returns a promise chain for asynchronous handling.

```typescript
emitPromised<T extends UserEvent>(
  event: T,
  ...args: Parameters<UserEventHandlerMap[T]>,
): Promise<boolean>
```

--------------------------------

### on

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Adds a listener function to the end of the listeners array for a given event.

```APIDOC
## on

### Description
Adds the `listener` function to the end of the listeners array for the event named `event`.

### Method
this

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- **event** (string) - The name of the event.
- **listener** (Listener) - The callback function

### Request Example
N/A

### Response
#### Success Response (200)
- **this** (EventEmitter) - A reference to the event emitter, for chaining.

#### Response Example
N/A
```

--------------------------------

### Create User constructor in TypeScript

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix

Constructs a new User instance with a required user ID. This is the base constructor for creating user objects in the Matrix SDK.

```typescript
new User(userId: string): User
```

--------------------------------

### VerificationRequest Accessor Descriptions

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Provides descriptions for the accessors of the VerificationRequest interface. These accessors allow retrieval of the current state and details of a verification request.

```typescript
/**
 * True if we have started the process of sending an `m.key.verification.ready` (but have not necessarily received the remote echo which causes a transition to VerificationPhase.Ready.
 * @returns boolean
 */
get accepting(): boolean;

/**
 * If this request has been cancelled, the cancellation code (e.g `m.user`) which is responsible for cancelling this verification.
 * @returns null | string
 */
get cancellationCode(): null | string;

/**
 * The id of the user that cancelled the request. Only defined when phase is Cancelled
 * @returns undefined | string
 */
get cancellingUserId(): undefined | string;

/**
 * the method picked in the .start event
 * @returns null | string
 */
get chosenMethod(): null | string;

/**
 * True if we have started the process of sending an `m.key.verification.cancel` (but have not necessarily received the remote echo which causes a transition to VerificationPhase.Cancelled).
 * @returns boolean
 */
get declining(): boolean;

/**
 * True if this request was initiated by the local client.
 * For in-room verifications, the initiator is who sent the `m.key.verification.request` event. For to-device verifications, the initiator is who sent the `m.key.verification.start` event.
 * @returns boolean
 */
get initiatedByMe(): boolean;

/**
 * True if the other party in this request is one of this user's own devices.
 * @returns boolean
 */
get isSelfVerification(): boolean;
```

--------------------------------

### Mock OpenID Configuration Function (JavaScript)

Source: https://matrix-org.github.io/matrix-js-sdk/functions/testing

The mockOpenIdConfiguration function is designed to simulate the /.well-known/openid-configuration endpoint for testing purposes. It accepts an optional issuer URL and an array of additional grant types to customize the mocked response. The function returns a ValidatedAuthMetadata object, which is essential for validating authentication flows in tests.

```javascript
/**
 * Mock OpenID Configuration
 * Useful for mocking /.well-known/openid-configuration
 * @param {string} issuer - used as the base for all other urls
 * @param {string[]} additionalGrantTypes - to add to the default grant types
 * @returns {ValidatedAuthMetadata}
 */
// Experimental
function mockOpenIdConfiguration(
  issuer?: string,
  additionalGrantTypes?: string[]
): ValidatedAuthMetadata {
  // Function implementation would go here
  // For example purposes, returning a placeholder object:
  return {
    issuer: issuer || "https://auth.org/",
    jwks_uri: `${issuer || "https://auth.org/"}/.well-known/openid-configuration/jwks",
    authorization_endpoint: `${issuer || "https://auth.org/"}/auth",
    token_endpoint: `${issuer || "https://auth.org/"}/token`,
    grant_types_supported: ["authorization_code", ...(additionalGrantTypes || [])],
    response_types_supported: ["code"],
    subject_types_supported: ["public"],
    id_token_signing_alg_values_supported: ["RS256"],
    scopes_supported: ["openid", "profile", "email"]
  };
}
```

--------------------------------

### Emit events in TypeScript

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix

Synchronously calls all listeners registered for a specific event, passing the supplied arguments to each.

```typescript
emit<T extends UserEvent>(
  event: T,
  ...args: Parameters<UserEventHandlerMap[T]>,
): boolean
```

--------------------------------

### otherPartySupportsMethod

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Checks whether the other party supports a given verification method.

```APIDOC
## otherPartySupportsMethod

### Description
Checks whether the other party supports a given verification method.

### Method
boolean

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- **method** (string) - The method to check

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (bool) - True if the other party supports the method

#### Response Example
N/A
```

--------------------------------

### deriveRecoveryKeyFromPassphrase

Source: https://matrix-org.github.io/matrix-js-sdk/functions/crypto-api

Derives a recovery key from a passphrase and salt using PBKDF2. This function implements the key derivation specification for Matrix recovery keys.

```APIDOC
## deriveRecoveryKeyFromPassphrase

### Description
Derives a recovery key from a passphrase and salt using PBKDF2. This function implements the key derivation specification for Matrix recovery keys as defined in the Matrix client-server API.

### Function Signature
```typescript
deriveRecoveryKeyFromPassphrase(
  passphrase: string,
  salt: string,
  iterations: number,
  numBits?: number
): Promise<Uint8Array<ArrayBufferLike>>
```

### Parameters

#### passphrase
- **Type:** `string`
- **Required:** Yes
- **Description:** The passphrase to derive the key from

#### salt
- **Type:** `string`
- **Required:** Yes
- **Description:** The salt to use in the derivation

#### iterations
- **Type:** `number`
- **Required:** Yes
- **Description:** The number of iterations to use in the derivation

#### numBits
- **Type:** `number`
- **Required:** No
- **Default:** `DEFAULT_BIT_SIZE`
- **Description:** The number of bits to derive

### Returns
- **Type:** `Promise<Uint8Array<ArrayBufferLike>>`
- **Description:** A promise that resolves to the derived recovery key as a Uint8Array

### See Also
- [Matrix Spec: Deriving Keys from Passphrases](https://spec.matrix.org/v1.11/client-server-api/#deriving-keys-from-passphrases)
```

--------------------------------

### listenerCount

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Returns the number of listeners listening to a specific event.

```APIDOC
## listenerCount

### Description
Returns the number of listeners listening to the event named `event`.

### Method
Number

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **number** (number) - The number of listeners

#### Response Example
N/A
```

--------------------------------

### ThumbnailInfo Interface Definition (TypeScript)

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/types._internal_

Defines the ThumbnailInfo interface used in the matrix-js-sdk. It includes optional properties for height, mimetype, size, and width of an image thumbnail.

```typescript
interface ThumbnailInfo {
  h?: number;
  mimetype?: string;
  size?: number;
  w?: number;
}
```

--------------------------------

### Define VideoInfo Interface in TypeScript

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/types

The VideoInfo interface is used to specify metadata for video files within Matrix room messages of message type m.video. It includes optional properties such as duration in milliseconds, display dimensions, mimetype, file size, and thumbnail details. Dependencies include EncryptedFile and ThumbnailInfo types, and it's hierarchical to AudioInfo and ImageInfo interfaces, with no specific inputs or outputs as it's a data structure.

```typescript
interface VideoInfo {
  duration?: number;
  h?: number;
  mimetype?: string;
  size?: number;
  thumbnail_file?: EncryptedFile;
  thumbnail_info?: ThumbnailInfo;
  thumbnail_url?: string;
  w?: number;
}
```

--------------------------------

### Add Key to Server-Side Secret Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Adds a key for encrypting secrets in the server-side storage. It accepts an algorithm, options specific to the algorithm, and an optional key ID. If no key ID is provided, a random one is generated. Returns details about the newly added key.

```typescript
addKey(
  algorithm: string,
  opts: AddSecretStorageKeyOpts,
  keyId?: string,
): Promise<SecretStorageKeyObject>
```

--------------------------------

### Querying and Removing Event Listeners (TypeScript)

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Provides methods to inspect and manage event listeners attached to an EventEmitter. `rawListeners` returns all listeners for a given event, `removeAllListeners` clears all or specific event listeners, and `removeListener` targets a specific listener function. These methods facilitate robust event handling and cleanup.

```typescript
/**
 * Returns a copy of the array of listeners for the event named `eventName`.
 * @param event The name of the event.
 * @returns An array of listener functions.
 */
rawListeners(event: EventEmitterEvents | Change): Function[];

/**
 * Removes all listeners, or those of the specified `event`.
 * It is bad practice to remove listeners added elsewhere in the code, particularly when the `EventEmitter` instance was created by some other component or module (e.g. sockets or file streams).
 * @param event Optional. The name of the event. If undefined, all listeners everywhere are removed.
 * @returns A reference to the `EventEmitter`, so that calls can be chained.
 */
removeAllListeners(event?: EventEmitterEvents | Change): this;

/**
 * Removes the specified `listener` from the listener array for the event named `event`.
 * @template T The event type.
 * @param event The name of the event.
 * @param listener The listener function to remove.
 * @returns A reference to the `EventEmitter`, so that calls can be chained.
 */
removeListener<T extends EventEmitterEvents | Change>(
  event: T,
  listener: Listener<Change, VerificationRequestEventHandlerMap, T>
): this;
```

--------------------------------

### Add event listener in TypeScript

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix

Adds an event listener for specified events. This is an alias for the 'on' method in the EventEmitter pattern.

```typescript
addListener<T extends EventEmitterEvents | UserEvent>(
  event: T,
  listener: Listener<UserEvent, UserEventHandlerMap, T>,
): this
```

--------------------------------

### off

Source: https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto-api

Removes a listener from the event listeners array (alias for removeListener).

```APIDOC
## off

### Description
Alias for removeListener

### Method
this

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **this** (EventEmitter) - A reference to the event emitter.

#### Response Example
N/A
```

--------------------------------

### Define RustBackupCryptoEventMap type alias in TypeScript

Source: https://matrix-org.github.io/matrix-js-sdk/types/crypto-api._internal_

This snippet declares a TypeScript type alias `RustBackupCryptoEventMap` that maps crypto backup related event names to their callback signatures. It specifies the expected argument types for each event, such as version strings, error codes, remaining session counts, and enabled flags. Used by the matrix-js-sdk to type‑check event listeners for crypto backup events.

```TypeScript
type RustBackupCryptoEventMap = {\n  \"crypto.keyBackupDecryptionKeyCached\": (version: string) => void;\n  \"crypto.keyBackupFailed\": (errCode: string) => void;\n  \"crypto.keyBackupSessionsRemaining\": (remaining: number) => void;\n  \"crypto.keyBackupStatus\": (enabled: boolean) => void;\n};
```

--------------------------------

### Check Key Match in Secret Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Verifies if a given key matches the expected key information stored on the server. This is useful for validating stored encryption keys.

```typescript
checkKey(
  key: Uint8Array,
  info: SecretStorageKeyDescriptionAesV1,
): Promise<boolean>
```

--------------------------------

### Check if Key Exists in Secret Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Determines if a key with the specified ID exists in the server-side storage. If no key ID is provided, it checks for the default key ID.

```typescript
hasKey(keyId?: string): Promise<boolean>
```

--------------------------------

### Store Secret in Server-Side Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Stores a secret on the server, potentially encrypted with specified keys. If no keys are provided, default encryption mechanisms may be used.

```typescript
store(
  name: keyof SecretStorageAccountDataEvents,
  secret: null | string,
  keys?: null | string[],
): Promise<void>
```

--------------------------------

### Set Default Key ID for Secret Storage

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Sets or unsets the default key ID for secret encryption. This key will be used for subsequent encryption operations unless otherwise specified.

```typescript
setDefaultKeyId(keyId: null | string): Promise<void>
```

--------------------------------

### Define VerifierEventHandlerMap Type Alias (TypeScript)

Source: https://matrix-org.github.io/matrix-js-sdk/types/crypto-api

This TypeScript code defines the `VerifierEventHandlerMap` type alias. It specifies the expected callback function signatures for handling different VerifierEvents, such as cancellation, displaying a QR code, or showing a SAS (Secure And Simple) pairing interface. This type is crucial for ensuring type safety when implementing event listeners for the verifier functionality.

```typescript
type VerifierEventHandlerMap = {
  cancel: (e: Error | MatrixEvent) => void;
  show_reciprocate_qr: (qr: ShowQrCodeCallbacks) => void;
  show_sas: (sas: ShowSasCallbacks) => void;
}
```

--------------------------------

### Check if Secret is Stored on Server

Source: https://matrix-org.github.io/matrix-js-sdk/classes/matrix.SecretStorage

Checks if a specific secret is present and encrypted on the server. Returns a map of key names to their encryption information, or null if the secret is not found or not encrypted with a trusted key.

```typescript
isStored(
  name: keyof SecretStorageAccountDataEvents,
): Promise<null | Record<string, SecretStorageKeyDescriptionAesV1>>
```
Tokens:
Raw