Classes

AppCollection

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

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

OAuthClient

Specialized CozyStackClient for mobile, implementing stack registration through OAuth.

PermissionCollection

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

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.

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

getCozyURL()

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

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:

CozyStackClient

Main API against the cozy-stack server.

Kind: global class

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, options) ⇒ Object

Fetches an endpoint in an authorized way.

Kind: instance method of CozyStackClient
Throws:

Param Type Description
method String The HTTP method.
path String The URI.
body Object The payload.
options Object

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:

cozyStackClient.fetchJSON(method, path, body, options) ⇒ Object

Fetches JSON in an authorized way.

Kind: instance method of CozyStackClient
Throws:

Param Type Description
method String The HTTP method.
path String The URI.
body Object The payload.
options Object

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

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:

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:

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

documentCollection.getIndexFields(options) ⇒ Array

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

Kind: instance method of DocumentCollection
Returns: Array - - Fields to index

Param Type Description
options Object Mango query options

documentCollection.fetchChanges(couchOptions, options)

Use Couch _changes API

Kind: instance method of DocumentCollection

Param Type Description
couchOptions Object Couch options for changes https://kutt.it/5r7MNQ
options Object

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

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

fileCollection.findReferencedBy(document, {, limit) ⇒ 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.
{ number skip = 0 For pagination, the number of referenced files to skip
limit number } For pagination, the number of results to return.

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:

Param Type Description
id string The file’s id

fileCollection.updateFile(data, params) ⇒ object

updateFile - Updates a file’s data

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

Param Type Description
data object Javascript File object
params object Additional parameters
params.fileId string The id of the file to update (required)
params.executable boolean Whether the file is executable or not
params.options object Options to pass to doUpload method (additional headers)

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

fileCollection.updateFileMetadata(id, attributes) ⇒ object

async updateFileMetadata - Updates a file’s metadata

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

Param Type Description
id string File id
attributes object New file meta data

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

OAuthClient

Specialized CozyStackClient for mobile, implementing stack registration through OAuth.

Kind: global class

oAuthClient.register() ⇒ promise

Registers the currenly configured client with the OAuth server.

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:

oAuthClient.unregister() ⇒ promise

Unregisters the currenly configured client with the OAuth server.

Kind: instance method of OAuthClient
Throws:

oAuthClient.fetchInformation() ⇒ promise

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

Kind: instance method of OAuthClient
Throws:

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 - A promise that resolves to a complete, updated list of client information
Throws:

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:

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:

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, oauthOptions, 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:

Param Type Description
accessCode string The access code contained in the redirection URL — see client.getAccessCodeFromURL()
oauthOptions 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:

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

PermissionCollection

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

Kind: global class

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
document object
permission object

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

async getOwnPermissions - Gets the permission for the current token

Kind: instance method of PermissionCollection

SharingCollection

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

Kind: global class

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

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

Kind: instance method of SharingCollection

Param Type Default Description
document object The document to share. Should have and _id and a name.
recipients array A list of io.cozy.contacts
sharingType string
description string
[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
sharingId string
sharecode string

TriggerCollection

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

Kind: global class

triggerCollection.all(options) ⇒ Object

Get the list of triggers.

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

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.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 to launch

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

getCozyURL()

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

Kind: global function