

Cozy Stack Client API

Classes¶

AppCollection

Extends DocumentCollection API along with specific methods for io.cozy.apps.

AppsRegistryCollection

Extends DocumentCollection API along with specific methods for io.cozy.apps_registry.

Collection

Utility class to abstract an regroup identical methods and logics for specific collections.

CozyStackClient

Main API against the cozy-stack server.

DocumentCollection

Abstracts a collection of documents of the same doctype, providing CRUD methods and other helpers.

FileCollection

Implements DocumentCollection API along with specific methods for io.cozy.files.

Files are a special type of documents and are handled differently by the stack: special routes are to be used, and there is a notion of referenced files, aka files associated to a specific document

NotesCollection

Implements DocumentCollection API to interact with the /notes endpoint of the stack

OAuthClient

Specialized CozyStackClient for mobile, implementing stack registration through OAuth.

OAuthClientsCollection

Implements DocumentCollection API to interact with the /settings/clients endpoint of the stack

PermissionCollection

Implements DocumentCollection API along with specific methods for io.cozy.permissions.

PromiseCache

Caches promises while they are pending Serves to dedupe equal queries requested at the same time

SettingsCollection

Implements DocumentCollection API to interact with the /settings endpoint of the stack

SharingCollection

Implements the DocumentCollection API along with specific methods for io.cozy.sharings.

TriggerCollection

Implements DocumentCollection API along with specific methods for io.cozy.triggers.

Constants¶

dontThrowNotFoundError ⇒ object

Handler for error response which return a empty value for "not found" error

isIndexNotFoundError ⇒ Array | null

Helper to identify an index not found error

isIndexConflictError ⇒ Array | null

Helper to identify an index conflict

isIndexNotUsedWarning ⇒ Array | null

Helper to identify a not used index

isNoUsableIndexError ⇒ Array | null

Helper to identify a no usable index error

isTimeoutError ⇒ Array | null

Helper to identify timeout error See cozy-stack's timeout value for couchdb request: https://github.com/cozy/cozy-stack/blob/669cd694132388ef6b7d1a58cf3d1b5dfb52896a/pkg/config/config/config.go#L963

isDocumentUpdateConflict ⇒ Array | null

Helper to identify a document conflict

isFile ⇒ boolean

Returns true when parameter has type directory, file or has _type io.cozy.files

isDirectory ⇒ boolean

Returns true when parameters has type directory

getIllegalCharacters ⇒ string

Get the list of illegal characters in the file name

makeKeyFromPartialFilter ⇒ string

Process a partial filter to generate a string key

/!\ Warning: this method is similar to cozy-pouch-link mango.makeKeyFromPartialFilter() If you edit this method, please check if the change is also needed in mango file

getIndexNameFromFields ⇒ string

Name an index, based on its indexed fields and partial filter.

It follows this naming convention: by_{indexed_field1}_and_{indexed_field2}_filter_({partial_filter.key1}_{partial_filter.value1})_and_({partial_filter.key2}_{partial_filter.value2})

/!\ Warning: this method is similar to cozy-pouch-link mango.getIndexNameFromFields() If you edit this method, please check if the change is also needed in mango file

transformSort ⇒ MangoSort

Transform sort into Array

getIndexFields ⇒ Array

Compute fields that should be indexed for a mango query to work

isMatchingIndex ⇒ boolean

Check if an index is matching the given fields

makeOperatorsExplicit ⇒ object

Transform a query to make all operators explicit

getPermissionsFor ⇒ object

Build a permission set

normalizeSettings ⇒ object

Normalizing a document for SettingsCollection context

getSharingRules ⇒ Array.<Rule>

Rules determine the behavior of the sharing when changes are made to the shared document See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing

forceDownload

Force a download from the given href

encodePath ⇒ string

Encode a path for use in a URL by encoding special characters but keeping slashes

Functions¶

getAccessToken() ⇒ string: Get the access token string
getAccessToken() ⇒ string: Get the app token string
getIconURL(): Get Icon URL using blob mechanism if OAuth connected or using preloaded url when blob not needed
handleNorOperator(conditions) ⇒ Array: Handle the $nor operator in a query CouchDB transforms $nor into $and with $ne operators
sortObjectByKey(a, b) ⇒ number: Compares two objects based on their first key to determine their order.
garbageCollect(): Delete outdated results from cache
memoize(): Memoize with maxDuration and custom key
normalizeDoctypeJsonApi(doctype) ⇒ function: Normalizes a document in JSON API format for a specific doctype
getSharingRulesForPhotosAlbum(document, sharingType) ⇒ Array.<Rule>: Compute the rules that define how to share a Photo Album. See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing
getSharingPolicyForReferencedFiles(sharingType) ⇒ SharingPolicy: Compute the sharing policy for a ReferencedFile based on its sharing type
getSharingPolicyForAlbum(sharingType) ⇒ Array.<Rule>: Compute the sharing policy for an Album based on its sharing type
getSharingRulesForFile(document, sharingType) ⇒ Array.<Rule>: Compute the rules that define how to share a File. See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing
getSharingPolicyForFile(document, sharingType) ⇒ SharingPolicy: Compute the sharing policy for a File based on its sharing type
getSharingRulesForOrganizations(document) ⇒ Array.<Rule>: Compute the rules that define how to share an Organization. See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing
toRelationshipItem(item) ⇒ RelationshipItem: Compute the RelationshipItem that can be referenced as a sharing recipient
getCozyURL(): Get a uniform formatted URL and SSL information according to a provided URL
joinPath(start, end) ⇒ string: Join two paths together ensuring there is only one slash between them

Typedefs¶

FetchChangesReturnValue ⇒ Promise.<FetchChangesReturnValue>

Use Couch _changes API Deleted and design docs are filtered by default, thus documents are retrieved in the response (include_docs is set to true in the parameters of _changes).

You should use fetchChangesRaw to have low level control on _changes parameters.

IOCozyFolder : object

Folder

SpecificFileAttributesForKonnector : object

Specific file attributes for creation for konnector

CouchDBViewCursor : Array.<string> | string

Cursor used for Mango queries pagination

DirectoryAttributes : object

Attributes used for directory creation

FileAttributes : object

Attributes used for file creation

FileDocument : object

Document representing a io.cozy.files

Stream : object

Stream is not defined in a browser, but is on NodeJS environment

OAuthClient : object

Document representing a io.cozy.oauth.clients

ArchivePages : object

Attributes used for create archive link by ids

FetchChangesReturnValue ⇒ FetchChangesReturnValue

Use cozy-stack's _changes API for io.cozy.files Design docs are filtered by default, thus documents are retrieved in the response (includeDocs is set to true in the parameters of _changes). Deleted and trashed documents can be filtered on demand and files' paths can be requested as well.

Since deleted and trashed documents are skipped by cozy-stack rather than CouchDB, when either option is set to true, the response can contain less documents than the defined limit. Thus one should rely solely on the pending result attribute to determine if more documents can be fetched or not.

You should use fetchChangesRaw to call CouchDB's _changes API.

JobDocument : object

Document representing a io.cozy.jobs

MangoPartialFilter : Object

MangoSelector : object

MangoSort : Array.<object>

MangoQueryOptions : object

DesignDoc : object

Attributes representing a design doc

SessionCode : string

SessionCodeRes

AccessTokenRes

TwoFactorNeededRes

Permission ⇒ Permission

async getOwnPermissions - deprecated: please use fetchOwnPermissions instead

Permission ⇒ Permission

async fetchOwnPermissions - Fetches permissions

Rule : object

A sharing rule

Recipient : object

An io.cozy.contact

Sharing : object

An io.cozy.sharings document

SharingPolicy : object

Define the add/update/remove policies for a sharing

SharingType : undefined | 'one-way' | 'two-way'

Define how a document is synced between sharing's owner and receivers.

RelationshipItem : object

Define a recipient that can be used as target of a sharing

CozyStackClient : object

AppCollection¶

Extends DocumentCollection API along with specific methods for io.cozy.apps.

Kind: global class

appCollection.all() ⇒ `Object`¶

Lists all apps, without filters.

The returned documents are not paginated by the stack.

Kind: instance method of AppCollection
Returns: Object - The JSON API conformant response.
Throws:

FetchError

AppsRegistryCollection¶

Extends DocumentCollection API along with specific methods for io.cozy.apps_registry.

Kind: global class

appsRegistryCollection.get(slug) ⇒ `Promise.<{data: object}>`¶

Fetches an app from the registry.

Kind: instance method of AppsRegistryCollection
Returns: Promise.<{data: object}> - JsonAPI response containing normalized document as data attribute
Throws:

FetchError

Param	Type	Description
slug	`string`	Slug of the app

Collection¶

Utility class to abstract an regroup identical methods and logics for specific collections.

Kind: global class

Collection.get(stackClient, endpoint, options) ⇒ `Promise.<object>`¶

Utility method aimed to return only one document.

Kind: static method of Collection
Returns: Promise.<object> - JsonAPI response containing normalized document as data attribute

Param	Type	Default	Description
stackClient	`CozyStackClient`		CozyStackClient
endpoint	`string`		Stack endpoint
options	`object`		Options of the collection
options.normalize	`function`		Callback to normalize response data (default `data => data`)
[options.method]	`string`	`"GET"`	HTTP method

CozyStackClient¶

Main API against the cozy-stack server.

Kind: global class

CozyStackClient
- .collection(doctype) ⇒ DocumentCollection
- .fetch(method, path, [body], [opts]) ⇒ object
- .refreshToken() ⇒ Promise
- .fetchJSON(method, path, body, options) ⇒ object
- .setToken(token)
- .getAccessToken() ⇒ string

cozyStackClient.collection(doctype) ⇒ `DocumentCollection`¶

Creates a DocumentCollection instance.

Kind: instance method of CozyStackClient

Param	Type	Description
doctype	`string`	The collection doctype.

cozyStackClient.fetch(method, path, [body], [opts]) ⇒ `object`¶

Fetches an endpoint in an authorized way.

Kind: instance method of CozyStackClient
Throws:

FetchError

Param	Type	Description
method	`string`	The HTTP method.
path	`string`	The URI.
[body]	`object`	The payload.
[opts]	`object`	Options for fetch

cozyStackClient.refreshToken() ⇒ `Promise`¶

Retrieves a new app token by refreshing the currently used token.

Kind: instance method of CozyStackClient
Returns: Promise - A promise that resolves with a new AccessToken object
Throws:

Error The client should already have an access token to use this function
Error The client couldn’t fetch a new token

cozyStackClient.fetchJSON(method, path, body, options) ⇒ `object`¶

Fetches JSON in an authorized way.

Kind: instance method of CozyStackClient
Throws:

FetchError

Param	Type	Description
method	`string`	The HTTP method.
path	`string`	The URI.
body	`object`	The payload.
options	`object`	Options

cozyStackClient.setToken(token)¶

Change or set the API token

Kind: instance method of CozyStackClient

Param	Type	Description
token	`string` \| `AppToken` \| `AccessToken`	Stack API token

cozyStackClient.getAccessToken() ⇒ `string`¶

Get the access token string, being an oauth token or an app token

Kind: instance method of CozyStackClient
Returns: string - token

DocumentCollection¶

Abstracts a collection of documents of the same doctype, providing CRUD methods and other helpers.

Kind: global class

DocumentCollection
- instance
  - .all(options) ⇒ Promise.<{data, meta, skip, bookmark, next}>
  - .fetchDocumentsWithMango(path, selector, options)
  - .findWithMango(path, selector, options) ⇒ Promise.<object>
  - .find(selector, options) ⇒ Promise.<{data, skip, bookmark, next, execution_stats}>
  - .findAll(selector, options) ⇒ Promise.<Array.<{data}>>
  - .get(id) ⇒ Promise.<object>
  - .getAll()
  - .create(doc)
  - .update(document)
  - .destroy(doc)
  - .updateAll(rawDocs)
  - .destroyAll(docs)
  - .toMangoOptions(selector, options) ⇒ MangoQueryOptions
  - .createIndex(fields, indexOption) ⇒ Promise.<{id, fields}>
  - .fetchAllMangoIndexes() ⇒ Promise.<Array.<DesignDoc>>
  - .destroyIndex(index) ⇒ Promise.<object>
  - .copyIndex(existingIndex, newIndexName) ⇒ Promise.<DesignDoc>
  - .fetchChangesRaw(couchOptions)
- static
  - .normalizeDoctype(doctype) ⇒ function

documentCollection.all(options) ⇒ `Promise.<{data, meta, skip, bookmark, next}>`¶

Lists all documents of the collection, without filters.

The returned documents are paginated by the stack.

Kind: instance method of DocumentCollection
Returns: Promise.<{data, meta, skip, bookmark, next}> - The JSON API conformant response.
Throws:

FetchError

Param	Type	Default	Description
options	`object`		The fetch options: pagination & fetch of specific docs.
[options.limit]	`number` \| `null`	`100`	Pagination limit
[options.skip]	`number`	`0`	Pagination Skip
[options.bookmark]	`string`		Pagination bookmark
[options.keys]	`Array.<string>`		Keys to query

documentCollection.fetchDocumentsWithMango(path, selector, options)¶

Fetch Documents with Mango

Kind: instance method of DocumentCollection

Param	Type	Description
path	`string`	path to fetch
selector	`MangoSelector`	selector
options	`MangoQueryOptions`	request options

documentCollection.findWithMango(path, selector, options) ⇒ `Promise.<object>`¶

Find documents with the mango selector and create index if missing.

We adopt an optimistic approach for index creation: we run the query first, and only if an index missing error is returned, the index is created and the query run again.

Kind: instance method of DocumentCollection
Returns: Promise.<object> - - The find response
Access: protected

Param	Type	Description
path	`string`	The route path
selector	`MangoSelector`	The mango selector
options	`MangoQueryOptions`	The find options

documentCollection.find(selector, options) ⇒ `Promise.<{data, skip, bookmark, next, execution_stats}>`¶

Returns a filtered list of documents using a Mango selector.

The returned documents are paginated by the stack.

Kind: instance method of DocumentCollection
Returns: Promise.<{data, skip, bookmark, next, execution_stats}> - The JSON API conformant response.
Throws:

FetchError

Param	Type	Description
selector	`MangoSelector`	The Mango selector.
options	`MangoQueryOptions`	MangoQueryOptions

documentCollection.findAll(selector, options) ⇒ `Promise.<Array.<{data}>>`¶

Returns a filtered list with all documents using a Mango selector, automatically fetching more documents if the total of documents is superior to the pagination limit. Can result in a lot of network requests.

The returned documents are paginated by the stack.

Kind: instance method of DocumentCollection
Returns: Promise.<Array.<{data}>> - Documents fetched
Throws:

FetchError

Param	Type	Description
selector	`MangoSelector`	The Mango selector.
options	`MangoQueryOptions`	MangoQueryOptions

documentCollection.get(id) ⇒ `Promise.<object>`¶

Get a document by id

Kind: instance method of DocumentCollection
Returns: Promise.<object> - JsonAPI response containing normalized document as data attribute

Param	Type	Description
id	`string`	The document id.

documentCollection.getAll()¶

Get many documents by id

Kind: instance method of DocumentCollection

documentCollection.create(doc)¶

Creates a document

Kind: instance method of DocumentCollection

Param	Type	Description
doc	`object`	Document to create. Optional: you can force the id with the _id attribute

documentCollection.update(document)¶

Updates a document

Kind: instance method of DocumentCollection

Param	Type	Description
document	`object`	Document to update. Do not forget the _id attribute

documentCollection.destroy(doc)¶

Destroys a document

Kind: instance method of DocumentCollection

Param	Type	Description
doc	`object`	Document to destroy. Do not forget _id and _rev attributes

documentCollection.updateAll(rawDocs)¶

Updates several documents in one batch

Kind: instance method of DocumentCollection

Param	Type	Description
rawDocs	`Array.<Document>`	Documents to be updated

documentCollection.destroyAll(docs)¶

Deletes several documents in one batch

Kind: instance method of DocumentCollection

Param	Type	Description
docs	`Array.<Document>`	Documents to delete

documentCollection.toMangoOptions(selector, options) ⇒ `MangoQueryOptions`¶

Returns Mango Options from Selector and Options

Kind: instance method of DocumentCollection
Returns: MangoQueryOptions - Mango options

Param	Type	Description
selector	`MangoSelector`	Mango selector
options	`MangoQueryOptions`	Mango Options

documentCollection.createIndex(fields, indexOption) ⇒ `Promise.<{id, fields}>`¶

Kind: instance method of DocumentCollection

Param	Type	Description
fields	`Array`	Fields to index
indexOption	`object`	Options for the index
[indexOption.partialFilter]	`MangoPartialFilter`	partialFilter
[indexOption.indexName]	`string`	indexName

documentCollection.fetchAllMangoIndexes() ⇒ `Promise.<Array.<DesignDoc>>`¶

Retrieve all design docs of mango indexes

Kind: instance method of DocumentCollection
Returns: Promise.<Array.<DesignDoc>> - The design docs

documentCollection.destroyIndex(index) ⇒ `Promise.<object>`¶

Delete the specified design doc

Kind: instance method of DocumentCollection
Returns: Promise.<object> - The delete response

Param	Type	Description
index	`DesignDoc`	The design doc to remove

documentCollection.copyIndex(existingIndex, newIndexName) ⇒ `Promise.<DesignDoc>`¶

Copy an existing design doc.

This is useful to create a new design doc without having to recompute the existing index.

Kind: instance method of DocumentCollection
Returns: Promise.<DesignDoc> - The copy response

Param	Type	Description
existingIndex	`DesignDoc`	The design doc to copy
newIndexName	`string`	The name of the copy

documentCollection.fetchChangesRaw(couchOptions)¶

Calls _changes route from CouchDB No further treatment is done contrary to fetchchanges

Kind: instance method of DocumentCollection
See: https://docs.couchdb.org/en/stable/api/database/changes.html

Param	Type	Description
couchOptions	`object`	Couch options for changes https://kutt.it/5r7MNQ
[couchOptions.since]	`string`	Bookmark telling CouchDB from which point in time should changes be returned
[couchOptions.doc_ids]	`Array.<string>`	Only return changes for a subset of documents
[couchOptions.includeDocs]	`boolean`	Includes full documents as part of results
[couchOptions.filter]	`string`	Filter

DocumentCollection.normalizeDoctype(doctype) ⇒ `function`¶

Provides a callback for Collection.get

Kind: static method of DocumentCollection
Returns: function - (data, response) => normalizedDocument using normalizeDoc

Param	Type	Description
doctype	`string`	Document doctype

FileCollection¶

Implements DocumentCollection API along with specific methods for io.cozy.files.

Files are a special type of documents and are handled differently by the stack: special routes are to be used, and there is a notion of referenced files, aka files associated to a specific document

Kind: global class

FileCollection
- .forceFileDownload
- .get(id) ⇒ Object
- .getAll(ids) ⇒ Promise.<{data, meta, execution_stats}>
- .find(selector, options) ⇒ Promise.<{data, meta, skip, next, bookmark, execution_stats}>
- .findReferencedBy(document, options) ⇒ Promise.<{data, included, meta, skip, next}>
- .addReferencedBy(document, documents) ⇒ Promise.<{data, meta}>
- .removeReferencedBy(document, documents) ⇒ Promise.<{data, meta}>
- .addReferencesTo(document, documents)
- .removeReferencesTo(document, documents)
- .destroy(file) ⇒ Promise
- .emptyTrash()
- .restore(id) ⇒ Promise
- .copy(id, [name], [dirId]) ⇒ Promise.<object>
- .deleteFilePermanently(id) ⇒ Promise.<object>
- .upload(data, dirPath) ⇒ Promise.<object>
- .create(attributes)
- .updateFile(data, params) ⇒ object
- .download(file, versionId, filename)
- .fetchFileContentById(id)
- .getBeautifulSize(file, decimal)
- .downloadArchive(fileIds, [notSecureFilename], [options])
- ~~.getArchiveLinkByIds()~~
- .createArchiveLinkByIds(params) ⇒ Promise.<string>
- .isChildOf(child, parent) ⇒ boolean
- .statById(id, options) ⇒ object
- .createDirectoryByPath(path) ⇒ object
- .createFileMetadata(attributes) ⇒ Promise.<object>
- .updateMetadataAttribute(id, metadata) ⇒ Promise.<object>
- .getFileTypeFromName(name) ⇒ string
- .doUpload(dataArg, path, options, method)
- .findNotSynchronizedDirectories(oauthClient, options) ⇒ Array.<(object|IOCozyFolder)>
- .addNotSynchronizedDirectories(oauthClient, directories)
- .removeNotSynchronizedDirectories(oauthClient, directories)

fileCollection.forceFileDownload¶

Force a file download from the given href

Kind: instance property of FileCollection

Param	Type	Description
href	`string`	The link to download
filename	`string`	The file name to download

fileCollection.get(id) ⇒ `Object`¶

Fetches the file’s data

Kind: instance method of FileCollection
Returns: Object - Information about the file or folder and it’s descendents

Param	Type	Description
id	`string`	File id

fileCollection.getAll(ids) ⇒ `Promise.<{data, meta, execution_stats}>`¶

Get all files by their ids

Kind: instance method of FileCollection
Returns: Promise.<{data, meta, execution_stats}> - JSON API response

Param	Type	Description
ids	`Array.<string>`	files ids

fileCollection.find(selector, options) ⇒ `Promise.<{data, meta, skip, next, bookmark, execution_stats}>`¶

Returns a filtered list of documents using a Mango selector.

The returned documents are paginated by the stack.

Kind: instance method of FileCollection
Returns: Promise.<{data, meta, skip, next, bookmark, execution_stats}> - The JSON API conformant response.
Throws:

FetchError

Param	Type	Description
selector	`object`	The Mango selector.
options	`MangoQueryOptions`	The query options

fileCollection.findReferencedBy(document, options) ⇒ `Promise.<{data, included, meta, skip, next}>`¶

async findReferencedBy - Returns the list of files referenced by a document — see https://docs.cozy.io/en/cozy-stack/references-docs-in-vfs/

Kind: instance method of FileCollection
Returns: Promise.<{data, included, meta, skip, next}> - The JSON API conformant response.

Param	Type	Description
document	`object`	A JSON representing a document, with at least a `_type` and `_id` field.
options	`object`	Additional options
[options.skip]	`number` \| `null`	For skip-based pagination, the number of referenced files to skip.
[options.limit]	`number` \| `null`	For pagination, the number of results to return.
[options.cursor]	`CouchDBViewCursor` \| `null`	For cursor-based pagination, the index cursor.

fileCollection.addReferencedBy(document, documents) ⇒ `Promise.<{data, meta}>`¶

Add referenced_by documents to a file — see https://docs.cozy.io/en/cozy-stack/references-docs-in-vfs/#post-filesfile-idrelationshipsreferenced_by

For example, to have an album referenced by a file:

addReferencedBy({_id: 123, _type: "io.cozy.files", name: "cozy.jpg"}, [{_id: 456, _type: "io.cozy.photos.albums", name: "Happy Cloud"}])

Kind: instance method of FileCollection
Returns: Promise.<{data, meta}> - The JSON API conformant response.

Param	Type	Description
document	`FileDocument`	A JSON representing the file
documents	`Array`	An array of JSON documents having a `_type` and `_id` field.

fileCollection.removeReferencedBy(document, documents) ⇒ `Promise.<{data, meta}>`¶

Remove referenced_by documents from a file — see https://docs.cozy.io/en/cozy-stack/references-docs-in-vfs/#delete-filesfile-idrelationshipsreferenced_by

For example, to remove an album reference from a file:

 removeReferencedBy({_id: 123, _type: "io.cozy.files", name: "cozy.jpg"}, [{_id: 456, _type: "io.cozy.photos.albums", name: "Happy Cloud"}])

Kind: instance method of FileCollection
Returns: Promise.<{data, meta}> - The JSON API conformant response.

Param	Type	Description
document	`object`	A JSON representing the file
documents	`Array`	An array of JSON documents having a `_type` and `_id` field.

fileCollection.addReferencesTo(document, documents)¶

Add files references to a document — see https://docs.cozy.io/en/cozy-stack/references-docs-in-vfs/#post-datatypedoc-idrelationshipsreferences

For example, to add a photo to an album:

 addReferencesTo({_id: 456, _type: "io.cozy.photos.albums", name: "Happy Cloud"}, [{_id: 123, _type: "io.cozy.files", name: "cozy.jpg"}])

Kind: instance method of FileCollection

Param	Type	Description
document	`object`	A JSON representing a document, with at least a `_type` and `_id` field.
documents	`Array`	An array of JSON files having an `_id` field. Returns 204 No Content

fileCollection.removeReferencesTo(document, documents)¶

Remove files references to a document — see https://docs.cozy.io/en/cozy-stack/references-docs-in-vfs/#delete-datatypedoc-idrelationshipsreferences

For example, to remove a photo from an album:

 removeReferencesTo({_id: 456, _type: "io.cozy.photos.albums", name: "Happy Cloud"}, [{_id: 123, _type: "io.cozy.files", name: "cozy.jpg"}])

Kind: instance method of FileCollection

Param	Type	Description
document	`object`	A JSON representing a document, with at least a `_type` and `_id` field.
documents	`Array`	An array of JSON files having an `_id` field. Returns 204 No Content

fileCollection.destroy(file) ⇒ `Promise`¶

Sends file to trash and removes references to it

Kind: instance method of FileCollection
Returns: Promise - - Resolves when references have been removed and file has been sent to trash

Param	Type	Description
file	`FileDocument`	File that will be sent to trash

fileCollection.emptyTrash()¶

Empty the Trash

Kind: instance method of FileCollection

fileCollection.restore(id) ⇒ `Promise`¶

Restores a trashed file.

Kind: instance method of FileCollection
Returns: Promise - - A promise that returns the restored file if resolved.
Throws:

FetchError

Param	Type	Description
id	`string`	The file’s id

fileCollection.copy(id, [name], [dirId]) ⇒ `Promise.<object>`¶

Copy a file.

Kind: instance method of FileCollection
Returns: Promise.<object> - - A promise that returns the copied file if resolved.
Throws:

FetchError

Param	Type	Description
id	`string`	The file’s id
[name]	`string`	The file copy name
[dirId]	`string`	The destination directory id

fileCollection.deleteFilePermanently(id) ⇒ `Promise.<object>`¶

async deleteFilePermanently - Definitely delete a file

Kind: instance method of FileCollection
Returns: Promise.<object> - The deleted file object

Param	Type	Description
id	`string`	The id of the file to delete

fileCollection.upload(data, dirPath) ⇒ `Promise.<object>`¶

Kind: instance method of FileCollection
Returns: Promise.<object> - Created io.cozy.files

Param	Type	Description
data	`File` \| `Blob` \| `Stream` \| `string` \| `ArrayBuffer`	file to be uploaded
dirPath	`string`	Path to upload the file to. ie : /Administative/XXX/

fileCollection.create(attributes)¶

Creates directory or file. - Used by StackLink to support CozyClient.create(‘io.cozy.files’, options)

Kind: instance method of FileCollection
Throws:

Error - explaining reason why creation failed

Param	Type	Description
attributes	`FileAttributes` \| `DirectoryAttributes`	Attributes of the created file/directory
attributes.data	`File` \| `Blob` \| `string` \| `ArrayBuffer`	Will be used as content of the created file

fileCollection.updateFile(data, params) ⇒ `object`¶

updateFile - Updates a file’s data

Kind: instance method of FileCollection
Returns: object - Updated document
Throws:

Error - explaining reason why update failed

Param	Type	Description
data	`File` \| `Blob` \| `Stream` \| `string` \| `ArrayBuffer`	file to be uploaded
params	`FileAttributes`	Additional parameters
params.options	`object`	Options to pass to doUpload method (additional headers)

fileCollection.download(file, versionId, filename)¶

Download a file or a specific version of the file

Kind: instance method of FileCollection

Param	Type	Default	Description
file	`object`		io.cozy.files object
versionId	`string`	`null`	Id of the io.cozy.files.version
filename	`string`		The name you want for the downloaded file (by default the same as the file)

fileCollection.fetchFileContentById(id)¶

Fetch the binary of a file or a specific version of a file Useful for instance when you can’t download the file directly (via a content-disposition attachement header) and need to store it before doing an operation.

Kind: instance method of FileCollection

Param	Type	Description
id	`string`	Id of the io.cozy.files or io.cozy.files.version

fileCollection.getBeautifulSize(file, decimal)¶

Get a beautified size for a given file 1024B => 1KB 102404500404B => 95.37 GB

Kind: instance method of FileCollection

Param	Type	Description
file	`object`	io.cozy.files object
decimal	`number`	number of decimal

fileCollection.downloadArchive(fileIds, [notSecureFilename], [options])¶

Download an archive of the files

Kind: instance method of FileCollection

Param	Type	Description
fileIds	`Array.<string>`	List of file ids
[notSecureFilename]	`string`	Name of the archive (default: ‘files’)
[options]	`object`	Additional options
[options.pages]	`Array.<ArchivePages>`	Array of objects, with `id` the file identifier, and `page` the page number (1 is the first page)

fileCollection.getArchiveLinkByIds()¶

Deprecated

Kind: instance method of FileCollection

fileCollection.createArchiveLinkByIds(params) ⇒ `Promise.<string>`¶

Create the archive link for a list of files The generated archive is temporary and is not persisted

Kind: instance method of FileCollection
Returns: Promise.<string> - - The archive link

Param	Type	Description
params	`object`	Parameters
params.ids	`Array.<string>`	List of file ids
[params.name]	`string`	Name of the archive (default: ‘files’)
[params.pages]	`Array.<ArchivePages>`	Array of objects, with `id` the file identifier, and `page` the page number (1 is the first page)

fileCollection.isChildOf(child, parent) ⇒ `boolean`¶

Checks if the file belongs to the parent’s hierarchy.

Kind: instance method of FileCollection
Returns: boolean - Whether the file is a parent’s child

Param	Type	Description
child	`string` \| `object`	The file which can either be an id or an object
parent	`string` \| `object`	The parent target which can either be an id or an object

fileCollection.statById(id, options) ⇒ `object`¶

statById - Fetches the metadata about a document. For folders, the results include the list of child files and folders.

Kind: instance method of FileCollection
Returns: object - A promise resolving to an object containing “data” (the document metadata), “included” (the child documents) and “links” (pagination informations)

Param	Type	Description
id	`string`	ID of the document
options	`object` \| `null`	Pagination options
[options.page[limit]]	`number` \| `null`	For pagination, the number of results to return.
[options.page[skip]]	`number` \| `null`	For skip-based pagination, the number of referenced files to skip.
[options.page[cursor]]	`CouchDBViewCursor` \| `null`	For cursor-based pagination, the index cursor.

fileCollection.createDirectoryByPath(path) ⇒ `object`¶

async createDirectoryByPath - Creates one or more folders until the given path exists

Kind: instance method of FileCollection
Returns: object - The document corresponding to the last segment of the path

Param	Type	Description
path	`string`	Path of the created directory

fileCollection.createFileMetadata(attributes) ⇒ `Promise.<object>`¶

Send a metadata object that can be associated to a file uploaded after that, via the MetadataID query parameter. See https://github.com/cozy/cozy-stack/blob/master/docs/files.md#post-filesuploadmetadata

Kind: instance method of FileCollection
Returns: Promise.<object> - The Metadata object

Param	Type	Description
attributes	`object`	The file’s metadata

fileCollection.updateMetadataAttribute(id, metadata) ⇒ `Promise.<object>`¶

Updates the metadata attribute of a io.cozy.files Creates a new version of the file without having to upload again the file’s content

To see available content of the metadata attribute see : https://docs.cozy.io/en/cozy-doctypes/docs/io.cozy.files_metadata/

Kind: instance method of FileCollection
Returns: Promise.<object> - io.cozy.files updated

Param	Type	Description
id	`string`	File id
metadata	`object`	io.cozy.files.metadata attributes

fileCollection.getFileTypeFromName(name) ⇒ `string`¶

Get the file mime-type based on its name

Kind: instance method of FileCollection
Returns: string - the inferred file mime-type

Param	Type	Description
name	`string`	The file name

fileCollection.doUpload(dataArg, path, options, method)¶

This method should not be called directly to upload a file. You should use createFile

Kind: instance method of FileCollection

Param	Type	Default	Description
dataArg	`File` \| `Blob` \| `Stream` \| `string` \| `ArrayBuffer`		file to be uploaded
path	`string`		Uri to call the stack from. Something like `/files/${dirId}?Name=${name}&Type=file&Executable=${executable}&MetadataID=${metadataId}`
options	`object`		Additional headers
method	`string`	`"POST"`	POST / PUT / PATCH

fileCollection.findNotSynchronizedDirectories(oauthClient, options) ⇒ `Array.<(object|IOCozyFolder)>`¶

async findNotSynchronizedDirectories - Returns the list of directories not synchronized on the given OAuth client (mainly Cozy Desktop clients) — see https://docs.cozy.io/en/cozy-stack/not-synchronized-vfs/#get-datatypedoc-idrelationshipsnot_synchronizing

Kind: instance method of FileCollection
Returns: Array.<(object|IOCozyFolder)> - The JSON API conformant response.

Param	Type	Description
oauthClient	`OAuthClient`	A JSON representing an OAuth client, with at least a `_type` and `_id` field.
options	`object` \| `null`	Pagination options
options.skip	`number` \| `null`	For skip-based pagination, the number of referenced files to skip.
options.limit	`number` \| `null`	For pagination, the number of results to return.
options.cursor	`CouchDBViewCursor` \| `null`	For cursor-based pagination, the index cursor.
options.includeFiles	`boolean`	Include the whole file documents in the results list

fileCollection.addNotSynchronizedDirectories(oauthClient, directories)¶

Add directory synchronization exclusions to an OAuth client — see https://docs.cozy.io/en/cozy-stack/not-synchronized-vfs/#post-datatypedoc-idrelationshipsnot_synchronizing

For example, to exclude directory /Photos from My Computer‘s desktop synchronization:

addNotSynchronizedDirectories({_id: 123, _type: "io.cozy.oauth.clients", clientName: "Cozy Drive (My Computer)", clientKind: "desktop"}, [{_id: 456, _type: "io.cozy.files", name: "Photos", path: "/Photos"}])

Kind: instance method of FileCollection

Param	Type	Description
oauthClient	`OAuthClient`	A JSON representing the OAuth client
directories	`Array`	An array of JSON documents having a `_type` and `_id` fields and representing directories. Returns 204 No Content

fileCollection.removeNotSynchronizedDirectories(oauthClient, directories)¶

Remove directory synchronization exclusions from an OAuth client — see https://docs.cozy.io/en/cozy-stack/not-synchronized-vfs/#delete-datatypedoc-idrelationshipsnot_synchronizing

For example, to re-include directory /Photos into My Computer‘s desktop synchronization:

 removeNotSynchronizedDirectories({_id: 123, _type: "io.cozy.oauth.clients", clientName: "Cozy Drive (My Computer)", clientKind: "desktop"}, [{_id: 456, _type: "io.cozy.files", name: "Photos", path: "/Photos"}])

Kind: instance method of FileCollection

Param	Type	Description
oauthClient	`OAuthClient`	A JSON representing the OAuth client
directories	`Array`	An array of JSON documents having a `_type` and `_id` field and representing directories. Returns 204 No Content

NotesCollection¶

Implements DocumentCollection API to interact with the /notes endpoint of the stack

Kind: global class

NotesCollection
- .get(id) ⇒ Object
- .all() ⇒ Object
- .destroy(note) ⇒ Object
- .create(options) ⇒ Object
- .fetchURL(note) ⇒ Object
- .getDefaultSchema() ⇒ object

notesCollection.get(id) ⇒ `Object`¶

Fetches the note data

Kind: instance method of NotesCollection
Returns: Object - Information about the note

Param	Type	Description
id	`string`	Note id

notesCollection.all() ⇒ `Object`¶

Fetches all notes

Kind: instance method of NotesCollection
Returns: Object - The JSON API conformant response.

notesCollection.destroy(note) ⇒ `Object`¶

Destroys the note on the server

Kind: instance method of NotesCollection
Returns: Object - The deleted note

Param	Type	Description
note	`object`	The io.cozy.notes document to destroy
[note._id]	`string`	The note’s id

notesCollection.create(options) ⇒ `Object`¶

Create a note

Kind: instance method of NotesCollection
Returns: Object - The JSON API conformant response.

Param	Type	Description
options	`object`	Options
[options.dir_id]	`string`	dir_id where to create the note

notesCollection.fetchURL(note) ⇒ `Object`¶

Returns the details to build the note’s url

Kind: instance method of NotesCollection
Returns: Object - The note’s url details
See: https://github.com/cozy/cozy-stack/blob/master/docs/notes.md#get-notesidopen

Param	Type	Description
note	`object`	The io.cozy.notes document to open
[note._id]	`string`	The note’s id

notesCollection.getDefaultSchema() ⇒ `object`¶

Returns promise mirror schema for a note

Kind: instance method of NotesCollection
Returns: object - schema

OAuthClient¶

Specialized CozyStackClient for mobile, implementing stack registration through OAuth.

Kind: global class

OAuthClient
- .doRegistration()
- .register() ⇒ Promise
- .unregister() ⇒ Promise
- .fetchInformation() ⇒ Promise
- .updateInformation(information, resetSecret) ⇒ Promise
- .generateStateCode() ⇒ string
- .getAuthCodeURL(options) ⇒ string
- .getAccessCodeFromURL(pageURL, stateCode) ⇒ string
- .fetchAccessToken(accessCode, oauthOptionsArg, uri, codeVerifier) ⇒ Promise
- .fetchKonnectorToken(slug) ⇒ Promise.<string>
- .fetchSessionCode() ⇒ Promise.<SessionCodeRes>
- .fetchSessionCodeWithPassword() ⇒ Promise.<SessionCodeRes>
- .loginFlagship() ⇒ Promise.<(AccessTokenRes|TwoFactorNeededRes|SessionCodeRes)>
- .refreshToken() ⇒ Promise
- .setToken(token)
- .setOAuthOptions(options)
- .resetClient()
- .setPassphraseFlagship(params) ⇒ object
- .checkForRevocation() ⇒ Promise.<boolean>

oAuthClient.doRegistration()¶

Performs the HTTP call to register the client to the server

Kind: instance method of OAuthClient

oAuthClient.register() ⇒ `Promise`¶

Registers the currenly configured client with the OAuth server and sets internal information from the server response

Kind: instance method of OAuthClient
Returns: Promise - A promise that resolves with a complete list of client information, including client ID and client secret.
Throws:

Error When the client is already registered

oAuthClient.unregister() ⇒ `Promise`¶

Unregisters the currenly configured client with the OAuth server.

Kind: instance method of OAuthClient
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

oAuthClient.fetchInformation() ⇒ `Promise`¶

Fetches the complete set of client information from the server after it has been registered.

Kind: instance method of OAuthClient
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

oAuthClient.updateInformation(information, resetSecret) ⇒ `Promise`¶

Overwrites the client own information. This method will update both the local information and the remote information on the OAuth server.

Kind: instance method of OAuthClient
Returns: Promise - Resolves to a complete, updated list of client information
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

Param	Type	Default	Description
information	`object`		Set of information to update. Note that some fields such as `clientID` can’t be updated.
resetSecret	`boolean`	`false`	= false Optionnal, whether to reset the client secret or not

oAuthClient.generateStateCode() ⇒ `string`¶

Generates a random state code to be used during the OAuth process

Kind: instance method of OAuthClient

oAuthClient.getAuthCodeURL(options) ⇒ `string`¶

Generates the URL that the user should be sent to in order to accept the app’s permissions.

Kind: instance method of OAuthClient
Returns: string - The URL
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

Param	Type	Description
options	`object`	URL generation options
options.stateCode	`string`	A random code to be included in the URl for security. Can be generated with `client.generateStateCode()`
[options.scopes]	`Array`	An array of permission scopes for the token.
[options.sessionCode]	`SessionCode`	A session code that can be used to create a session.
[options.codeChallenge]	`string`	A code challenge that can be used in a PKCE verification process.

oAuthClient.getAccessCodeFromURL(pageURL, stateCode) ⇒ `string`¶

Retrieves the access code contained in the URL to which the user is redirected after accepting the app’s permissions (the redirectURI).

Kind: instance method of OAuthClient
Returns: string - The access code
Throws:

Error The URL should contain the same state code as the one generated with client.getAuthCodeURL(). If not, it will throw an error

Param	Type	Description
pageURL	`string`	The redirected page URL, containing the state code and the access code
stateCode	`string`	The state code that was contained in the original URL the user was sent to (see `client.getAuthCodeURL()`)

oAuthClient.fetchAccessToken(accessCode, oauthOptionsArg, uri, codeVerifier) ⇒ `Promise`¶

Exchanges an access code for an access token. This function does not update the client’s token.

Kind: instance method of OAuthClient
Returns: Promise - A promise that resolves with an AccessToken object.
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

Param	Type	Description
accessCode	`string`	The access code contained in the redirection URL — see `client.getAccessCodeFromURL()`
oauthOptionsArg	`object`	— To use when OAuthClient is not yet registered (during login process)
uri	`string`	— To use when OAuthClient is not yet registered (during login process)
codeVerifier	`string`	— The PKCE code verifier (see https://docs.cozy.io/en/cozy-stack/auth/#pkce-extension)

oAuthClient.fetchKonnectorToken(slug) ⇒ `Promise.<string>`¶

Used by the flagship application in order to create a token for the konnector with the given slug. This token can then be used by the client-side konnector to make requests to cozy-stack. The flagship app will need to use its own access token to request the konnector token.

Kind: instance method of OAuthClient
Returns: Promise.<string> - - A promise that resolves with a new token

Param	Type	Description
slug	`string`	The slug of the konnector

oAuthClient.fetchSessionCode() ⇒ `Promise.<SessionCodeRes>`¶

Fetches a new session code. Only usable by the Flagship application

Kind: instance method of OAuthClient
Returns: Promise.<SessionCodeRes> - A promise that resolves with a new session_code
Throws:

NotRegisteredException When the client isn’t certified to be the Flagship application

oAuthClient.fetchSessionCodeWithPassword() ⇒ `Promise.<SessionCodeRes>`¶

Fetches a new session code. Only usable by the Flagship application

Kind: instance method of OAuthClient
Returns: Promise.<SessionCodeRes> - A promise that resolves with a new session_code
Throws:

NotRegisteredException When the client isn’t certified to be the Flagship application

oAuthClient.loginFlagship() ⇒ `Promise.<(AccessTokenRes|TwoFactorNeededRes|SessionCodeRes)>`¶

Get OAuth access and register tokens without having to make OAuth dance

This endpoint returns registration tokens only from a Flagship app, otherwise it returns a session_code that should be used in an OAuth dance

More info: https://docs.cozy.io/en/cozy-stack/flagship/ More info: https://docs.cozy.io/en/cozy-stack/auth/#post-authloginflagship

Kind: instance method of OAuthClient
Returns: Promise.<(AccessTokenRes|TwoFactorNeededRes|SessionCodeRes)> - A promise that resolves with an access token, a session_code or a 2FA code

oAuthClient.refreshToken() ⇒ `Promise`¶

Retrieves a new access token by refreshing the currently used token.

Kind: instance method of OAuthClient
Returns: Promise - A promise that resolves with a new AccessToken object
Throws:

NotRegisteredException When the client doesn’t have it’s registration information
Error The client should already have an access token to use this function

oAuthClient.setToken(token)¶

Updates the client’s stored token

Kind: instance method of OAuthClient

Param	Type	Description
token	`string`	= null The new token to use — can be a string, a json object or an AccessToken instance.

oAuthClient.setOAuthOptions(options)¶

Updates the OAuth informations

Kind: instance method of OAuthClient

Param	Type	Description
options	`object`	Map of OAuth options

oAuthClient.resetClient()¶

Reset the current OAuth client

Kind: instance method of OAuthClient

oAuthClient.setPassphraseFlagship(params) ⇒ `object`¶

This method should be used in flagship app onboarding process to finalize the cozy creation by setting the user password into the cozy-stack

More info: https://docs.cozy.io/en/cozy-stack/settings/#post-settingspassphraseflagship

Kind: instance method of OAuthClient
Returns: object - token - The OAauth token

Param	Type	Description
params	`object`	parameters needed to set passphrase
params.registerToken	`string`	registration token provided by the onboarding link
params.passwordHash	`string`	hash of the master password
params.hint	`string`	hint for the master password
params.key	`string`	key (crypted) used for the vault encryption
params.publicKey	`string`	public key used for sharing ciphers from the vault
params.privateKey	`string`	private key (crypted) used for sharing ciphers from the vault
params.iterations	`string`	number of KDF iterations applied when hashing the master password

oAuthClient.checkForRevocation() ⇒ `Promise.<boolean>`¶

Check if the OAuth client’s has been revoked. If this is the case, call the onRevocationChange callback

Kind: instance method of OAuthClient
Returns: Promise.<boolean> - A Promise that resolves to false if client is still valid, or true if it has been revoked.

OAuthClientsCollection¶

Implements DocumentCollection API to interact with the /settings/clients endpoint of the stack

Kind: global class

OAuthClientsCollection
- .all(options) ⇒ object
- .get(id) ⇒ object
- .destroy(oauthClient) ⇒ Object

oAuthClientsCollection.all(options) ⇒ `object`¶

Fetches all OAuth clients

Kind: instance method of OAuthClientsCollection
Returns: object - The JSON API conformant response.

Param	Type	Description
options	`object`	Query options
[options.limit]	`number`	For pagination, the number of results to return.
[options.bookmark]	`string`	For bookmark-based pagination, the document _id to start from
[options.keys]	`Array.<string>`	Ids of specific clients to return (within the current page),

oAuthClientsCollection.get(id) ⇒ `object`¶

Get an OAuth client by id

Kind: instance method of OAuthClientsCollection
Returns: object - JsonAPI response containing normalized client as data attribute

Param	Type	Description
id	`string`	The client id.

oAuthClientsCollection.destroy(oauthClient) ⇒ `Object`¶

Destroys the OAuth client on the server

Kind: instance method of OAuthClientsCollection
Returns: Object - The deleted client

Param	Type	Description
oauthClient	`object`	The io.cozy.oauth.clients document to destroy

PermissionCollection¶

Implements DocumentCollection API along with specific methods for io.cozy.permissions.

Kind: global class

PermissionCollection
- .create(permission)
- .add(document, permission) ⇒ Promise
- ~~.findApps()~~
- .createSharingLink(document, options)
- .fetchPermissionsByLink(permissions)
- .fetchAllLinks(document) ⇒ object
- .revokeSharingLink(document)

permissionCollection.create(permission)¶

Create a new set of permissions It can also associates one or more codes to it, via the codes parameter

Kind: instance method of PermissionCollection
See: https://docs.cozy.io/en/cozy-stack/permissions/#post-permissions

Param	Type	Description
permission	`object`	permission to create
permission.codes	`string`	A comma separed list of values (defaulted to code)
permission.ttl	`string`	Make the codes expire after a delay (bigduration format)
permission.tiny	`boolean`	If set to true then the generated shortcode will be 6 digits Cozy-Stack has a few conditions to be able to use this tiny shortcode ATM you have to specifiy a ttl < 1h, but it can change. see https://docs.cozy.io/en/cozy-stack/permissions/#post-permissions for exact informations bigduration format: https://github.com/justincampbell/bigduration/blob/master/README.md

permissionCollection.add(document, permission) ⇒ `Promise`¶

Adds a permission to the given document. Document type must be io.cozy.apps, io.cozy.konnectors or io.cozy.permissions

Kind: instance method of PermissionCollection

Param	Type	Description
document	`object`	Document which receives the permission
permission	`object`	Describes the permission

Example

const permissions = await client
  .collection('io.cozy.permissions')
  .add(konnector, {
    folder: {
      type: 'io.cozy.files',
      verbs: ['GET', 'PUT'],
      values: [`io.cozy.files.bc57b60eb2954537b0dcdc6ebd8e9d23`]
    }
 })

permissionCollection.findApps()¶

Deprecated

Kind: instance method of PermissionCollection

permissionCollection.createSharingLink(document, options)¶

Create a share link

Kind: instance method of PermissionCollection

Param	Type	Description
document	`Object`	cozy document
options	`object`	options
options.verbs	`Array.<string>`	explicit permissions to use

permissionCollection.fetchPermissionsByLink(permissions)¶

Follow the next link to fetch the next permissions

Kind: instance method of PermissionCollection

Param	Type	Description
permissions	`object`	JSON-API based permissions document

permissionCollection.fetchAllLinks(document) ⇒ `object`¶

Kind: instance method of PermissionCollection
Returns: object - with all the permissions

Param	Type	Description
document	`object`	Cozy doc

permissionCollection.revokeSharingLink(document)¶

Destroy a sharing link and the related permissions

Kind: instance method of PermissionCollection

Param	Type	Description
document	`object`	document to revoke sharing link

PromiseCache¶

Caches promises while they are pending Serves to dedupe equal queries requested at the same time

Kind: global class

PromiseCache
- .pending : Object.<string, Promise>
- .exec(promiseFunc, keyFunc) ⇒ Promise.<T>
- .get(keyFunc) ⇒ Promise | null

promiseCache.pending : `Object.<string, Promise>`¶

Holds pending promises

Kind: instance property of PromiseCache

promiseCache.exec(promiseFunc, keyFunc) ⇒ `Promise.<T>`¶

Tries to find a pending promise corresponding to the result of keyFunc - If not found, promiseFunc is executed and the resulting promise is stored while it’s pending - If found, it is immediately returned

Kind: instance method of PromiseCache

Param	Type	Description
promiseFunc	`function`	Not executed only if an “equal” promise is already pending.
keyFunc	`function`	Returns a key to find in cache to find a pending promise.

promiseCache.get(keyFunc) ⇒ `Promise` | `null`¶

Kind: instance method of PromiseCache

Param	Type	Description
keyFunc	`function`	Returns a key to find in cache to find a pending promise.

SettingsCollection¶

Implements DocumentCollection API to interact with the /settings endpoint of the stack

Kind: global class

SettingsCollection
- .get(id) ⇒ object
- .update(document)

settingsCollection.get(id) ⇒ `object`¶

async get - Calls a route on the /settings API

Kind: instance method of SettingsCollection
Returns: object - The response from the route

Param	Type	Description
id	`string`	The setting id to call, eg `io.cozy.settings.instance` for `instance` route or `io.cozy.settings.context` for `context`route

settingsCollection.update(document)¶

Updates a settings document

Kind: instance method of SettingsCollection

Param	Type	Description
document	`object`	Document to update. Do not forget the _id attribute

SharingCollection¶

Implements the DocumentCollection API along with specific methods for io.cozy.sharings.

Kind: global class

SharingCollection

Fetches a sharing by id

Kind: instance method of SharingCollection
Returns: Sharing - sharing

Param	Type	Description
id	`string`	Sharing’s id

sharingCollection.create(params)¶

Creates a new Sharing. See https://docs.cozy.io/en/cozy-stack/sharing/#post-sharings

Kind: instance method of SharingCollection

Param	Type	Description
params	`object`	Sharing params
params.document	`Sharing`	The document to share
params.description	`string`	Description of the sharing
[params.previewPath]	`string`	The preview path
[params.rules]	`Array.<Rule>`	The rules defined to the sharing. See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing
[params.recipients]	`Array.<Recipient>`	Recipients to add to the sharings (will have the same permissions given by the rules defined by the sharing )
[params.readOnlyRecipients]	`Array.<Recipient>`	Recipients to add to the sharings with only read only access
[params.openSharing]	`boolean`	If someone else than the owner can add a recipient to the sharing
[params.appSlug]	`string`	Slug of the targeted app

sharingCollection.share(document, recipients, sharingType, description, [previewPath])¶

Deprecated

Kind: instance method of SharingCollection

Param	Type	Default	Description
document	`Sharing`		The document to share. Should have and _id and a name.
recipients	`Array`		A list of io.cozy.contacts
sharingType	`string`		If “two-way”, will set the open_sharing attribute to true
description	`string`		Describes the sharing
[previewPath]	`string`	`null`	Relative URL of the sharings preview page

sharingCollection.getDiscoveryLink(sharingId, sharecode) ⇒ `string`¶

getDiscoveryLink - Returns the URL of the page that can be used to accept a sharing. See https://docs.cozy.io/en/cozy-stack/sharing/#get-sharingssharing-iddiscovery

Kind: instance method of SharingCollection

Param	Type	Description
sharingId	`string`	Id of the sharing
sharecode	`string`	Code of the sharing

sharingCollection.addRecipients(options)¶

Add an array of contacts to the Sharing

Kind: instance method of SharingCollection

Param	Type	Description
options	`object`	Object
options.document	`Sharing`	Sharing Object
[options.recipients]	`Array.<Recipient>`	Recipients to add to the sharing
[options.readOnlyRecipients]	`Array.<Recipient>`	Recipients to add to the sharings with only read only access

sharingCollection.revokeRecipient(sharing, recipientIndex)¶

Revoke only one recipient of the sharing.

Kind: instance method of SharingCollection

Param	Type	Description
sharing	`Sharing`	Sharing Object
recipientIndex	`number`	Index of this recipient in the members array of the sharing

sharingCollection.revokeGroup(sharing, groupIndex)¶

Revoke only one group of the sharing.

Kind: instance method of SharingCollection

Param	Type	Description
sharing	`Sharing`	Sharing Object
groupIndex	`number`	Index of this group in the groups array of the sharing

sharingCollection.revokeSelf(sharing)¶

Remove self from the sharing.

Kind: instance method of SharingCollection

Param	Type	Description
sharing	`Sharing`	Sharing Object

sharingCollection.revokeAllRecipients(sharing)¶

Revoke the sharing for all the members. Must be called from the owner’s cozy

Kind: instance method of SharingCollection

Param	Type	Description
sharing	`Sharing`	Sharing Objects

TriggerCollection¶

Implements DocumentCollection API along with specific methods for io.cozy.triggers.

Kind: global class

TriggerCollection
- .all(options) ⇒ Object
- .create(attributes) ⇒ object
- .destroy(document) ⇒ object
- .find(selector, options) ⇒ Object
- .launch(trigger) ⇒ object
- .update(trigger) ⇒ object

triggerCollection.all(options) ⇒ `Object`¶

Get the list of triggers.

Kind: instance method of TriggerCollection
Returns: Object - The JSON API conformant response.
Throws:

FetchError

See: https://docs.cozy.io/en/cozy-stack/jobs/#get-jobstriggers

Param	Type	Description
options	`Object`	The fetch options: Worker allow to filter only triggers associated with a specific worker.

triggerCollection.create(attributes) ⇒ `object`¶

Creates a Trigger document

Kind: instance method of TriggerCollection
Returns: object - Stack response, containing trigger document under data attribute.
See: https://docs.cozy.io/en/cozy-stack/jobs/#post-jobstriggers

Param	Type	Description
attributes	`object`	Trigger’s attributes

triggerCollection.destroy(document) ⇒ `object`¶

Deletes a trigger

Kind: instance method of TriggerCollection
Returns: object - The deleted document
See: https://docs.cozy.io/en/cozy-stack/jobs/#delete-jobstriggerstrigger-id

Param	Type	Description
document	`object`	The trigger to delete — must have an _id field

triggerCollection.find(selector, options) ⇒ `Object`¶

Be warned, ATM /jobs/triggers does not return the same informations than /data/io.cozy.triggers (used by the super.find method).

See https://github.com/cozy/cozy-stack/pull/2010

Kind: instance method of TriggerCollection
Returns: Object - The JSON API conformant response.
Throws:

FetchError

Param	Type	Description
selector	`object`	Which kind of worker
options	`object`	Options

triggerCollection.launch(trigger) ⇒ `object`¶

Force given trigger execution.

Kind: instance method of TriggerCollection
Returns: object - Stack response, containing job launched by trigger, under data attribute.
See: https://docs.cozy.io/en/cozy-stack/jobs/#post-jobstriggerstrigger-idlaunch

Param	Type	Description
trigger	`object`	Trigger to launch

triggerCollection.update(trigger) ⇒ `object`¶

Updates a Trigger document. Only updatable attributes plus _id are allowed.

Kind: instance method of TriggerCollection
Returns: object - Stack response, containing resulting trigger document under data attribute.

Param	Type	Description
trigger	`object`	Trigger’s attributes to update + id

dontThrowNotFoundError ⇒ `object`¶

Handler for error response which return a empty value for “not found” error

Kind: global constant
Returns: object - JsonAPI response with empty data in case of “not found” error.

Param	Type	Description
error	`Error`	An error
data	`Array` \| `object` \| `null`	Data to return in case of “not found” error

isIndexNotFoundError ⇒ `Array` | `null`¶

Helper to identify an index not found error

Kind: global constant
Returns: Array | null - - Whether or not the error is an index not found error

Param	Type	Description
error	`Error`	An error

isIndexConflictError ⇒ `Array` | `null`¶

Helper to identify an index conflict

Kind: global constant
Returns: Array | null - - Whether or not the error is an index conflict error

Param	Type	Description
error	`Error`	An error

isIndexNotUsedWarning ⇒ `Array` | `null`¶

Helper to identify a not used index

Kind: global constant
Returns: Array | null - Whether or not this is a not used index warning

Param	Type	Description
warning	`string`	The warning returned by CouchDB

isNoUsableIndexError ⇒ `Array` | `null`¶

Helper to identify a no usable index error

Kind: global constant
Returns: Array | null - - Whether or not the error is a no usable index error

Param	Type	Description
error	`Error`	An error

isTimeoutError ⇒ `Array` | `null`¶

Helper to identify timeout error See cozy-stack’s timeout value for couchdb request: https://github.com/cozy/cozy-stack/blob/669cd694132388ef6b7d1a58cf3d1b5dfb52896a/pkg/config/config/config.go#L963

Kind: global constant
Returns: Array | null - Whether or not the error is a timeout error

Param	Type	Description
error	`Error`	An error

isDocumentUpdateConflict ⇒ `Array` | `null`¶

Helper to identify a document conflict

Kind: global constant
Returns: Array | null - - Whether or not the error is a document conflict error

Param	Type	Description
error	`Error`	An error

isFile ⇒ `boolean`¶

Returns true when parameter has type directory, file or has _type io.cozy.files

Kind: global constant
Returns: boolean - true when objects has type directory, file or has _type io.cozy.files or false

Param	Type	Description
doc	`object`	The document whose type is checked
[doc._type]	`string`	The document’s doctype
[doc.type]	`'directory'` \| `'file'`	The io.cozy-files document type

isDirectory ⇒ `boolean`¶

Returns true when parameters has type directory

Kind: global constant
Returns: boolean - true when parameters has type directory or false

Param	Type	Description
args	`object`	File
args.type	`string`	The type of the file

getIllegalCharacters ⇒ `string`¶

Get the list of illegal characters in the file name

Kind: global constant
Returns: string - illegal characters separated by spaces
Access: public

Param	Type	Description
name	`string`	the file name

makeKeyFromPartialFilter ⇒ `string`¶

Process a partial filter to generate a string key

/!\ Warning: this method is similar to cozy-pouch-link mango.makeKeyFromPartialFilter() If you edit this method, please check if the change is also needed in mango file

Kind: global constant
Returns: string - - The string key of the processed partial filter

Param	Type	Description
condition	`object`	An object representing the partial filter or a sub-condition of the partial filter

getIndexNameFromFields ⇒ `string`¶

Name an index, based on its indexed fields and partial filter.

It follows this naming convention: by_{indexed_field1}_and_{indexed_field2}_filter_({partial_filter.key1}_{partial_filter.value1})_and_({partial_filter.key2}_{partial_filter.value2})

/!\ Warning: this method is similar to cozy-pouch-link mango.getIndexNameFromFields() If you edit this method, please check if the change is also needed in mango file

Kind: global constant
Returns: string - The index name, built from the fields

Param	Type	Description
fields	`Array.<string>`	The indexed fields
[partialFilter]	`object`	The partial filter

transformSort ⇒ `MangoSort`¶

Transform sort into Array

Kind: global constant

Param	Type	Description
sort	`MangoSort`	The sorting parameters

getIndexFields ⇒ `Array`¶

Compute fields that should be indexed for a mango query to work

Kind: global constant
Returns: Array - - Fields to index

isMatchingIndex ⇒ `boolean`¶

Check if an index is matching the given fields

Kind: global constant
Returns: boolean - True if the index is matches the given fields

Param	Type	Description
index	`DesignDoc`	The index to check
fields	`Array`	The fields that the index must have
partialFilter	`object`	An optional partial filter

makeOperatorsExplicit ⇒ `object`¶

Transform a query to make all operators explicit

Kind: global constant
Returns: object - - The transformed query with all operators explicit

Param	Type	Description
query	`object`	The query to transform
reverseEq	`boolean`	If true, $eq will be transformed to $ne (useful for manage $nor)

getPermissionsFor ⇒ `object`¶

Build a permission set

Kind: global constant
Returns: object - permissions object that can be sent through /permissions/*

Param	Type	Description
document	`Object`	cozy document
publicLink	`boolean`	are the permissions for a public link ?
options	`object`	options
options.verbs	`Array.<string>`	explicit permissions to use

normalizeSettings ⇒ `object`¶

Normalizing a document for SettingsCollection context

Kind: global constant
Returns: object - normalized document

Param	Type	Description
doc	`object`	Document to normalize

getSharingRules ⇒ `Array.<Rule>`¶

Rules determine the behavior of the sharing when changes are made to the shared document See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing

Kind: global constant
Returns: Array.<Rule> - The rules that define how to share the document

Param	Type	Description
document	`Sharing`	The document to share. Should have and _id and a name
sharingType	`SharingType`	The type of the sharing

forceDownload¶

Force a download from the given href

Kind: global constant

Param	Type	Description
href	`string`	The link to download
filename	`string`	The file name to download

encodePath ⇒ `string`¶

Encode a path for use in a URL by encoding special characters but keeping slashes

Kind: global constant
Returns: string - - The encoded path with special characters for parentheses and spaces

Param	Type	Description
path	`string`	The path to encode

getAccessToken() ⇒ `string`¶

Get the access token string

Kind: global function
Returns: string - token
See: CozyStackClient.getAccessToken

getAccessToken() ⇒ `string`¶

Get the app token string

Kind: global function
Returns: string - token
See: CozyStackClient.getAccessToken

getIconURL()¶

Get Icon URL using blob mechanism if OAuth connected or using preloaded url when blob not needed

Kind: global function

handleNorOperator(conditions) ⇒ `Array`¶

Handle the $nor operator in a query CouchDB transforms $nor into $and with $ne operators

Kind: global function
Returns: Array - - The reversed conditions

Param	Type	Description
conditions	`Array`	The conditions inside the $nor operator

sortObjectByKey(a, b) ⇒ `number`¶

Compares two objects based on their first key to determine their order.

Kind: global function
Returns: number - - A negative number if the key of a should appear before the key of b, a positive number if it should appear after, or 0 if they are equal.

Param	Type	Description
a	`object`	The first object to compare
b	`object`	The second object to compare

garbageCollect()¶

Delete outdated results from cache

Kind: global function

memoize()¶

Memoize with maxDuration and custom key

Kind: global function

normalizeDoctypeJsonApi(doctype) ⇒ `function`¶

Normalizes a document in JSON API format for a specific doctype

Kind: global function
Returns: function - A function that normalizes the document

Param	Type	Description
doctype	`string`	The document type

getSharingRulesForPhotosAlbum(document, sharingType) ⇒ `Array.<Rule>`¶

Compute the rules that define how to share a Photo Album. See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing

Kind: global function
Returns: Array.<Rule> - The rules that define how to share a Photo Album

Param	Type	Description
document	`Sharing`	The document to share. Should have and _id and a name
sharingType	`SharingType`	The type of the sharing

getSharingPolicyForReferencedFiles(sharingType) ⇒ `SharingPolicy`¶

Compute the sharing policy for a ReferencedFile based on its sharing type

Kind: global function
Returns: SharingPolicy - The sharing policy for the ReferencedFile

Param	Type	Description
sharingType	`SharingType`	The type of the sharing

getSharingPolicyForAlbum(sharingType) ⇒ `Array.<Rule>`¶

Compute the sharing policy for an Album based on its sharing type

Kind: global function
Returns: Array.<Rule> - The sharing policy for the Album

Param	Type	Description
sharingType	`SharingType`	The type of the sharing

getSharingRulesForFile(document, sharingType) ⇒ `Array.<Rule>`¶

Compute the rules that define how to share a File. See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing

Kind: global function
Returns: Array.<Rule> - The rules that define how to share a File

Param	Type	Description
document	`Sharing`	The document to share. Should have and _id and a name
sharingType	`SharingType`	The type of the sharing

getSharingPolicyForFile(document, sharingType) ⇒ `SharingPolicy`¶

Compute the sharing policy for a File based on its sharing type

Kind: global function
Returns: SharingPolicy - The sharing policy for the File

Param	Type	Description
document	`Sharing`	The document to share. Should have and _id and a name
sharingType	`SharingType`	The type of the sharing

getSharingRulesForOrganizations(document) ⇒ `Array.<Rule>`¶

Compute the rules that define how to share an Organization. See https://docs.cozy.io/en/cozy-stack/sharing-design/#description-of-a-sharing

Kind: global function
Returns: Array.<Rule> - The rules that define how to share an Organization

Param	Type	Description
document	`Sharing`	The document to share. Should have and _id and a name

toRelationshipItem(item) ⇒ `RelationshipItem`¶

Compute the RelationshipItem that can be referenced as a sharing recipient

Kind: global function
Returns: RelationshipItem - The RelationshipItem that can be referenced as a sharing recipient

Param	Type	Description
item	`Recipient`	The recipient of a sharing

getCozyURL()¶

Get a uniform formatted URL and SSL information according to a provided URL

Kind: global function

joinPath(start, end) ⇒ `string`¶

Join two paths together ensuring there is only one slash between them

Kind: global function
Returns: string - The joined path

Param	Type	Description
start	`string`	The starting part of the path
end	`string`	The ending part of the path

FetchChangesReturnValue ⇒ `Promise.<FetchChangesReturnValue>`¶

Use Couch _changes API Deleted and design docs are filtered by default, thus documents are retrieved in the response (include_docs is set to true in the parameters of _changes).

You should use fetchChangesRaw to have low level control on _changes parameters.

Kind: global typedef

Param	Type	Description
couchOptions	`object`	Couch options for changes
[couchOptions.since]	`string`	Bookmark telling CouchDB from which point in time should changes be returned
[couchOptions.doc_ids]	`Array.<string>`	Only return changes for a subset of documents
options	`object`	Further options on the returned documents. By default, it is set to
[options.includeDesign]	`boolean`	Whether to include changes from design docs (needs include_docs to be true)
[options.includeDeleted]	`boolean`	Whether to include changes for deleted documents (needs include_docs to be true)

Properties

Name	Type
newLastSeq	`string`
documents	`Array.<object>`

IOCozyFolder : `object`¶

Folder

Kind: global typedef

SpecificFileAttributesForKonnector : `object`¶

Specific file attributes for creation for konnector

Kind: global typedef
Properties

Name	Type	Description
sourceAccount	`string`	the id of the source account used by a konnector
sourceAccountIdentifier	`string`	the unique identifier of the account targeted by the connector

CouchDBViewCursor : `Array.<string>` | `string`¶

Cursor used for Mango queries pagination

Kind: global typedef

DirectoryAttributes : `object`¶

Attributes used for directory creation

Kind: global typedef
Properties

Name	Type	Description
dirId	`string`	Id of the parent directory.
name	`boolean`	Name of the created directory.
executable	`boolean`	Indicates whether the file will be executable.
[metadata]	`object`	io.cozy.files.metadata to attach to the directory

FileAttributes : `object`¶

Attributes used for file creation

Kind: global typedef
Properties

Name	Type	Description
id	`string`	Id of the document
_id	`string`	Id of the document
dirId	`string`	Id of the parent directory.
name	`string`	Name of the created file.
lastModifiedDate	`Date`	Can be used to set the last modified date of a file.
executable	`boolean`	Whether or not the file is executable
encrypted	`boolean`	Whether or not the file is client-side encrypted
metadata	`object`	io.cozy.files.metadata to attach to the file

FileDocument : `object`¶

Document representing a io.cozy.files

Kind: global typedef
Properties

Name	Type	Description
_id	`string`	Id of the file
_rev	`string`	Rev of the file
attributes	`FileAttributes`	Attributes of the file
meta	`object`	Meta
relationships	`object`	Relationships
referenced_by	`object`	Referenced by

Stream : `object`¶

Stream is not defined in a browser, but is on NodeJS environment

Kind: global typedef

OAuthClient : `object`¶

Document representing a io.cozy.oauth.clients

Kind: global typedef
Properties

Name	Type	Description
_id	`string`	Id of the client
_type	`string`	Doctype of the client (i.e. io.cozy.oauth.clients)

OAuthClient : object
- .doRegistration()
- .register() ⇒ Promise
- .unregister() ⇒ Promise
- .fetchInformation() ⇒ Promise
- .updateInformation(information, resetSecret) ⇒ Promise
- .generateStateCode() ⇒ string
- .getAuthCodeURL(options) ⇒ string
- .getAccessCodeFromURL(pageURL, stateCode) ⇒ string
- .fetchAccessToken(accessCode, oauthOptionsArg, uri, codeVerifier) ⇒ Promise
- .fetchKonnectorToken(slug) ⇒ Promise.<string>
- .fetchSessionCode() ⇒ Promise.<SessionCodeRes>
- .fetchSessionCodeWithPassword() ⇒ Promise.<SessionCodeRes>
- .loginFlagship() ⇒ Promise.<(AccessTokenRes|TwoFactorNeededRes|SessionCodeRes)>
- .refreshToken() ⇒ Promise
- .setToken(token)
- .setOAuthOptions(options)
- .resetClient()
- .setPassphraseFlagship(params) ⇒ object
- .checkForRevocation() ⇒ Promise.<boolean>

oAuthClient.doRegistration()¶

Performs the HTTP call to register the client to the server

Kind: instance method of OAuthClient

oAuthClient.register() ⇒ `Promise`¶

Registers the currenly configured client with the OAuth server and sets internal information from the server response

Kind: instance method of OAuthClient
Returns: Promise - A promise that resolves with a complete list of client information, including client ID and client secret.
Throws:

Error When the client is already registered

oAuthClient.unregister() ⇒ `Promise`¶

Unregisters the currenly configured client with the OAuth server.

Kind: instance method of OAuthClient
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

oAuthClient.fetchInformation() ⇒ `Promise`¶

Fetches the complete set of client information from the server after it has been registered.

Kind: instance method of OAuthClient
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

oAuthClient.updateInformation(information, resetSecret) ⇒ `Promise`¶

Overwrites the client own information. This method will update both the local information and the remote information on the OAuth server.

Kind: instance method of OAuthClient
Returns: Promise - Resolves to a complete, updated list of client information
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

Param	Type	Default	Description
information	`object`		Set of information to update. Note that some fields such as `clientID` can’t be updated.
resetSecret	`boolean`	`false`	= false Optionnal, whether to reset the client secret or not

oAuthClient.generateStateCode() ⇒ `string`¶

Generates a random state code to be used during the OAuth process

Kind: instance method of OAuthClient

oAuthClient.getAuthCodeURL(options) ⇒ `string`¶

Generates the URL that the user should be sent to in order to accept the app’s permissions.

Kind: instance method of OAuthClient
Returns: string - The URL
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

Param	Type	Description
options	`object`	URL generation options
options.stateCode	`string`	A random code to be included in the URl for security. Can be generated with `client.generateStateCode()`
[options.scopes]	`Array`	An array of permission scopes for the token.
[options.sessionCode]	`SessionCode`	A session code that can be used to create a session.
[options.codeChallenge]	`string`	A code challenge that can be used in a PKCE verification process.

oAuthClient.getAccessCodeFromURL(pageURL, stateCode) ⇒ `string`¶

Retrieves the access code contained in the URL to which the user is redirected after accepting the app’s permissions (the redirectURI).

Kind: instance method of OAuthClient
Returns: string - The access code
Throws:

Error The URL should contain the same state code as the one generated with client.getAuthCodeURL(). If not, it will throw an error

Param	Type	Description
pageURL	`string`	The redirected page URL, containing the state code and the access code
stateCode	`string`	The state code that was contained in the original URL the user was sent to (see `client.getAuthCodeURL()`)

oAuthClient.fetchAccessToken(accessCode, oauthOptionsArg, uri, codeVerifier) ⇒ `Promise`¶

Exchanges an access code for an access token. This function does not update the client’s token.

Kind: instance method of OAuthClient
Returns: Promise - A promise that resolves with an AccessToken object.
Throws:

NotRegisteredException When the client doesn’t have it’s registration information

Param	Type	Description
accessCode	`string`	The access code contained in the redirection URL — see `client.getAccessCodeFromURL()`
oauthOptionsArg	`object`	— To use when OAuthClient is not yet registered (during login process)
uri	`string`	— To use when OAuthClient is not yet registered (during login process)
codeVerifier	`string`	— The PKCE code verifier (see https://docs.cozy.io/en/cozy-stack/auth/#pkce-extension)

oAuthClient.fetchKonnectorToken(slug) ⇒ `Promise.<string>`¶

Used by the flagship application in order to create a token for the konnector with the given slug. This token can then be used by the client-side konnector to make requests to cozy-stack. The flagship app will need to use its own access token to request the konnector token.

Kind: instance method of OAuthClient
Returns: Promise.<string> - - A promise that resolves with a new token

Param	Type	Description
slug	`string`	The slug of the konnector

oAuthClient.fetchSessionCode() ⇒ `Promise.<SessionCodeRes>`¶

Fetches a new session code. Only usable by the Flagship application

Kind: instance method of OAuthClient
Returns: Promise.<SessionCodeRes> - A promise that resolves with a new session_code
Throws:

NotRegisteredException When the client isn’t certified to be the Flagship application

oAuthClient.fetchSessionCodeWithPassword() ⇒ `Promise.<SessionCodeRes>`¶

Fetches a new session code. Only usable by the Flagship application

Kind: instance method of OAuthClient
Returns: Promise.<SessionCodeRes> - A promise that resolves with a new session_code
Throws:

NotRegisteredException When the client isn’t certified to be the Flagship application

oAuthClient.loginFlagship() ⇒ `Promise.<(AccessTokenRes|TwoFactorNeededRes|SessionCodeRes)>`¶

Get OAuth access and register tokens without having to make OAuth dance

This endpoint returns registration tokens only from a Flagship app, otherwise it returns a session_code that should be used in an OAuth dance

More info: https://docs.cozy.io/en/cozy-stack/flagship/ More info: https://docs.cozy.io/en/cozy-stack/auth/#post-authloginflagship

Kind: instance method of OAuthClient
Returns: Promise.<(AccessTokenRes|TwoFactorNeededRes|SessionCodeRes)> - A promise that resolves with an access token, a session_code or a 2FA code

oAuthClient.refreshToken() ⇒ `Promise`¶

Retrieves a new access token by refreshing the currently used token.

Kind: instance method of OAuthClient
Returns: Promise - A promise that resolves with a new AccessToken object
Throws:

NotRegisteredException When the client doesn’t have it’s registration information
Error The client should already have an access token to use this function

oAuthClient.setToken(token)¶

Updates the client’s stored token

Kind: instance method of OAuthClient

Param	Type	Description
token	`string`	= null The new token to use — can be a string, a json object or an AccessToken instance.

oAuthClient.setOAuthOptions(options)¶

Updates the OAuth informations

Kind: instance method of OAuthClient

Param	Type	Description
options	`object`	Map of OAuth options

oAuthClient.resetClient()¶

Reset the current OAuth client

Kind: instance method of OAuthClient

oAuthClient.setPassphraseFlagship(params) ⇒ `object`¶

This method should be used in flagship app onboarding process to finalize the cozy creation by setting the user password into the cozy-stack

More info: https://docs.cozy.io/en/cozy-stack/settings/#post-settingspassphraseflagship

Kind: instance method of OAuthClient
Returns: object - token - The OAauth token

Param	Type	Description
params	`object`	parameters needed to set passphrase
params.registerToken	`string`	registration token provided by the onboarding link
params.passwordHash	`string`	hash of the master password
params.hint	`string`	hint for the master password
params.key	`string`	key (crypted) used for the vault encryption
params.publicKey	`string`	public key used for sharing ciphers from the vault
params.privateKey	`string`	private key (crypted) used for sharing ciphers from the vault
params.iterations	`string`	number of KDF iterations applied when hashing the master password

oAuthClient.checkForRevocation() ⇒ `Promise.<boolean>`¶

Check if the OAuth client’s has been revoked. If this is the case, call the onRevocationChange callback

Kind: instance method of OAuthClient
Returns: Promise.<boolean> - A Promise that resolves to false if client is still valid, or true if it has been revoked.

ArchivePages : `object`¶

Attributes used for create archive link by ids

Kind: global typedef
Properties

Name	Type	Description
id	`string`	Id of the file
page	`number`	The page number. PDF files only (1 is the first page)

FetchChangesReturnValue ⇒ `FetchChangesReturnValue`¶

Use cozy-stack’s _changes API for io.cozy.files Design docs are filtered by default, thus documents are retrieved in the response (includeDocs is set to true in the parameters of _changes). Deleted and trashed documents can be filtered on demand and files’ paths can be requested as well.

Since deleted and trashed documents are skipped by cozy-stack rather than CouchDB, when either option is set to true, the response can contain less documents than the defined limit. Thus one should rely solely on the pending result attribute to determine if more documents can be fetched or not.

You should use fetchChangesRaw to call CouchDB’s _changes API.

Kind: global typedef

Param	Type	Description
couchOptions	`CouchOptions`	Couch options for changes
options	`FetchChangesOptions`	Further options on the returned documents. By default, it is set to

Properties

Name	Type	Description
since	`string`	Bookmark telling CouchDB from which point in time should changes be returned
limit	`number`	The maximum number of returned documents for one call
includeDocs	`boolean`	Whether or not complete documents should be returned
fields	`Array.<string>`	The list of fields that should be returned for each document
includeFilePath	`boolean`	Whether to include the path of file changes (needs includeDocs to be true)
skipDeleted	`boolean`	Whether to skip changes for deleted documents
skipTrashed	`boolean`	Whether to skip changes for trashed documents (needs includeDocs to be true)
newLastSeq	`string`
pending	`boolean`
documents	`Array.<object>`

JobDocument : `object`¶

Document representing a io.cozy.jobs

Kind: global typedef
Properties

Name	Type	Description
_id	`string`	Id of the job
attributes.state	`string`	state of the job. Can be ‘errored’, ‘running’, ‘queued’, ‘done’
attributes.error	`string`	Error message of the job if any

MangoPartialFilter : `Object`¶

Kind: global typedef

MangoSelector : `object`¶

Kind: global typedef

MangoSort : `Array.<object>`¶

Kind: global typedef

MangoQueryOptions : `object`¶

Kind: global typedef
Properties

Name	Type	Description
[selector]	`MangoSelector`	Selector
[sort]	`MangoSort`	The sorting parameters
[fields]	`Array.<string>`	The fields to return
[partialFilterFields]	`Array.<string>`	The partial filter fields
[limit]	`number` \| `null`	For pagination, the number of results to return
[skip]	`number` \| `null`	For skip-based pagination, the number of referenced files to skip
[indexId]	`string` \| `null`	The _id of the CouchDB index to use for this request
[bookmark]	`string` \| `null`	For bookmark-based pagination, the document _id to start from
[indexedFields]	`Array.<string>`
[use_index]	`string`	Name of the index to use
[execution_stats]	`boolean`	If true, we request the stats from Couch
[partialFilter]	`MangoPartialFilter` \| `null`	An optional partial filter

DesignDoc : `object`¶

Attributes representing a design doc

Kind: global typedef
Properties

Name	Type	Description
_id	`string`	Id of the design doc. Can be named, e.g. ‘_design/by_indexed_attribute’ or not, e.g. ‘_design/12345’
language	`string`	The index language. Can be ‘query’ for mango index or ‘javascript’ for views.
views	`object`	Views definition, i.e. the index.
_rev	`string`	Rev version

SessionCode : `string`¶

Kind: global typedef

SessionCodeRes¶

Kind: global typedef
Properties

Name	Type	Description
session_code	`string`	The value of the session code

AccessTokenRes¶

Kind: global typedef
Properties

Name	Type	Description
email_verified_code	`string`	The email verified code to skip 2FA
access_token	`string`	The OAuth access token
refresh_token	`string`	The OAuth refresh token
token_type	`string`	The OAuth token type
scope	`string`	The OAuth scope

TwoFactorNeededRes¶

Kind: global typedef
Properties

Name	Type	Description
two_factor_token	`string`	The 2FA token

Permission ⇒ `Permission`¶

async getOwnPermissions - deprecated: please use fetchOwnPermissions instead

Kind: global typedef
Returns: Permission - permission

Permission ⇒ `Permission`¶

async fetchOwnPermissions - Fetches permissions

Kind: global typedef
Returns: Permission - permission

Rule : `object`¶

A sharing rule

Kind: global typedef
Properties

Name	Type
title	`string`
doctype	`string`
values	`Array`
[add]	`string`
[update]	`string`
[remove]	`string`

Recipient : `object`¶

An io.cozy.contact

Kind: global typedef

Sharing : `object`¶

An io.cozy.sharings document

Kind: global typedef

SharingPolicy : `object`¶

Define the add/update/remove policies for a sharing

Kind: global typedef
Properties

Name	Type
add	`string`
update	`string`
remove	`string`

SharingType : `undefined` | `'one-way'` | `'two-way'`¶

Define how a document is synced between sharing’s owner and receivers.

Kind: global typedef

RelationshipItem : `object`¶

Define a recipient that can be used as target of a sharing

Kind: global typedef
Properties

Name	Type	Description
id	`string`	Recipient’s ID
type	`string`	Reciptient’s type (should be ‘io.cozy.contacts’)

CozyStackClient : `object`¶

Kind: global typedef
Properties

Name	Type	Description
oauthOptions	`object`	oauthOptions
uri	`string`	CozyUri
fetch	`function`	fetchMethod
fetchJSON	`function`	fetchJSON

CozyStackClient : object
- .collection(doctype) ⇒ DocumentCollection
- .fetch(method, path, [body], [opts]) ⇒ object
- .refreshToken() ⇒ Promise
- .fetchJSON(method, path, body, options) ⇒ object
- .setToken(token)
- .getAccessToken() ⇒ string

cozyStackClient.collection(doctype) ⇒ `DocumentCollection`¶

Creates a DocumentCollection instance.

Kind: instance method of CozyStackClient

Param	Type	Description
doctype	`string`	The collection doctype.

cozyStackClient.fetch(method, path, [body], [opts]) ⇒ `object`¶

Fetches an endpoint in an authorized way.

Kind: instance method of CozyStackClient
Throws:

FetchError

Param	Type	Description
method	`string`	The HTTP method.
path	`string`	The URI.
[body]	`object`	The payload.
[opts]	`object`	Options for fetch

cozyStackClient.refreshToken() ⇒ `Promise`¶

Retrieves a new app token by refreshing the currently used token.

Kind: instance method of CozyStackClient
Returns: Promise - A promise that resolves with a new AccessToken object
Throws:

Error The client should already have an access token to use this function
Error The client couldn’t fetch a new token

cozyStackClient.fetchJSON(method, path, body, options) ⇒ `object`¶

Fetches JSON in an authorized way.

Kind: instance method of CozyStackClient
Throws:

FetchError

Param	Type	Description
method	`string`	The HTTP method.
path	`string`	The URI.
body	`object`	The payload.
options	`object`	Options

cozyStackClient.setToken(token)¶

Change or set the API token

Kind: instance method of CozyStackClient

Param	Type	Description
token	`string` \| `AppToken` \| `AccessToken`	Stack API token

cozyStackClient.getAccessToken() ⇒ `string`¶

Get the access token string, being an oauth token or an app token

Kind: instance method of CozyStackClient
Returns: string - token

Cozy Stack Client API

Classes¶

Constants¶

Functions¶

Typedefs¶

AppCollection¶

appCollection.all() ⇒ Object¶

AppsRegistryCollection¶

appsRegistryCollection.get(slug) ⇒ Promise.<{data: object}>¶

Collection¶

Collection.get(stackClient, endpoint, options) ⇒ Promise.<object>¶

CozyStackClient¶

cozyStackClient.collection(doctype) ⇒ DocumentCollection¶

cozyStackClient.fetch(method, path, [body], [opts]) ⇒ object¶

cozyStackClient.refreshToken() ⇒ Promise¶

cozyStackClient.fetchJSON(method, path, body, options) ⇒ object¶

cozyStackClient.setToken(token)¶

cozyStackClient.getAccessToken() ⇒ string¶

DocumentCollection¶

documentCollection.all(options) ⇒ Promise.<{data, meta, skip, bookmark, next}>¶

documentCollection.fetchDocumentsWithMango(path, selector, options)¶

documentCollection.findWithMango(path, selector, options) ⇒ Promise.<object>¶

documentCollection.find(selector, options) ⇒ Promise.<{data, skip, bookmark, next, execution_stats}>¶

documentCollection.findAll(selector, options) ⇒ Promise.<Array.<{data}>>¶

documentCollection.get(id) ⇒ Promise.<object>¶

documentCollection.getAll()¶

documentCollection.create(doc)¶

documentCollection.update(document)¶

documentCollection.destroy(doc)¶

documentCollection.updateAll(rawDocs)¶

documentCollection.destroyAll(docs)¶

documentCollection.toMangoOptions(selector, options) ⇒ MangoQueryOptions¶

documentCollection.createIndex(fields, indexOption) ⇒ Promise.<{id, fields}>¶

documentCollection.fetchAllMangoIndexes() ⇒ Promise.<Array.<DesignDoc>>¶

documentCollection.destroyIndex(index) ⇒ Promise.<object>¶

documentCollection.copyIndex(existingIndex, newIndexName) ⇒ Promise.<DesignDoc>¶

documentCollection.fetchChangesRaw(couchOptions)¶

DocumentCollection.normalizeDoctype(doctype) ⇒ function¶

FileCollection¶

fileCollection.forceFileDownload¶

fileCollection.get(id) ⇒ Object¶

fileCollection.getAll(ids) ⇒ Promise.<{data, meta, execution_stats}>¶

fileCollection.find(selector, options) ⇒ Promise.<{data, meta, skip, next, bookmark, execution_stats}>¶

fileCollection.findReferencedBy(document, options) ⇒ Promise.<{data, included, meta, skip, next}>¶

fileCollection.addReferencedBy(document, documents) ⇒ Promise.<{data, meta}>¶

fileCollection.removeReferencedBy(document, documents) ⇒ Promise.<{data, meta}>¶

fileCollection.addReferencesTo(document, documents)¶

fileCollection.removeReferencesTo(document, documents)¶

fileCollection.destroy(file) ⇒ Promise¶

fileCollection.emptyTrash()¶

fileCollection.restore(id) ⇒ Promise¶

fileCollection.copy(id, [name], [dirId]) ⇒ Promise.<object>¶

fileCollection.deleteFilePermanently(id) ⇒ Promise.<object>¶

fileCollection.upload(data, dirPath) ⇒ Promise.<object>¶

fileCollection.create(attributes)¶

fileCollection.updateFile(data, params) ⇒ object¶

fileCollection.download(file, versionId, filename)¶

fileCollection.fetchFileContentById(id)¶

fileCollection.getBeautifulSize(file, decimal)¶

fileCollection.downloadArchive(fileIds, [notSecureFilename], [options])¶

~~fileCollection.getArchiveLinkByIds()~~¶

fileCollection.createArchiveLinkByIds(params) ⇒ Promise.<string>¶

fileCollection.isChildOf(child, parent) ⇒ boolean¶

fileCollection.statById(id, options) ⇒ object¶

fileCollection.createDirectoryByPath(path) ⇒ object¶

fileCollection.createFileMetadata(attributes) ⇒ Promise.<object>¶

fileCollection.updateMetadataAttribute(id, metadata) ⇒ Promise.<object>¶

fileCollection.getFileTypeFromName(name) ⇒ string¶

fileCollection.doUpload(dataArg, path, options, method)¶

fileCollection.findNotSynchronizedDirectories(oauthClient, options) ⇒ Array.<(object|IOCozyFolder)>¶

fileCollection.addNotSynchronizedDirectories(oauthClient, directories)¶

fileCollection.removeNotSynchronizedDirectories(oauthClient, directories)¶

NotesCollection¶

notesCollection.get(id) ⇒ Object¶

notesCollection.all() ⇒ Object¶

notesCollection.destroy(note) ⇒ Object¶

notesCollection.create(options) ⇒ Object¶

notesCollection.fetchURL(note) ⇒ Object¶

notesCollection.getDefaultSchema() ⇒ object¶

OAuthClient¶

appCollection.all() ⇒ `Object`¶

appsRegistryCollection.get(slug) ⇒ `Promise.<{data: object}>`¶

Collection.get(stackClient, endpoint, options) ⇒ `Promise.<object>`¶

cozyStackClient.collection(doctype) ⇒ `DocumentCollection`¶

cozyStackClient.fetch(method, path, [body], [opts]) ⇒ `object`¶

cozyStackClient.refreshToken() ⇒ `Promise`¶

cozyStackClient.fetchJSON(method, path, body, options) ⇒ `object`¶

cozyStackClient.getAccessToken() ⇒ `string`¶

documentCollection.all(options) ⇒ `Promise.<{data, meta, skip, bookmark, next}>`¶

documentCollection.findWithMango(path, selector, options) ⇒ `Promise.<object>`¶

documentCollection.find(selector, options) ⇒ `Promise.<{data, skip, bookmark, next, execution_stats}>`¶

documentCollection.findAll(selector, options) ⇒ `Promise.<Array.<{data}>>`¶

documentCollection.get(id) ⇒ `Promise.<object>`¶

documentCollection.toMangoOptions(selector, options) ⇒ `MangoQueryOptions`¶

documentCollection.createIndex(fields, indexOption) ⇒ `Promise.<{id, fields}>`¶

documentCollection.fetchAllMangoIndexes() ⇒ `Promise.<Array.<DesignDoc>>`¶

documentCollection.destroyIndex(index) ⇒ `Promise.<object>`¶

documentCollection.copyIndex(existingIndex, newIndexName) ⇒ `Promise.<DesignDoc>`¶

DocumentCollection.normalizeDoctype(doctype) ⇒ `function`¶

fileCollection.get(id) ⇒ `Object`¶

fileCollection.getAll(ids) ⇒ `Promise.<{data, meta, execution_stats}>`¶

fileCollection.find(selector, options) ⇒ `Promise.<{data, meta, skip, next, bookmark, execution_stats}>`¶

fileCollection.findReferencedBy(document, options) ⇒ `Promise.<{data, included, meta, skip, next}>`¶

fileCollection.addReferencedBy(document, documents) ⇒ `Promise.<{data, meta}>`¶

fileCollection.removeReferencedBy(document, documents) ⇒ `Promise.<{data, meta}>`¶

fileCollection.destroy(file) ⇒ `Promise`¶

fileCollection.restore(id) ⇒ `Promise`¶

fileCollection.copy(id, [name], [dirId]) ⇒ `Promise.<object>`¶

fileCollection.deleteFilePermanently(id) ⇒ `Promise.<object>`¶

fileCollection.upload(data, dirPath) ⇒ `Promise.<object>`¶

fileCollection.updateFile(data, params) ⇒ `object`¶

fileCollection.getArchiveLinkByIds()¶

fileCollection.createArchiveLinkByIds(params) ⇒ `Promise.<string>`¶

fileCollection.isChildOf(child, parent) ⇒ `boolean`¶

fileCollection.statById(id, options) ⇒ `object`¶

fileCollection.createDirectoryByPath(path) ⇒ `object`¶

fileCollection.createFileMetadata(attributes) ⇒ `Promise.<object>`¶

fileCollection.updateMetadataAttribute(id, metadata) ⇒ `Promise.<object>`¶

fileCollection.getFileTypeFromName(name) ⇒ `string`¶

fileCollection.findNotSynchronizedDirectories(oauthClient, options) ⇒ `Array.<(object|IOCozyFolder)>`¶

notesCollection.get(id) ⇒ `Object`¶

notesCollection.all() ⇒ `Object`¶

notesCollection.destroy(note) ⇒ `Object`¶

notesCollection.create(options) ⇒ `Object`¶

notesCollection.fetchURL(note) ⇒ `Object`¶

notesCollection.getDefaultSchema() ⇒ `object`¶

oAuthClient.register() ⇒ `Promise`¶

oAuthClient.unregister() ⇒ `Promise`¶

oAuthClient.fetchInformation() ⇒ `Promise`¶

oAuthClient.updateInformation(information, resetSecret) ⇒ `Promise`¶

oAuthClient.generateStateCode() ⇒ `string`¶

oAuthClient.getAuthCodeURL(options) ⇒ `string`¶

oAuthClient.getAccessCodeFromURL(pageURL, stateCode) ⇒ `string`¶

oAuthClient.fetchAccessToken(accessCode, oauthOptionsArg, uri, codeVerifier) ⇒ `Promise`¶

oAuthClient.fetchKonnectorToken(slug) ⇒ `Promise.<string>`¶

oAuthClient.fetchSessionCode() ⇒ `Promise.<SessionCodeRes>`¶

oAuthClient.fetchSessionCodeWithPassword() ⇒ `Promise.<SessionCodeRes>`¶

oAuthClient.loginFlagship() ⇒ `Promise.<(AccessTokenRes|TwoFactorNeededRes|SessionCodeRes)>`¶

oAuthClient.refreshToken() ⇒ `Promise`¶

oAuthClient.setPassphraseFlagship(params) ⇒ `object`¶

oAuthClient.checkForRevocation() ⇒ `Promise.<boolean>`¶

oAuthClientsCollection.all(options) ⇒ `object`¶

oAuthClientsCollection.get(id) ⇒ `object`¶

oAuthClientsCollection.destroy(oauthClient) ⇒ `Object`¶

permissionCollection.add(document, permission) ⇒ `Promise`¶

permissionCollection.findApps()¶

permissionCollection.fetchAllLinks(document) ⇒ `object`¶

promiseCache.pending : `Object.<string, Promise>`¶

promiseCache.exec(promiseFunc, keyFunc) ⇒ `Promise.<T>`¶

promiseCache.get(keyFunc) ⇒ `Promise` | `null`¶

settingsCollection.get(id) ⇒ `object`¶

sharingCollection.get(id) ⇒ `Sharing`¶

sharingCollection.share(document, recipients, sharingType, description, [previewPath])¶

sharingCollection.getDiscoveryLink(sharingId, sharecode) ⇒ `string`¶

triggerCollection.all(options) ⇒ `Object`¶

triggerCollection.create(attributes) ⇒ `object`¶

triggerCollection.destroy(document) ⇒ `object`¶

triggerCollection.find(selector, options) ⇒ `Object`¶

triggerCollection.launch(trigger) ⇒ `object`¶

triggerCollection.update(trigger) ⇒ `object`¶