{"id":14483649,"url":"https://github.com/matrix-org/matrix-js-sdk","last_synced_at":"2025-05-14T08:02:12.461Z","repository":{"id":28168890,"uuid":"31670053","full_name":"matrix-org/matrix-js-sdk","owner":"matrix-org","description":"Matrix Client-Server SDK for JavaScript","archived":false,"fork":false,"pushed_at":"2025-04-17T18:30:30.000Z","size":53380,"stargazers_count":1758,"open_issues_count":256,"forks_count":616,"subscribers_count":54,"default_branch":"develop","last_synced_at":"2025-04-18T06:14:55.096Z","etag":null,"topics":["hacktoberfest","matrix","matrix-chat","matrix-sdk"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"patreon":"matrixdotorg","liberapay":"matrixdotorg"}},"created_at":"2015-03-04T17:28:51.000Z","updated_at":"2025-04-17T23:27:28.000Z","dependencies_parsed_at":"2023-10-16T19:34:15.189Z","dependency_job_id":"6924810d-1e18-4fa8-acf3-1a46bc5458d8","html_url":"https://github.com/matrix-org/matrix-js-sdk","commit_stats":{"total_commits":8063,"total_committers":178,"mean_commits":45.29775280898876,"dds":0.8424903881929803,"last_synced_commit":"a6fb7530cb3320cac9c3e521f76ef0db72cbce82"},"previous_names":[],"tags_count":476,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-js-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-js-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-js-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-js-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249529101,"owners_count":21286436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","matrix","matrix-chat","matrix-sdk"],"created_at":"2024-09-03T00:01:56.902Z","updated_at":"2025-04-22T13:40:00.280Z","avatar_url":"https://github.com/matrix-org.png","language":"TypeScript","readme":"[![npm](https://img.shields.io/npm/v/matrix-js-sdk)](https://www.npmjs.com/package/matrix-js-sdk)\n![Tests](https://github.com/matrix-org/matrix-js-sdk/actions/workflows/tests.yml/badge.svg)\n![Static Analysis](https://github.com/matrix-org/matrix-js-sdk/actions/workflows/static_analysis.yml/badge.svg)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=matrix-js-sdk\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=matrix-js-sdk)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=matrix-js-sdk\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=matrix-js-sdk)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=matrix-js-sdk\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=matrix-js-sdk)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=matrix-js-sdk\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=matrix-js-sdk)\n\n# Matrix JavaScript SDK\n\nThis is the [Matrix](https://matrix.org) Client-Server SDK for JavaScript and TypeScript. This SDK can be run in a\nbrowser or in Node.js.\n\n#### Minimum Matrix server version: v1.1\n\nThe Matrix specification is constantly evolving - while this SDK aims for maximum backwards compatibility, it only\nguarantees that a feature will be supported for at least 4 spec releases. For example, if a feature the js-sdk supports\nis removed in v1.4 then the feature is _eligible_ for removal from the SDK when v1.8 is released. This SDK has no\nguarantee on implementing all features of any particular spec release, currently. This can mean that the SDK will call\nendpoints from before Matrix 1.1, for example.\n\n# Quickstart\n\n\u003e [!IMPORTANT]\n\u003e Servers may require or use authenticated endpoints for media (images, files, avatars, etc). See the\n\u003e [Authenticated Media](#authenticated-media) section for information on how to enable support for this.\n\nUsing `yarn` instead of `npm` is recommended. Please see the Yarn [install guide](https://classic.yarnpkg.com/en/docs/install)\nif you do not have it already.\n\n`yarn add matrix-js-sdk`\n\n```javascript\nimport * as sdk from \"matrix-js-sdk\";\nconst client = sdk.createClient({ baseUrl: \"https://matrix.org\" });\nclient.publicRooms(function (err, data) {\n    console.log(\"Public Rooms: %s\", JSON.stringify(data));\n});\n```\n\nSee [below](#end-to-end-encryption-support) for how to enable end-to-end-encryption, or check\n[the Node.js terminal app](https://github.com/matrix-org/matrix-js-sdk/tree/develop/examples/node) for a more complex example.\n\nTo start the client:\n\n```javascript\nawait client.startClient({ initialSyncLimit: 10 });\n```\n\nYou can perform a call to `/sync` to get the current state of the client:\n\n```javascript\nclient.once(ClientEvent.sync, function (state, prevState, res) {\n    if (state === \"PREPARED\") {\n        console.log(\"prepared\");\n    } else {\n        console.log(state);\n        process.exit(1);\n    }\n});\n```\n\nTo send a message:\n\n```javascript\nconst content = {\n    body: \"message text\",\n    msgtype: \"m.text\",\n};\nclient.sendEvent(\"roomId\", \"m.room.message\", content, \"\", (err, res) =\u003e {\n    console.log(err);\n});\n```\n\nTo listen for message events:\n\n```javascript\nclient.on(RoomEvent.Timeline, function (event, room, toStartOfTimeline) {\n    if (event.getType() !== \"m.room.message\") {\n        return; // only use messages\n    }\n    console.log(event.event.content.body);\n});\n```\n\nBy default, the `matrix-js-sdk` client uses the `MemoryStore` to store events as they are received. For example to iterate through the currently stored timeline for a room:\n\n```javascript\nObject.keys(client.store.rooms).forEach((roomId) =\u003e {\n    client.getRoom(roomId).timeline.forEach((t) =\u003e {\n        console.log(t.event);\n    });\n});\n```\n\n## Authenticated media\n\nServers supporting [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916) (Matrix 1.11) will require clients, like\nyours, to include an `Authorization` header when `/download`ing or `/thumbnail`ing media. For NodeJS environments this\nmay be as easy as the following code snippet, though web browsers may need to use [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)\nto append the header when using the endpoints in `\u003cimg /\u003e` elements and similar.\n\n```javascript\nconst downloadUrl = client.mxcUrlToHttp(\n    /*mxcUrl=*/ \"mxc://example.org/abc123\", // the MXC URI to download/thumbnail, typically from an event or profile\n    /*width=*/ undefined, // part of the thumbnail API. Use as required.\n    /*height=*/ undefined, // part of the thumbnail API. Use as required.\n    /*resizeMethod=*/ undefined, // part of the thumbnail API. Use as required.\n    /*allowDirectLinks=*/ false, // should generally be left `false`.\n    /*allowRedirects=*/ true, // implied supported with authentication\n    /*useAuthentication=*/ true, // the flag we're after in this example\n);\nconst img = await fetch(downloadUrl, {\n    headers: {\n        Authorization: `Bearer ${client.getAccessToken()}`,\n    },\n});\n// Do something with `img`.\n```\n\n\u003e [!WARNING]\n\u003e In future the js-sdk will _only_ return authentication-required URLs, mandating population of the `Authorization` header.\n\n## What does this SDK do?\n\nThis SDK provides a full object model around the Matrix Client-Server API and emits\nevents for incoming data and state changes. Aside from wrapping the HTTP API, it:\n\n- Handles syncing (via `/sync`)\n- Handles the generation of \"friendly\" room and member names.\n- Handles historical `RoomMember` information (e.g. display names).\n- Manages room member state across multiple events (e.g. it handles typing, power\n  levels and membership changes).\n- Exposes high-level objects like `Rooms`, `RoomState`, `RoomMembers` and `Users`\n  which can be listened to for things like name changes, new messages, membership\n  changes, presence changes, and more.\n- Handle \"local echo\" of messages sent using the SDK. This means that messages\n  that have just been sent will appear in the timeline as 'sending', until it\n  completes. This is beneficial because it prevents there being a gap between\n  hitting the send button and having the \"remote echo\" arrive.\n- Mark messages which failed to send as not sent.\n- Automatically retry requests to send messages due to network errors.\n- Automatically retry requests to send messages due to rate limiting errors.\n- Handle queueing of messages.\n- Handles pagination.\n- Handle assigning push actions for events.\n- Handles room initial sync on accepting invites.\n- Handles WebRTC calling.\n\n# Usage\n\n## Supported platforms\n\n`matrix-js-sdk` can be used in either Node.js applications (ensure you have the latest LTS version of Node.js installed),\nor in browser applications, via a bundler such as Webpack or Vite.\n\nYou can also use the sdk with [Deno](https://deno.land/) (`import npm:matrix-js-sdk`) but its not officially supported.\n\n## Emitted events\n\nThe SDK raises notifications to the application using\n[`EventEmitter`s](https://nodejs.org/api/events.html#class-eventemitter). The `MatrixClient` itself\nimplements `EventEmitter`, as do many of the high-level abstractions such as `Room` and `RoomMember`.\n\n```javascript\n// Listen for low-level MatrixEvents\nclient.on(ClientEvent.Event, function (event) {\n    console.log(event.getType());\n});\n\n// Listen for typing changes\nclient.on(RoomMemberEvent.Typing, function (event, member) {\n    if (member.typing) {\n        console.log(member.name + \" is typing...\");\n    } else {\n        console.log(member.name + \" stopped typing.\");\n    }\n});\n\n// start the client to setup the connection to the server\nclient.startClient();\n```\n\n## Entry points\n\nAs well as the primary entry point (`matrix-js-sdk`), there are several other entry points which may be useful:\n\n| Entry point                    | Description                                                                                         |\n| ------------------------------ | --------------------------------------------------------------------------------------------------- |\n| `matrix-js-sdk`                | Primary entry point. High-level functionality, and lots of historical clutter in need of a cleanup. |\n| `matrix-js-sdk/lib/crypto-api` | Cryptography functionality.                                                                         |\n| `matrix-js-sdk/lib/types`      | Low-level types, reflecting data structures defined in the Matrix spec.                             |\n| `matrix-js-sdk/lib/testing`    | Test utilities, which may be useful in test code but should not be used in production code.         |\n| `matrix-js-sdk/lib/utils/*.js` | A set of modules exporting standalone functions (and their types).                                  |\n\n## Examples\n\nThis section provides some useful code snippets which demonstrate the\ncore functionality of the SDK. These examples assume the SDK is set up like this:\n\n```javascript\nimport * as sdk from \"matrix-js-sdk\";\nconst myUserId = \"@example:localhost\";\nconst myAccessToken = \"QGV4YW1wbGU6bG9jYWxob3N0.qPEvLuYfNBjxikiCjP\";\nconst matrixClient = sdk.createClient({\n    baseUrl: \"http://localhost:8008\",\n    accessToken: myAccessToken,\n    userId: myUserId,\n});\n```\n\n### Automatically join rooms when invited\n\n```javascript\nmatrixClient.on(RoomEvent.MyMembership, function (room, membership, prevMembership) {\n    if (membership === KnownMembership.Invite) {\n        matrixClient.joinRoom(room.roomId).then(function () {\n            console.log(\"Auto-joined %s\", room.roomId);\n        });\n    }\n});\n\nmatrixClient.startClient();\n```\n\n### Print out messages for all rooms\n\n```javascript\nmatrixClient.on(RoomEvent.Timeline, function (event, room, toStartOfTimeline) {\n    if (toStartOfTimeline) {\n        return; // don't print paginated results\n    }\n    if (event.getType() !== \"m.room.message\") {\n        return; // only print messages\n    }\n    console.log(\n        // the room name will update with m.room.name events automatically\n        \"(%s) %s :: %s\",\n        room.name,\n        event.getSender(),\n        event.getContent().body,\n    );\n});\n\nmatrixClient.startClient();\n```\n\nOutput:\n\n```\n  (My Room) @megan:localhost :: Hello world\n  (My Room) @megan:localhost :: how are you?\n  (My Room) @example:localhost :: I am good\n  (My Room) @example:localhost :: change the room name\n  (My New Room) @megan:localhost :: done\n```\n\n### Print out membership lists whenever they are changed\n\n```javascript\nmatrixClient.on(RoomStateEvent.Members, function (event, state, member) {\n    const room = matrixClient.getRoom(state.roomId);\n    if (!room) {\n        return;\n    }\n    const memberList = state.getMembers();\n    console.log(room.name);\n    console.log(Array(room.name.length + 1).join(\"=\")); // underline\n    for (var i = 0; i \u003c memberList.length; i++) {\n        console.log(\"(%s) %s\", memberList[i].membership, memberList[i].name);\n    }\n});\n\nmatrixClient.startClient();\n```\n\nOutput:\n\n```\n  My Room\n  =======\n  (join) @example:localhost\n  (leave) @alice:localhost\n  (join) Bob\n  (invite) @charlie:localhost\n```\n\n# API Reference\n\nA hosted reference can be found at\nhttp://matrix-org.github.io/matrix-js-sdk/index.html\n\nThis SDK uses [Typedoc](https://typedoc.org/guides/doccomments) doc comments. You can manually build and\nhost the API reference from the source files like this:\n\n```\n  $ yarn gendoc\n  $ cd docs\n  $ python -m http.server 8005\n```\n\nThen visit `http://localhost:8005` to see the API docs.\n\n# End-to-end encryption support\n\n`matrix-js-sdk`'s end-to-end encryption support is based on the [WebAssembly bindings](https://github.com/matrix-org/matrix-rust-sdk-crypto-wasm) of the Rust [matrix-sdk-crypto](https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-crypto) library.\n\n## Initialization\n\nTo initialize the end-to-end encryption support in the matrix client:\n\n```javascript\n// Create a new matrix client\nconst matrixClient = sdk.createClient({\n    baseUrl: \"http://localhost:8008\",\n    accessToken: myAccessToken,\n    userId: myUserId,\n});\n\n// Initialize to enable end-to-end encryption support.\nawait matrixClient.initRustCrypto();\n```\n\nNote that by default it will attempt to use the Indexed DB provided by the browser as a crypto store. If running outside the browser, you will need to pass [an options object](https://matrix-org.github.io/matrix-js-sdk/classes/matrix.MatrixClient.html#initrustcrypto) which includes `useIndexedDB: false`, to use an ephemeral in-memory store instead. Note that without a persistent store, you'll need to create a new device on the server side (with [`MatrixClient.loginRequest`](https://matrix-org.github.io/matrix-js-sdk/classes/matrix.MatrixClient.html#loginrequest)) each time your application starts.\n\nAfter calling `initRustCrypto`, you can obtain a reference to the [`CryptoApi`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html) interface, which is the main entry point for end-to-end encryption, by calling [`MatrixClient.getCrypto`](https://matrix-org.github.io/matrix-js-sdk/classes/matrix.MatrixClient.html#getCrypto).\n\n**WARNING**: the cryptography stack is not thread-safe. Having multiple `MatrixClient` instances connected to the same Indexed DB will cause data corruption and decryption failures. The application layer is responsible for ensuring that only one `MatrixClient` issue is instantiated at a time.\n\n## Secret storage\n\nYou should normally set up [secret storage](https://spec.matrix.org/v1.12/client-server-api/#secret-storage) before using the end-to-end encryption. To do this, call [`CryptoApi.bootstrapSecretStorage`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html#bootstrapSecretStorage).\n`bootstrapSecretStorage` can be called unconditionally: it will only set up the secret storage if it is not already set up (unless you use the `setupNewSecretStorage` parameter).\n\n```javascript\nconst matrixClient = sdk.createClient({\n    ...,\n    cryptoCallbacks: {\n        getSecretStorageKey: async (keys) =\u003e {\n            // This function should prompt the user to enter their secret storage key.\n            return mySecretStorageKeys;\n        },\n    },\n});\n\nmatrixClient.getCrypto().bootstrapSecretStorage({\n    // This function will be called if a new secret storage key (aka recovery key) is needed.\n    // You should prompt the user to save the key somewhere, because they will need it to unlock secret storage in future.\n    createSecretStorageKey: async () =\u003e {\n        return mySecretStorageKey;\n    },\n});\n```\n\nThe example above will create a new secret storage key if secret storage was not previously set up.\nThe secret storage data will be encrypted using the secret storage key returned in [`createSecretStorageKey`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CreateSecretStorageOpts.html#createSecretStorageKey).\n\nWe recommend that you prompt the user to re-enter this key when [`CryptoCallbacks.getSecretStorageKey`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoCallbacks.html#getSecretStorageKey) is called (when the secret storage access is needed).\n\n## Set up cross-signing\n\nTo set up cross-signing to verify devices and other users, call\n[`CryptoApi.bootstrapCrossSigning`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html#bootstrapCrossSigning):\n\n```javascript\nmatrixClient.getCrypto().bootstrapCrossSigning({\n    authUploadDeviceSigningKeys: async (makeRequest) =\u003e {\n        return makeRequest(authDict);\n    },\n});\n```\n\nThe [`authUploadDeviceSigningKeys`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.BootstrapCrossSigningOpts.html#authUploadDeviceSigningKeys)\ncallback is required in order to upload newly-generated public cross-signing keys to the server.\n\n## Key backup\n\nIf the user doesn't already have a [key backup](https://spec.matrix.org/v1.12/client-server-api/#server-side-key-backups) you should create one:\n\n```javascript\n// Check if we have a key backup.\n// If checkKeyBackupAndEnable returns null, there is no key backup.\nconst hasKeyBackup = (await matrixClient.getCrypto().checkKeyBackupAndEnable()) !== null;\n\n// Create the key backup\nawait matrixClient.getCrypto().resetKeyBackup();\n```\n\n## Verify a new device\n\nOnce the cross-signing is set up on one of your devices, you can verify another device with two methods:\n\n1. Use `CryptoApi.bootstrapCrossSigning`.\n\n    `bootstrapCrossSigning` will call the [CryptoCallbacks.getSecretStorageKey](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoCallbacks.html#getSecretStorageKey) callback. The device is verified with the private cross-signing keys fetched from the secret storage.\n\n2. Request an interactive verification against existing devices, by calling [CryptoApi.requestOwnUserVerification](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html#requestOwnUserVerification).\n\n## Migrating from the legacy crypto stack to Rust crypto\n\nIf your application previously used the legacy crypto stack, (i.e, it called `MatrixClient.initLegacyCrypto()`), you will\nneed to migrate existing devices to the Rust crypto stack.\n\nThis migration happens automatically when you call `initRustCrypto()` instead of `initLegacyCrypto()`,\nbut you need to provide the legacy [`cryptoStore`](https://matrix-org.github.io/matrix-js-sdk/interfaces/matrix.ICreateClientOpts.html#cryptoStore) and [`pickleKey`](https://matrix-org.github.io/matrix-js-sdk/interfaces/matrix.ICreateClientOpts.html#pickleKey) to [`createClient`](https://matrix-org.github.io/matrix-js-sdk/functions/matrix.createClient.html):\n\n```javascript\n// You should provide the legacy crypto store and the pickle key to the matrix client in order to migrate the data.\nconst matrixClient = sdk.createClient({\n    cryptoStore: myCryptoStore,\n    pickleKey: myPickleKey,\n    baseUrl: \"http://localhost:8008\",\n    accessToken: myAccessToken,\n    userId: myUserId,\n});\n\n// The migration will be done automatically when you call `initRustCrypto`.\nawait matrixClient.initRustCrypto();\n```\n\nTo follow the migration progress, you can listen to the [`CryptoEvent.LegacyCryptoStoreMigrationProgress`](https://matrix-org.github.io/matrix-js-sdk/enums/crypto_api.CryptoEvent.html#LegacyCryptoStoreMigrationProgress) event:\n\n```javascript\n// When progress === total === -1, the migration is finished.\nmatrixClient.on(CryptoEvent.LegacyCryptoStoreMigrationProgress, (progress, total) =\u003e {\n    ...\n});\n```\n\nThe Rust crypto stack is not supported in a lot of deprecated methods of [`MatrixClient`](https://matrix-org.github.io/matrix-js-sdk/classes/matrix.MatrixClient.html). If you use them, you should migrate to the [`CryptoApi`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html). Also, the legacy `MatrixClient.crypto` object is not available any more: you should use `MatrixClient.getCrypto()` instead.\n\n# Contributing\n\n_This section is for people who want to modify the SDK. If you just\nwant to use this SDK, skip this section._\n\nFirst, you need to pull in the right build tools:\n\n```\n $ yarn install\n```\n\n## Building\n\nTo build a browser version from scratch when developing:\n\n```\n $ yarn build\n```\n\nTo run tests (Jest):\n\n```\n $ yarn test\n```\n\nTo run linting:\n\n```\n $ yarn lint\n```\n","funding_links":["https://patreon.com/matrixdotorg","https://liberapay.com/matrixdotorg"],"categories":["TypeScript","Bot SDKs"],"sub_categories":["Javascript/Typescript"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-js-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-js-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-js-sdk/lists"}