Files API

cozy.client.files.create(data, options)

cozy.client.files.create(data, options) is used to upload a new file onto your cozy

It returns a promise for the document of the file created.

Warning: this API is not v2 compatible.

const created = await cozy.client.files.create(blob, {
    name: "filename",
    dirID: "123456",
})
const fileCreated = await cozy.client.files.create(fileInput.files[0], {
  dirID: "",
  checksum: "rL0Y20zC+Fzt72VPzMSk2A==",
  lastModifiedDate: new Date()
})

cozy.client.files.createDirectory(options)

cozy.client.files.createDirectory(options) is used to create a new directory.

It returns a promise for the document of the directory created.

const created = await cozy.client.files.createDirectory({
  name: "mydir",
  dirID: "123456",
  lastModifiedDate: new Date()
})

cozy.client.files.createDirectoryByPath(path)

cozy.client.files.createDirectoryByPath(path) is used to create one or more directories for a given path.

It returns a promise for the document of the last directory created.

const barDirectory = await cozy.client.files.createDirectoryByPath('/Foo/Bar')

cozy.client.files.updateById(id, data, options)

cozy.client.files.updateById(id, data, options) is used to update the content of an already existing file.

It returns a promise for the document of the file updated.

const updated = await cozy.client.files.updateById("654321", blob, {
  contentType: "text/plain",
  checksum: "rL0Y20zC+Fzt72VPzMSk2A==",
  lastModifiedDate: new Date(),
  ifMatch: "1-0e6d5b72"
})

cozy.client.files.updateAttributesById(id, attrs, options)

cozy.client.files.updateAttributesById(id, attrs, options) is used to update the attributes associated to a file or directory specified by its id.

It returns a promise for the document of the updated directory or file.

const updated = await cozy.client.files.updateAttributesById("12345", { tags: ["foo"] }, { ifMatch: "1-0e6d5b72" })

cozy.client.files.updateAttributesByPath(path, attrs, options)

cozy.client.files.updateAttributesByPath(path, attrs, options) is used to update the attributes associated to a file or directory specified by the given path.

It returns a promise for the document of the updated directory or file.

const updated = await cozy.client.files.updateAttributes("/foo/bar", { executable: true }, { ifMatch: "1-0e6d5b72" })

cozy.client.files.statById(id, offline, options)

cozy.client.files.statById(id, offline, options) is used to get the metadata of a file specified by its id.

It returns a promise for the information of the file or directory. In the case of a directory, it contains the list of files and sub-directories inside it. This list is limited to 30 items by default, but the options argument allows you to fetch more items.

By default, statById will fetch the metadata from the local database, if it is available. Set the second parameter to false to query the server.

Returned directory have a relations() method that allow to access to their content:

const dir = await cozy.client.files.statById("io.cozy.files.root-dir");
dir.relations('contents').forEach( (file) =>  )

cozy.client.files.statByPath(path)

cozy.client.files.statByPath(path) is used to get the metadata of a file specified by its path.

cozy.client.files.trashById(id, options)

cozy.client.files.trashById(id, options) is used to move the file or directory identified by the given id to trash.

It returns a promise for the document of the file or directory moved to trash.

const trashed = await cozy.client.files.trashById("1234567")

cozy.client.files.destroyById(id, options)

cozy.client.files.destroyById(id, options) is used to shred (destroy definitively) a file or directory identified by the given id.

The file must be in the trash folder first.

It returns a promise for completion

const trashed = await cozy.client.files.trashById("1234567")
await cozy.client.files.destroyById("1234567")

cozy.client.files.restoreById(id)

cozy.client.files.restoreById(id) is used to restore a file or directory identified by the given id. The file must be in the trash folder.

It returns a promise for the restored doc. (with updated parent)

const trashed = await cozy.client.files.trashById("1234567")
const restored = await cozy.client.files.restoreById("1234567")

cozy.client.files.listTrash()

cozy.client.files.listTrash() returns a promise for the list of all files in the trash.

const trashedFilesAndFolders = await cozy.client.files.listTrash()

cozy.client.files.clearTrash()

cozy.client.files.clearTrash() destroys definitively all trash content.

await cozy.client.files.clearTrash()

cozy.client.files.downloadById(id)

cozy.client.files.downloadById(id) is used to download a file identified by the given id. The file is downloaded through the browser fetch method, use this if you plan to use the file in javascript after.

It returns a promise of a fetch Response object. This response object can be used to extract the information in the wanted form.

const response = await cozy.client.files.downloadById("1234567")
const blob = await response.blob()
const text = await response.text()
const buff = await response.arrayBuffer()
response.pipe(fs.createWriteStream('/some/file'))

cozy.client.files.downloadByPath(path)

cozy.client.files.downloadByPath(path) is used to download a file identified by the given path. The file is downloaded through the browser fetch method, use this if you plan to use the file in javascript after.

It returns a promise of a fetch Response object. This response object can be used to extract the information in the wanted form.

const response = await cozy.client.files.downloadByPath("/foo/hello.txt")
const blob = await response.blob()
const text = await response.text()
const buff = await response.arrayBuffer()
response.pipe(fs.createWriteStream('/some/file'))

cozy.client.files.getDownloadLinkById(id)

cozy.client.files.getDownloadLinkById(id) is used to get a download link for the file identified by the given id.

It returns a promise for the download link. Download link are only valid for a short while (default 1 hour) You can use this link to start a browser download like this:

const href = await cozy.client.files.getDownloadLinkById("id424242")
const link = document.createElement('a')
link.href = href
link.download = fileName
document.body.appendChild(link) && link.click()

cozy.client.files.getDownloadLinkByPath(path)

cozy.client.files.getDownloadLinkByPath(path) is used to get a download link for the file identified by the given path.

It returns a promise for the download link. Download link are only valid for a short while (default 1 hour) You can use this link to start a browser download like this:

const href = await cozy.client.files.getDownloadLinkByPath("/foo/hello.txt")
const link = document.createElement('a')
link.href = href
link.download = fileName
document.body.appendChild(link) && link.click()

cozy.client.files.getArchiveLinkByPaths(paths, name)

cozy.client.files.getArchiveLinkByPaths(paths, name) is used to get a download link for a zip file containing all the files identified by the given paths.

It returns a promise for the download link. Download link are only valid for a short while (default 1 hour) You can use this link to start a browser download (see code in getDownloadLinkById)

const href = await cozy.client.files.getArchiveLinkByPaths([
  "/foo/hello.txt",
  "/bar/test.txt"
])
// href === "/files/archive/b1c127c25d99f0b37ac2c2a907f36069/files.zip"

const href = await cozy.client.files.getArchiveLinkByPaths(["/foo/hello.txt"], "secretproject")
// href === "/files/archive/bc2a901c127c25d99f0b37a36069c27f/secretproject.zip"

cozy.client.files.getArchiveLinkByIds(ids, name)

cozy.client.files.getArchiveLinkByIds(ids, name) is used to get a download link for a zip file containing all the files identified by the given ids.

It returns a promise for the download link. Download link are only valid for a short while (default 1 hour) You can use this link to start a browser download (see code in getDownloadLinkById)

const href = await cozy.client.files.getArchiveLinkByIds([
  "1234567",
  "9876543"
])
// href === "/files/archive/b1c127c25d99f0b37ac2c2a907f36069/files.zip"

const href = await cozy.client.files.getArchiveLinkByIds(["1592673"], "secretproject")
// href === "/files/archive/bc2a901c127c25d99f0b37a36069c27f/secretproject.zip"

cozy.client.files.getFilePath(file, folder)

cozy.client.files.getFilePath(file, folder) is a helper that generates the file path from root directory. It may be used to specify the path parameter for functions like cozy.client.files.downloadByPath, cozy.client.files.getDownloadLinkByPath or cozy.client.files.getArchiveLinkByPaths.

cozy.client.data.addReferencedFiles(doc, fileIds)

cozy.client.data.addReferencedFiles(doc, fileIds) binds the files to the document. (see cozy-stack documentation for more details)

cozy.client.data.removeReferencedFiles(doc, fileIds)

cozy.client.data.removeReferencedFiles(doc, fileIds) unbinds the files to the document. (see cozy-stack documentation for more details)

cozy.client.data.listReferencedFiles(doc)

cozy.client.data.listReferencedFiles(doc) list the files bound to the document. (see cozy-stack documentation for more details).

It returns a promise for a list of filesIds. Files must then be fetched separately.

cozy.client.data.fetchReferencedFiles(doc)

cozy.client.data.fetchReferencedFiles(doc) fetches the files bound to the document. (see cozy-stack documentation for more details).

It returns a promise for a list of files.

cozy.client.files.query(indexReference, query)

cozy.client.files.query(indexReference, query) find files using an index.

It returns a promise with a list of files matching the query. Results will be returned in the order defined for the index.

const results = await cozy.client.files.query(photosByDate, {
  "selector": {"class": "image"},
  "limit": 3,
  "skip": 1
})