{"id":20217954,"url":"https://github.com/matrix-org/matrix-files-sdk","last_synced_at":"2026-02-25T10:41:25.106Z","repository":{"id":38108279,"uuid":"448058149","full_name":"matrix-org/matrix-files-sdk","owner":"matrix-org","description":"JS/TS SDK for working with files and folders in Matrix","archived":false,"fork":false,"pushed_at":"2024-01-09T17:43:15.000Z","size":709,"stargazers_count":12,"open_issues_count":3,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-10T16:07:04.118Z","etag":null,"topics":[],"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":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-14T17:49:12.000Z","updated_at":"2025-01-27T00:25:22.000Z","dependencies_parsed_at":"2023-11-29T16:28:22.424Z","dependency_job_id":"082587e7-05e2-4d79-ad06-7c12d0b4f9c9","html_url":"https://github.com/matrix-org/matrix-files-sdk","commit_stats":{"total_commits":102,"total_committers":6,"mean_commits":17.0,"dds":0.6176470588235294,"last_synced_commit":"594def216ff17468f3be10042e2bc9d8e486b673"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":"matrix-org/.github","purl":"pkg:github/matrix-org/matrix-files-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-files-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-files-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-files-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-files-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-files-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-files-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262400872,"owners_count":23305390,"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":[],"created_at":"2024-11-14T06:36:36.458Z","updated_at":"2026-02-25T10:41:20.087Z","avatar_url":"https://github.com/matrix-org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Matrix Files SDK\n\nProvides a file system like abstraction around MSC3089 tree \u0026 branch spaces over [Matrix](https://matrix.org).\n\nTargets LTS versions of Node.js (currently \u003e=12) and browsers.\n\n## Installation\n\n```sh\nnpm install matrix-files-sdk\n```\n\nor for `yarn`:\n\n```sh\nyarn add matrix-files-sdk\n```\n\nYou must install `matrix-js-sdk` in your project as well.\n\n## Usage\n\nFor a more complete example of the SDK in use see [vector-im/files-sdk-demo](https://github.com/vector-im/files-sdk-demo).\n\n![Class Diagram](./docs/class-diagram.svg)\n\n### Initialisation\n\nThe SDK acts as a wrapper around `matrix-js-sdk` so you need to create an instance of `MatrixClient` first.\n\nThe main entry point is via the `MatrixFiles` class:\n\n```ts\nimport { createClient } from 'matrix-js-sdk';\nimport { MatrixFiles } from 'matrix-files-sdk';\n\nconst client = createClient({});\n\nconst files = new MatrixFiles(client);\n\n// do initial sync of required state:\nawait files.sync();\n```\n\n### Navigating the hierarchy\n\nYou can use the `IFolder.getChildren()` function to discovery entries in the hierarchy:\n\n```ts\nimport { IEntry } from 'matrix-files-sdk';\n\n...\n\nconst entries: IEntry[] = await folder.getChildren();\n\nfor (const e: entries) {\n  console.log(`${e.name} =\u003e ${e.isFolder ? 'folder' : 'file' }`);\n}\n\n```\n\nEntries are identified by an ID (`IEntry.id` of type `MatrixFilesID`) which are standard Matrix room and event IDs.\n\nThe ID can be used on an `IFolder` with `getChildById()` and `getDescendantById()`.\n\nFurthermore the `MatrixFiles.resolvePath()` function can be used to resolve an entry by name from the root of the hierarchy:\n\n```ts\nconst entry = await files.resolvePath(['My workspace', 'documents', 'file.pdf']);\n```\n\n### Common operations on entries\n\nDeleting (redacting) a file:\n\n```ts\nawait anEntry.delete();\n```\n\nRenaming on a folder:\n\n```ts\nawait aFolder.rename('new name');\n```\n\nand a file:\n\n```ts\nawait aFile.rename('new name.pdf');\n```\n\nMoving within the hierarchy:\n\n```ts\nconst file = await files.resolvePath(['old folder', 'file.pdf']);\n\nconst newFolderId = await files.addFolder('new folder');\nconst newFolder = await files.getDescendantById(newFolderId);\n\nawait file.moveTo(newFolder, 'file.pdf');\n```\n\n### Observing changes\n\nFiles, folders and `MatrixFiles` all implement the `EventEmitter` pattern:\n\n```ts\nconst file = await files.resolvePath(['old folder', 'file.pdf']);\n\nfile.on('modified', () =\u003e { console.log('file modified'); });\n```\n\n### Logging\n\nLogging is available via  [log4js](https://www.npmjs.com/package/log4js) under the `MatrixFilesSDK` log category.\n\nFor example, to enable trace level logging from the SDK:\n\n```ts\nimport log4js from 'log4js';\n\nlog4js.configure({\n  appenders: {\n    console: {\n      type: 'console',\n      layout: { type: 'coloured' },\n    },\n  },\n  categories: {\n    default: {\n      appenders: ['console'],\n      level: 'debug',\n    },\n    MatrixFilesSDK: {\n      appenders: ['console'],\n      level: 'trace',\n    },\n  },\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-files-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-files-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-files-sdk/lists"}