

cozy-client

cozy-client¶

Namespaces¶

Classes¶

Properties¶

RealTimeQueries¶

• RealTimeQueries: MemoExoticComponent<(options: { doctype: string }) => null>

Variables¶

MutationTypes¶

• Const MutationTypes: Object

Type declaration

Name	Type
`ADD_REFERENCED_BY`	`string`
`ADD_REFERENCES_TO`	`string`
`CREATE_DOCUMENT`	`string`
`DELETE_DOCUMENT`	`string`
`REMOVE_REFERENCED_BY`	`string`
`REMOVE_REFERENCES_TO`	`string`
`UPDATE_DOCUMENT`	`string`
`UPDATE_DOCUMENTS`	`string`
`UPLOAD_FILE`	`string`

Defined in

packages/cozy-client/src/queries/dsl.js:510

Mutations¶

• Const Mutations: Object

Type declaration

Name	Type
`addReferencedBy`	(`document`: `any`, `referencedDocuments`: `any`) => { `document`: `any` ; `mutationType`: `string` = MutationTypes.ADD_REFERENCED_BY; `referencedDocuments`: `any` }
`addReferencesTo`	(`document`: `any`, `referencedDocuments`: `any`) => { `document`: `any` ; `mutationType`: `string` = MutationTypes.ADD_REFERENCES_TO; `referencedDocuments`: `any` }
`createDocument`	(`document`: `any`) => { `document`: `any` ; `mutationType`: `string` = MutationTypes.CREATE_DOCUMENT }
`deleteDocument`	(`document`: `any`) => { `document`: `any` ; `mutationType`: `string` = MutationTypes.DELETE_DOCUMENT }
`removeReferencedBy`	(`document`: `any`, `referencedDocuments`: `any`) => { `document`: `any` ; `mutationType`: `string` = MutationTypes.REMOVE_REFERENCED_BY; `referencedDocuments`: `any` }
`removeReferencesTo`	(`document`: `any`, `referencedDocuments`: `any`) => { `document`: `any` ; `mutationType`: `string` = MutationTypes.REMOVE_REFERENCES_TO; `referencedDocuments`: `any` }
`updateDocument`	(`document`: `any`) => { `document`: `any` ; `mutationType`: `string` = MutationTypes.UPDATE_DOCUMENT }
`updateDocuments`	(`documents`: `any`) => { `documents`: `any` ; `mutationType`: `string` = MutationTypes.UPDATE_DOCUMENTS }
`uploadFile`	(`file`: `any`, `dirPath`: `any`) => { `dirPath`: `any` ; `file`: `any` ; `mutationType`: `string` = MutationTypes.UPLOAD_FILE }

Defined in

packages/cozy-client/src/queries/dsl.js:498

defaultPerformanceApi¶

• Const defaultPerformanceApi: PerformanceAPI

Defined in

packages/cozy-client/src/performances/defaultPerformanceApi.js:2

fetchPolicies¶

• Const fetchPolicies: Object

Use those fetch policies with <Query /> to limit the number of re-fetch.

example

import { fetchPolicies } from 'cozy-client'
const olderThan30s = fetchPolicies.olderThan(30 * 1000)
<Query fetchPolicy={olderThan30s} />

Type declaration

Name	Type
`noFetch`	() => `boolean`
`olderThan`	(`delay`: `number`) => `Function`

Defined in

packages/cozy-client/src/policies.js:11

useMutation¶

• Const useMutation: Object

Call signature¶

▸ (__namedParameters?): UseMutationReturnValue

This hook manages the state during the saving of a document

Parameters

Name	Type
`__namedParameters`	`Object`
`__namedParameters.onError`	`any`
`__namedParameters.onSuccess`	`any`

Returns

UseMutationReturnValue

Type declaration

Name	Type
`propTypes`	{ `onError`: `Requireable`<(…`args`: `any`[]) => `any`> = PropTypes.func; `onSuccess`: `Requireable`<(…`args`: `any`[]) => `any`> = PropTypes.func }
`propTypes.onError`	`Requireable`<(…`args`: `any`[]) => `any`>
`propTypes.onSuccess`	`Requireable`<(…`args`: `any`[]) => `any`>

Defined in

packages/cozy-client/src/hooks/useMutation.jsx:11

webPerformanceApi¶

• Const webPerformanceApi: PerformanceAPI

Defined in

packages/cozy-client/src/performances/webPerformanceApi.js:42

Functions¶

Q¶

▸ Q(doctype): QueryDefinition

Helper to create a QueryDefinition. Recommended way to create query definitions.

example

import { Q } from 'cozy-client'

const qDef = Q('io.cozy.todos').where({ _id: '1234' })

Parameters

Name	Type	Description
`doctype`	`string`	Doctype of the query definition

Returns

QueryDefinition

Defined in

packages/cozy-client/src/queries/dsl.js:394

cancelable¶

▸ cancelable(promise): CancelablePromise

Wraps a promise so that it can be canceled

Rejects with canceled: true as soon as cancel is called

Parameters

Name	Type	Description
`promise`	`Promise`<`any`>	Promise

Returns

CancelablePromise

Promise with .cancel method

Defined in

packages/cozy-client/src/utils.js:16

createFakeClient¶

▸ createFakeClient(options?): CozyClient

Creates a client with pre-filled store This can be useful for demo in documentation (e.g. storybook)

client.{query,save} are replaced with empty functions
client.stackClient.fetchJSON is replaced with empty functions

Parameters

Name	Type	Description
`options`	`Object`	Options
`options.clientFunctions`	`any`	-
`options.clientOptions`	`any`	-
`options.queries`	`any`	-
`options.remote`	`any`	-

Returns

CozyClient

Defined in

packages/cozy-client/src/mock.js:92

createMockClient¶

▸ createMockClient(options?): CozyClient

Creates a client suitable for use in tests

client.{query,save} are mocked
client.stackClient.fetchJSON is mocked

Parameters

Name	Type	Description
`options`	`Object`	Options
`options.clientFunctions`	`any`	-
`options.clientOptions`	`any`	-
`options.queries`	`any`	-
`options.remote`	`any`	-

Returns

CozyClient

Defined in

packages/cozy-client/src/mock.js:48

deconstructCozyWebLinkWithSlug¶

▸ deconstructCozyWebLinkWithSlug(webLink, subDomainType?): CozyLinkData

Deconstruct the given link in order to retrieve useful data like Cozy’s name, domain, or slug

The given link MUST contain a slug

Parameters

Name	Type	Default value	Description
`webLink`	`string`	`undefined`	link to deconstruct. It should be a link from a Cozy and containing a slug
`subDomainType`	`SubdomainType`	`'flat'`	-

Returns

CozyLinkData

Deconstructed link

Defined in

packages/cozy-client/src/helpers/urlHelper.js:64

deconstructRedirectLink¶

▸ deconstructRedirectLink(redirectLink): RedirectLinkData

Deconstruct the given redirect link in order to retrieve slug, pathname and hash

throws {InvalidRedirectLinkError} Thrown when redirect link is invalid

Parameters

Name	Type	Description
`redirectLink`	`string`	redirect link to deconstruct (i.e. ‘drive/public/#/folder/SOME_ID’)

Returns

RedirectLinkData

Deconstructed link

Defined in

packages/cozy-client/src/helpers/urlHelper.js:106

dehydrate¶

▸ dehydrate(document): Object

Parameters

Name	Type
`document`	`any`

Returns

Object

Defined in

packages/cozy-client/src/helpers/dehydrateHelper.js:3

dispatchCreate¶

▸ dispatchCreate(client, doctype, couchDBDoc, options?): Promise<void>

Dispatches a create action for a document to update CozyClient store from realtime callbacks.

Parameters

Name	Type	Description
`client`	`any`	CozyClient instance
`doctype`	`string`	Doctype of the document to create
`couchDBDoc`	`CouchDBDocument`	Document to create
`options`	`DispatchOptions`	-

Returns

Promise<void>

Defined in

packages/cozy-client/src/store/realtime.js:76

dispatchDelete¶

▸ dispatchDelete(client, doctype, couchDBDoc, options?): Promise<void>

Dispatches a delete action for a document to update CozyClient store from realtime callbacks.

Parameters

Name	Type	Description
`client`	`any`	CozyClient instance
`doctype`	`string`	Doctype of the document to create
`couchDBDoc`	`CouchDBDocument`	Document to create
`options`	`DispatchOptions`	-

Returns

Promise<void>

Defined in

packages/cozy-client/src/store/realtime.js:120

dispatchUpdate¶

▸ dispatchUpdate(client, doctype, couchDBDoc, options?): Promise<void>

Dispatches a update action for a document to update CozyClient store from realtime callbacks.

Parameters

Name	Type	Description
`client`	`any`	CozyClient instance
`doctype`	`string`	Doctype of the document to create
`couchDBDoc`	`CouchDBDocument`	Document to create
`options`	`DispatchOptions`	-

Returns

Promise<void>

Defined in

packages/cozy-client/src/store/realtime.js:98

ensureFirstSlash¶

▸ ensureFirstSlash(path): any

Parameters

Name	Type
`path`	`any`

Returns

any

Defined in

packages/cozy-client/src/helpers/urlHelper.js:1

generateWebLink¶

▸ generateWebLink(options): string

generateWebLink - Construct a link to a web app

This function does not get its cozy url from a CozyClient instance so it can be used to build urls that point to other Cozies than the user’s own Cozy. This is useful when pointing to the Cozy of the owner of a shared note for example.

Parameters

Name	Type	Description
`options`	`Object`	Object of options
`options.cozyUrl`	`string`	Base URL of the cozy, eg. cozy.tools or test.mycozy.cloud
`options.hash`	`string`	-
`options.pathname`	`string`	-
`options.searchParams`	`any`[]	-
`options.slug`	`string`	-
`options.subDomainType`	`string`	-

Returns

string

Generated URL

Defined in

packages/cozy-client/src/helpers/urlHelper.js:27

getDoctypeFromOperation¶

▸ getDoctypeFromOperation(operation): any

Parameters

Name	Type
`operation`	`any`

Returns

any

Defined in

packages/cozy-client/src/queries/dsl.js:474

getQueryFromState¶

▸ getQueryFromState(state, queryId): any

Parameters

Name	Type
`state`	`any`
`queryId`	`any`

Returns

any

Defined in

packages/cozy-client/src/store/stateHelpers.js:15

getReferencedBy¶

▸ getReferencedBy(file, referencedBy): Reference[]

Get array of reference by an specific doctype

Parameters

Name	Type	Description
`file`	`IOCozyFile`	io.cozy.files document
`referencedBy`	`string`	Doctype where document is referenced

Returns

Reference[]

Array of references found

Defined in

packages/cozy-client/src/associations/helpers.js:133

getReferencedById¶

▸ getReferencedById(file, referencedBy, referencedId): Reference[]

Get array of reference by an specific doctype and a specific Id of that reference

Parameters

Name	Type	Description
`file`	`IOCozyFile`	io.cozy.files document
`referencedBy`	`string`	Doctype where document is referenced
`referencedId`	`string`	Id of the referenced document

Returns

Reference[]

Array of the reference found

Defined in

packages/cozy-client/src/associations/helpers.js:147

hasQueriesBeenLoaded¶

▸ hasQueriesBeenLoaded(queriesResults): boolean

Returns whether queries have been loaded at least once

Parameters

Name	Type
`queriesResults`	`any`

Returns

boolean

Defined in

packages/cozy-client/src/utils.js:66

hasQueryBeenLoaded¶

▸ hasQueryBeenLoaded(col): any

Returns whether a query has been loaded at least once

Parameters

Name	Type
`col`	`any`

Returns

any

Defined in

packages/cozy-client/src/utils.js:50

isQueriesLoading¶

▸ isQueriesLoading(queriesResults): boolean

Returns whether the result of queries are loading

Parameters

Name	Type
`queriesResults`	`any`

Returns

boolean

Defined in

packages/cozy-client/src/utils.js:57

isQueryLoading¶

▸ isQueryLoading(col): boolean

Returns whether the result of a query (given via queryConnect or Query) is loading.

Parameters

Name	Type
`col`	`any`

Returns

boolean

Defined in

packages/cozy-client/src/utils.js:39

isReferencedBy¶

▸ isReferencedBy(file, referencedBy): boolean

Checks if the file is referenced by a specific doctype

Parameters

Name	Type	Description
`file`	`IOCozyFile`	io.cozy.files document
`referencedBy`	`string`	Doctype where document is referenced

Returns

boolean

If a reference is found

Defined in

packages/cozy-client/src/associations/helpers.js:101

isReferencedById¶

▸ isReferencedById(file, referencedBy, referencedId): boolean

Checks if the file is referenced by a specific doctype and a specific Id of that reference

Parameters

Name	Type	Description
`file`	`IOCozyFile`	io.cozy.files document
`referencedBy`	`string`	Doctype where document is referenced
`referencedId`	`string`	Id of the referenced document

Returns

boolean

If a reference is found

Defined in

packages/cozy-client/src/associations/helpers.js:116

queryConnect¶

▸ queryConnect(querySpecs): Function

function

description HOC creator to connect component to several queries in a declarative manner

Parameters

Name	Type	Description
`querySpecs`	`any`	Definition of the queries

Returns

Function

HOC to apply to a component

Defined in

packages/cozy-client/src/hoc.jsx:74

queryConnectFlat¶

▸ queryConnectFlat(querySpecs): Function

function

description HOC creator to connect component to several queries in a declarative manner The only difference with queryConnect is that it does not wrap the component in N component if there are N queries, only 1 extra level of nesting is introduced.

Parameters

Name	Type	Description
`querySpecs`	`any`	Definition of the queries

Returns

Function

HOC to apply to a component

Defined in

packages/cozy-client/src/hoc.jsx:90

rootCozyUrl¶

▸ rootCozyUrl(url): Promise<URL>

rootCozyUrl - Get the root URL of a Cozy from more precise ones

The goal is to allow users to use any URL copied from their browser as their Cozy URL rather than trying to explain to them what we expect (e.g. when requesting the Cozy URL to connect an app). If we can’t get the root URL either because there’s no Cozy or the domain does not exist or anything else, we’ll throw an InvalidCozyUrlError. Also, since we communicate only via HTTP or HTTPS, we’ll throw an InvalidProtocolError if any other protocol is used.

This function expects a fully qualified URL thus with a protocol and a valid hostname. If your application accepts Cozy intances as input (e.g. claude when the Cozy can be found at https://claude.mycozy.cloud), it is your responsibility to add the appropriate domain to the hostname before calling this function.

Examples:

getting the root URL when your user gives you its instance name

const userInput = ‘claude’ const rootUrl = await rootCozyUrl(new URL(https://${userInput}.mycozy.cloud)) // → returns new URL(‘https://claude.mycozy.cloud’)

getting the root URL when your user gives you a Cozy Drive URL

const userInput = ‘https://claude-drive.mycozy.cloud/#/folder/io.cozy.files.root-dir’ const rootUrl = await rootCozyUrl(new URL(userInput)) // → returns new URL(‘https://claude.mycozy.cloud’)

getting the root URL when the Cozy uses nested sub-domains

const userInput = ‘http://photos.camille.nimbus.com:8080/#/album/1234567890’ const rootCozyUrl = await rootCozyUrl(new URL(userInput)) // → returns new URL(‘http://camille.nimbus.com:8080’)

Parameters

Name	Type	Description
`url`	`URL`	The URL from which we’ll try to get the root Cozy URL

Returns

Promise<URL>

The root Cozy URL

Defined in

packages/cozy-client/src/helpers/urlHelper.js:268

useAppLinkWithStoreFallback¶

▸ useAppLinkWithStoreFallback(slug, client, path?): Object

Parameters

Name	Type	Default value
`slug`	`any`	`undefined`
`client`	`any`	`undefined`
`path`	`string`	`''`

Returns

Object

Name	Type
`fetchStatus`	`string`
`isInstalled`	`boolean`
`url`	`any`

Defined in

packages/cozy-client/src/hooks/useAppLinkWithStoreFallback.jsx:9

useAppsInMaintenance¶

▸ useAppsInMaintenance(): "io.cozy.apps"[]

Returns all apps in maintenance

Returns

"io.cozy.apps"[]

An array with all apps in maintenance

Defined in

packages/cozy-client/src/hooks/useAppsInMaintenance.jsx:12

useCapabilities¶

▸ useCapabilities(client): Object

Parameters

Name	Type
`client`	`any`

Returns

Object

Name	Type
`capabilities`	`undefined`
`fetchStatus`	`string`

Defined in

packages/cozy-client/src/hooks/useCapabilities.jsx:5

useClient¶

▸ useClient(): CozyClient

Returns the cozy client from the context

Returns

CozyClient

Current cozy client

Defined in

packages/cozy-client/src/hooks/useClient.js:10

useFetchShortcut¶

▸ useFetchShortcut(client, id): Object

Parameters

Name	Type
`client`	`any`
`id`	`any`

Returns

Object

Name	Type
`fetchStatus`	`string`
`shortcutImg`	`any`
`shortcutInfos`	`any`

Defined in

packages/cozy-client/src/hooks/useFetchShortcut.jsx:8

useInstanceInfo¶

▸ useInstanceInfo(): InstanceInfo

Retrieve intance info like context, uuid, disk usage etc

Returns

InstanceInfo

Defined in

packages/cozy-client/src/hooks/useInstanceInfo.js:11

useQueries¶

▸ useQueries(querySpecs): Object

Parameters

Name	Type
`querySpecs`	`any`

Returns

Object

Defined in

packages/cozy-client/src/hooks/useQuery.js:93

useQuery¶

▸ useQuery(queryDefinition, options): UseQueryReturnValue

Fetches a queryDefinition and returns the queryState

Parameters

Name	Type	Description
`queryDefinition`	`QueryDefinition`	() => `QueryDefinition`
`options`	`QueryOptions`	Options created with Q()

Returns

UseQueryReturnValue

Defined in

packages/cozy-client/src/hooks/useQuery.js:28

useQueryAll¶

▸ useQueryAll(queryDefinition, options): UseQueryReturnValue

Fetches a queryDefinition and run fetchMore on the query until the query is fully loaded

Parameters

Name	Type	Description
`queryDefinition`	`QueryDefinition`	Definition created with Q()
`options`	`QueryOptions`	Options created with Q()

Returns

UseQueryReturnValue

Defined in

packages/cozy-client/src/hooks/useQueryAll.jsx:14

useSettings¶

▸ useSettings<T>(slug, keys): UseSettingsReturnValue<T>

Query the cozy-app settings corresponding to the given slug and return:

the values corresponding to the given keys
the save() method that can be used to edit the setting’s value
the query that manages the state during the fetching of the setting
the mutation that manages the state during the saving of the setting

Type parameters¶

Name	Type
`T`	extends `string`

Parameters

Name	Type	Description
`slug`	`string`	the cozy-app’s slug containing the setting (special cases are: ‘instance’ for global settings and ‘passwords’ for bitwarden settings)
`keys`	`T`[]	The name of the setting to retrieve

Returns

UseSettingsReturnValue<T>

Defined in

packages/cozy-client/src/hooks/useSetting.js:24

withClient¶

▸ withClient(WrappedComponent): Function

function

description HOC to provide client from context as prop

Parameters

Name	Type	Description
`WrappedComponent`	`Component`<`any`, `any`, `any`>	wrapped component

Returns

Function

Component that will receive client as prop

Defined in

packages/cozy-client/src/hoc.jsx:16

withMutation¶

▸ withMutation(mutation, options?): Function

Parameters

Name	Type
`mutation`	`any`
`options`	`Object`

Returns

Function

Defined in

packages/cozy-client/src/withMutation.jsx:8

withMutations¶

▸ withMutations(…mutations): Function

function

description HOC to provide mutations to components. Needs client in context or as prop.

deprecated Prefer to use withClient and access directly the client.

Parameters

Name	Type	Description
`...mutations`	`Function`[]	One ore more mutations, which are function taking CozyClient as parameter and returning an object containing one or more mutations as attributes.

Returns

Function

Component that will receive mutations as props

Defined in

packages/cozy-client/src/withMutations.jsx:24