cozy-stack-client.md

Classes

AppCollection

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

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.

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 ⇒ boolean

Helper to identify an index not found error

isIndexConflictError ⇒ boolean

Helper to identify an index conflict

isNoUsableIndexError ⇒ boolean

Helper to identify a no usable index error

isDocumentUpdateConflict ⇒ boolean

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

getIndexFields ⇒ Array

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

isInconsistentIndex ⇒ boolean

Check if an index is in an inconsistent state, i.e. its name contains the indexed attributes which are not in correct order.

isMatchingIndex ⇒ boolean

Check if an index is matching the given fields

getPermissionsFor ⇒ object

Build a permission set

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

Functions

getAccessToken() ⇒ string

Get the access token string

getAccessToken() ⇒ string

Get the app token string

garbageCollect()

Delete outdated results from cache

memoize()

Memoize with maxDuration and custom key

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

Typedefs

CouchOptionsRaw : object

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

FetchChangesReturnValue ⇒ 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.

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

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

DesignDoc : object

Attributes representing a design doc

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

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

Collection

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

Kind: global class

Collection.get(stackClient, endpoint, options) ⇒ object

Utility method aimed to return only one document.

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

Param	Type	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	HTTP method (default GET)

CozyStackClient

Main API against the cozy-stack server.

Kind: global class

• CozyStackClient
  • .collection(doctype) ⇒ DocumentCollection
  • .fetch(method, path, body, opts) ⇒ object
  • .checkForRevocation()
  • .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.checkForRevocation()

Returns whether the client has been revoked on the server

Kind: instance method of CozyStackClient

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
  • .all(options) ⇒ Object
  • .find(selector, options) ⇒ Object
  • .get(id) ⇒ object
  • .getAll()
  • .create(doc)
  • .update(document)
  • .destroy(doc)
  • .updateAll(docs)
  • .destroyAll(docs)
  • .fetchAllMangoIndexes() ⇒ Array
  • .destroyIndex(index) ⇒ object
  • .copyIndex(existingIndex, newIndexName) ⇒ object

documentCollection.all(options) ⇒ Object

Lists all documents of the collection, without filters.

The returned documents are paginated by the stack.

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

• FetchError

Param	Type	Description
options	Object	The fetch options: pagination & fetch of specific docs.

documentCollection.find(selector, options) ⇒ Object

Returns a filtered list of documents using a Mango selector.

The returned documents are paginated by the stack.

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

• FetchError

Param	Type	Description
selector	object	The Mango selector.
options	Object	The query options.

documentCollection.get(id) ⇒ object

Get a document by id

Kind: instance method of DocumentCollection
Returns: 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(docs)

Updates several documents in one batch

Kind: instance method of DocumentCollection

Param	Type	Description
docs	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.fetchAllMangoIndexes() ⇒ Array

Retrieve all design docs of mango indexes

Kind: instance method of DocumentCollection
Returns: Array - The design docs

documentCollection.destroyIndex(index) ⇒ object

Delete the specified design doc

Kind: instance method of DocumentCollection
Returns: object - The delete response

Param	Type	Description
index	object	The design doc to remove

documentCollection.copyIndex(existingIndex, newIndexName) ⇒ object

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: object - The copy response

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

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
  • .find(selector, options) ⇒ Object
  • .findReferencedBy(document, options) ⇒ Object
  • .addReferencedBy(document, documents) ⇒ Object
  • .removeReferencedBy(document, documents) ⇒ Object
  • .addReferencesTo(document, documents) ⇒
  • .removeReferencesTo(document, documents) ⇒
  • .destroy(file) ⇒ Promise
  • .emptyTrash()
  • .restore(id) ⇒ Promise
  • .deleteFilePermanently(id) ⇒ object
  • .upload(data, dirPath) ⇒ object
  • .create(attributes)
  • .updateFile(data, params) ⇒ object
  • .download(file, versionId, filename)
  • .fetchFileContentById(id)
  • .getBeautifulSize(file, decimal)
  • .isChildOf(child, parent) ⇒ boolean
  • .statById(id, [options]) ⇒ object
  • .createDirectoryByPath(path) ⇒ object
  • .createFileMetadata(attributes) ⇒ object
  • .updateMetadataAttribute(id, metadata) ⇒ 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.find(selector, options) ⇒ Object

Returns a filtered list of documents using a Mango selector.

The returned documents are paginated by the stack.

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

• FetchError

Param	Type	Description
selector	object	The Mango selector.
options	Object	The query options.

fileCollection.findReferencedBy(document, options) ⇒ Object

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: Object - 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	For skip-based pagination, the number of referenced files to skip.
options.limit	number	For pagination, the number of results to return.
options.cursor	object	For cursor-based pagination, the index cursor.

fileCollection.addReferencedBy(document, documents) ⇒ Object

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: Object - 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) ⇒ Object

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: Object - 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
Returns: 204 No Content

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.

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
Returns: 204 No Content

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.

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.deleteFilePermanently(id) ⇒ object

async deleteFilePermanently - Definitely delete a file

Kind: instance method of FileCollection
Returns: object - The deleted file object

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

fileCollection.upload(data, dirPath) ⇒ object

Kind: instance method of FileCollection
Returns: 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.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	Default	Description
id	string		ID of the document
[options]	object	{}	Description
[options.page[limit]]	number		Max number of children documents to return
[options.page[skip]]	number		Number of children documents to skip from the start
[options.page[cursor]]	string		A cursor id for pagination

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) ⇒ 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: object - The Metadata object

Param	Type	Description
attributes	object	The file's metadata

fileCollection.updateMetadataAttribute(id, metadata) ⇒ 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: 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	Additional options
options.skip	number	For skip-based pagination, the number of referenced files to skip.
options.limit	number	For pagination, the number of results to return.
options.cursor	object	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
Returns: 204 No Content

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.

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
Returns: 204 No Content

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.

NotesCollection

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

Kind: global class

• NotesCollection
  • .all() ⇒ Object
  • .destroy(note) ⇒ Object
  • .create(option) ⇒ Object
  • .fetchURL(note) ⇒ Object
  • .getDefaultSchema() ⇒ object

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	io.cozy.notes	The note document to destroy
note._id	string	The note's id

notesCollection.create(option) ⇒ Object

Create a note

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

Param	Type	Description
option	object
option.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	io.cozy.notes	The note 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(stateCode, scopes) ⇒ string
  • .getAccessCodeFromURL(pageURL, stateCode) ⇒ string
  • .fetchAccessToken(accessCode, oauthOptionsArg, uri) ⇒ Promise
  • .refreshToken() ⇒ Promise
  • .setToken(token)
  • .setOAuthOptions(options)
  • .resetClient()

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(stateCode, scopes) ⇒ 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
stateCode	string	A random code to be included in the URl for security. Can be generated with client.generateStateCode()
scopes	Array	= [] An array of permission scopes for the token.

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) ⇒ 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)

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

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	object	For cursor-based pagination, the index cursor.
options.keys	Array	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	io.cozy.oauth.clients	The client 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
  • .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.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.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
document	object

SettingsCollection

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

Kind: global class

settingsCollection.get(path) ⇒ 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
path	string	The setting route to call, eg instance or context

SharingCollection

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

Kind: global class

• SharingCollection
  • .get(id) ⇒ Sharing
  • .create(params)
  • .share(document, recipients, sharingType, description, [previewPath])
  • .getDiscoveryLink(sharingId, sharecode) ⇒ string
  • .addRecipients(options)
  • .revokeRecipient(sharing, recipientIndex)
  • .revokeSelf(sharing)
  • .revokeAllRecipients(sharing)

sharingCollection.get(id) ⇒ Sharing

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	object	Sharing Object
recipientIndex	number	Index of this recipient in the members array of the sharing

sharingCollection.revokeSelf(sharing)

Remove self from the sharing.

Kind: instance method of SharingCollection

Param	Type	Description
sharing	object	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	object	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

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 cozy/cozy-stack#2010

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

• FetchError

Param	Type	Description
selector	object	Which kind of worker {konnector,service}
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

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	Data to return in case of "not found" error

isIndexNotFoundError ⇒ boolean

Helper to identify an index not found error

Kind: global constant
Returns: boolean - - Whether or not the error is an index not found error

Param	Type	Description
error	Error	An error

isIndexConflictError ⇒ boolean

Helper to identify an index conflict

Kind: global constant
Returns: boolean - - Whether or not the error is an index conflict error

Param	Type	Description
error	Error	An error

isNoUsableIndexError ⇒ boolean

Helper to identify a no usable index error

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

Param	Type	Description
error	Error	An error

isDocumentUpdateConflict ⇒ boolean

Helper to identify a document conflict

Kind: global constant
Returns: boolean - - 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
type	string	The type of the file
_type	string	The _type of the file

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
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

getIndexFields ⇒ Array

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

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

Param	Type	Description
options	object	Mango query options

isInconsistentIndex ⇒ boolean

Check if an index is in an inconsistent state, i.e. its name contains the indexed attributes which are not in correct order.

Kind: global constant
Returns: boolean - True if the index is inconsistent

Param	Type	Description
index	DesignDoc	The index to check

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

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

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

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

garbageCollect()

Delete outdated results from cache

Kind: global function

memoize()

Memoize with maxDuration and custom key

Kind: global function

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

CouchOptionsRaw : object

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

Kind: global typedef
See: https://docs.couchdb.org/en/stable/api/database/changes.html

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

FetchChangesReturnValue ⇒ 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
since	string	Bookmark telling CouchDB from which point in time should changes be returned
doc_ids	Array.<string>	Only return changes for a subset of documents
couchOptions	CouchOptions	Couch options for changes
options	FetchChangesOptions	Further options on the returned documents. By default, it is set to { includeDesign: false, includeDeleted: false }

Properties

Name	Type	Description
includeDesign	boolean	Whether to include changes from design docs (needs include_docs to be true)
includeDeleted	boolean	Whether to include changes for deleted documents (needs include_docs to be true)
newLastSeq	string
documents	Array.<object>

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.

FileAttributes : object

Attributes used for file creation

Kind: global typedef
Properties

Name	Type	Description
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
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
attributes	FileAttributes	Attributes of the file

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(stateCode, scopes) ⇒ string
  • .getAccessCodeFromURL(pageURL, stateCode) ⇒ string
  • .fetchAccessToken(accessCode, oauthOptionsArg, uri) ⇒ Promise
  • .refreshToken() ⇒ Promise
  • .setToken(token)
  • .setOAuthOptions(options)
  • .resetClient()

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(stateCode, scopes) ⇒ 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
stateCode	string	A random code to be included in the URl for security. Can be generated with client.generateStateCode()
scopes	Array	= [] An array of permission scopes for the token.

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) ⇒ 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)

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

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 { includeFilePath: false, skipDeleted: false, skipTrashed: false }

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

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.

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')