cozy-client 46.7.1 → 46.9.0

package/types/CozyClient.d.ts

@@ -414,6 +414,10 @@ declare class CozyClient {
      * `getQueryFromState` or directly using `<Query />`. `<Query />` automatically
      * executes its query when mounted if no fetch policy has been indicated.
      *
+     * If the query is called under the fetch policy's delay, then the query
+     * is not executed and nothing is returned. If you need a result anyway,
+     * please use `fetchQueryAndGetFromState` instead
+     *
      * @param  {QueryDefinition} queryDefinition - Definition that will be executed
      * @param  {import("./types").QueryOptions} [options] - Options
      * @returns {Promise<import("./types").QueryResult>}
@@ -713,6 +717,31 @@ declare class CozyClient {
      * @param {import("./types").AppMetadata} newAppMetadata AppMetadata to update
      */
     setAppMetadata(newAppMetadata: import("./types").AppMetadata): void;
+    /**
+     * Query the cozy-app settings corresponding to the given slug and
+     * extract the value corresponding to the given `key`
+     *
+     * @template {string} T
+     *
+     * @param {string} slug - the cozy-app's slug containing the setting (can be 'instance' for global settings)
+     * @param {T[]} keys - The names of the settings to retrieve
+     * @returns {Promise<any>} - The value of the requested setting
+     */
+    getSettings<T extends string>(slug: string, keys: T[]): Promise<any>;
+    /**
+     * Save the given value into the corresponding cozy-app setting
+     *
+     * This methods will first query the cozy-app's settings before injecting the new value and then
+     * save the new resulting settings into database
+     *
+     * @template {string} T
+     *
+     * @param {string} slug - the cozy-app's slug containing the setting (can be 'instance' for global settings)
+     * @param {Record<string, any> | ((oldValue) => Record<T, any>)} itemsOrSetter - The new values of the settings to save. It can be a raw dictionnary, or a callback that should return a new dictionnary
+     * @param {T[]=} setterKeys - The new values of the settings to save. It can be a raw dictionnary, or a callback that should return a new dictionnary
+     * @returns {Promise<any>} - The result of the `client.save()` call
+     */
+    saveAfterFetchSettings<T_1 extends string>(slug: string, itemsOrSetter: Record<string, any> | ((oldValue: any) => Record<T_1, any>), setterKeys?: T_1[]): Promise<any>;
 }
 declare namespace CozyClient {
     export const hooks: {};

package/types/__tests__/mocks.d.ts

@@ -8,6 +8,7 @@ export function client(implementations: any): {
     requestQuery: jest.Mock<any, any>;
     all: jest.Mock<any, any>;
     setStore: jest.Mock<any, any>;
+    fetchQueryAndGetFromState: jest.Mock<any, any>;
 };
 export function observableQuery(implementations: any): {
     currentResult: jest.Mock<any, any>;

package/types/helpers/index.d.ts

@@ -1,2 +1,3 @@
 export { dehydrate } from "./dehydrateHelper";
 export { deconstructCozyWebLinkWithSlug, deconstructRedirectLink, generateWebLink, ensureFirstSlash, rootCozyUrl, InvalidRedirectLinkError, InvalidCozyUrlError, InvalidProtocolError, BlockedCozyError } from "./urlHelper";
+export { editSettings, getQuery, getSettings, normalizeSettings, saveAfterFetchSettings } from "./settings";

package/types/helpers/settings.d.ts

@@ -0,0 +1,7 @@
+export function getSettings<T extends string>(client: CozyClient, slug: string, keys: T[]): Promise<Record<T, any>>;
+export function saveAfterFetchSettings<T extends string>(client: CozyClient, slug: string, itemsOrSetter: Record<string, any> | ((oldValue: any) => Record<T, any>), setterKeys?: T[]): Promise<any>;
+export function normalizeSettings(data: any[] | any): any;
+export function editSettings(slug: string, currentSettings: any, items: Record<string, unknown>): any;
+export function extractKeys<T extends string>(settings: Record<T, any>, keys: T[]): Record<T, any>;
+export function getQuery(slug: string): import('../types').Query;
+import CozyClient from "../CozyClient";

package/types/hooks/index.d.ts

@@ -6,4 +6,5 @@ export { default as useAppsInMaintenance } from "./useAppsInMaintenance";
 export { default as useQueryAll } from "./useQueryAll";
 export { useMutation } from "./useMutation";
 export { useInstanceInfo } from "./useInstanceInfo";
+export { useSettings } from "./useSetting";
 export { default as useQuery, useQueries } from "./useQuery";

package/types/hooks/useSetting.d.ts

@@ -0,0 +1 @@
+export function useSettings<T extends string>(slug: string, keys: T[]): import("../types").UseSettingsReturnValue<T>;

package/types/types.d.ts

@@ -481,7 +481,7 @@ export type IndexedDocuments = {
 export type DocumentsStateSlice = {
     [x: string]: Record<string, CozyClientDocument>;
 };
-export type QueryState = {
+export type QueryStateWithoutData = {
     id: string;
     definition: QueryDefinition;
     fetchStatus: QueryFetchStatus;
@@ -493,11 +493,14 @@ export type QueryState = {
     hasMore: boolean;
     count: number;
     fetchedPagesCount: number;
-    data: object | any[];
     bookmark: string;
     execution_stats?: object;
     options?: QueryOptions;
 };
+export type QueryStateData = {
+    data: object | any[];
+};
+export type QueryState = QueryStateWithoutData & QueryStateData;
 export type AutoUpdateOptions = any;
 export type QueryOptions = {
     /**
@@ -539,18 +542,18 @@ export type QueryOptions = {
      */
     singleDocData?: boolean;
 };
+export type Query = {
+    definition: QueryDefinition;
+    options: QueryOptions;
+};
 export type FetchMoreAble = {
     fetchMore: Function;
 };
 export type FetchAble = {
     fetch: Function;
 };
-export type UseQueryReturnValue = QueryState & FetchMoreAble & FetchAble;
-export type UseMutationReturnValue = {
-    /**
-     * - Function to save the document
-     */
-    mutate: Function;
+export type UseQueryReturnValue = QueryStateWithoutData & QueryStateData & FetchMoreAble & FetchAble;
+export type UseMutationWithoutMutate = {
     /**
      * - Status of the current mutation
      */
@@ -564,6 +567,35 @@ export type UseMutationReturnValue = {
      */
     data?: object;
 };
+export type UseMutationMutate = {
+    /**
+     * - Function to save the document
+     */
+    mutate: Function;
+};
+export type UseMutationReturnValue = UseMutationWithoutMutate & UseMutationMutate;
+/**
+ * Update the setting with corresponding value and save it.
+ */
+export type SaveSettingsFunction<T extends string> = (items: Partial<Record<T, any>>) => any;
+export type UseSettingsReturnValue<T extends string> = {
+    /**
+     * - The setting's value
+     */
+    values: Record<T, any>;
+    /**
+     * - Function to edit the setting
+     */
+    save: SaveSettingsFunction<T>;
+    /**
+     * - Function to edit the setting
+     */
+    query: QueryStateWithoutData;
+    /**
+     * - Status of the current mutation
+     */
+    mutation: UseMutationWithoutMutate;
+};
 /**
  * A reference to a document
  */