cozy-client 46.8.0 → 46.9.0

package/dist/CozyClient.js

@@ -1245,6 +1245,10 @@ var CozyClient = /*#__PURE__*/function () {
      * `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>}
@@ -2543,6 +2547,79 @@ var CozyClient = /*#__PURE__*/function () {
     value: function setAppMetadata(newAppMetadata) {
       this.appMetadata = _objectSpread(_objectSpread({}, this.appMetadata), newAppMetadata);
     }
+    /**
+     * 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
+     */
+
+  }, {
+    key: "getSettings",
+    value: function () {
+      var _getSettings2 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee19(slug, keys) {
+        return _regenerator.default.wrap(function _callee19$(_context19) {
+          while (1) {
+            switch (_context19.prev = _context19.next) {
+              case 0:
+                return _context19.abrupt("return", (0, _helpers2.getSettings)(this, slug, keys));
+
+              case 1:
+              case "end":
+                return _context19.stop();
+            }
+          }
+        }, _callee19, this);
+      }));
+
+      function getSettings(_x17, _x18) {
+        return _getSettings2.apply(this, arguments);
+      }
+
+      return getSettings;
+    }()
+    /**
+     * 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
+     */
+
+  }, {
+    key: "saveAfterFetchSettings",
+    value: function () {
+      var _saveAfterFetchSettings2 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee20(slug, itemsOrSetter, setterKeys) {
+        return _regenerator.default.wrap(function _callee20$(_context20) {
+          while (1) {
+            switch (_context20.prev = _context20.next) {
+              case 0:
+                return _context20.abrupt("return", (0, _helpers2.saveAfterFetchSettings)(this, slug, itemsOrSetter, setterKeys));
+
+              case 1:
+              case "end":
+                return _context20.stop();
+            }
+          }
+        }, _callee20, this);
+      }));
+
+      function saveAfterFetchSettings(_x19, _x20, _x21) {
+        return _saveAfterFetchSettings2.apply(this, arguments);
+      }
+
+      return saveAfterFetchSettings;
+    }()
   }], [{
     key: "fromOldClient",
     value: function fromOldClient(oldClient, options) {
@@ -2565,22 +2642,22 @@ var CozyClient = /*#__PURE__*/function () {
   }, {
     key: "fromOldOAuthClient",
     value: function () {
-      var _fromOldOAuthClient = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee19(oldClient, options) {
+      var _fromOldOAuthClient = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee21(oldClient, options) {
         var credentials, oauthOptions, client;
-        return _regenerator.default.wrap(function _callee19$(_context19) {
+        return _regenerator.default.wrap(function _callee21$(_context21) {
           while (1) {
-            switch (_context19.prev = _context19.next) {
+            switch (_context21.prev = _context21.next) {
               case 0:
                 if (!oldClient._oauth) {
-                  _context19.next = 12;
+                  _context21.next = 12;
                   break;
                 }
 
-                _context19.next = 3;
+                _context21.next = 3;
                 return oldClient.authorize();
 
               case 3:
-                credentials = _context19.sent;
+                credentials = _context21.sent;
                 oauthOptions = {
                   oauth: credentials.client,
                   token: credentials.token,
@@ -2591,28 +2668,28 @@ var CozyClient = /*#__PURE__*/function () {
                 }, oauthOptions), options));
 
                 if (!client.loginPromise) {
-                  _context19.next = 9;
+                  _context21.next = 9;
                   break;
                 }
 
-                _context19.next = 9;
+                _context21.next = 9;
                 return client.loginPromise;
 
               case 9:
-                return _context19.abrupt("return", client);
+                return _context21.abrupt("return", client);
 
               case 12:
                 throw new Error('Cannot instantiate a new client: old client is not an OAuth client. CozyClient.fromOldClient might be more suitable.');
 
               case 13:
               case "end":
-                return _context19.stop();
+                return _context21.stop();
             }
           }
-        }, _callee19);
+        }, _callee21);
       }));
 
-      function fromOldOAuthClient(_x17, _x18) {
+      function fromOldOAuthClient(_x22, _x23) {
         return _fromOldOAuthClient.apply(this, arguments);
       }
 
@@ -2705,7 +2782,7 @@ var CozyClient = /*#__PURE__*/function () {
 CozyClient.hooks = CozyClient.hooks || {};
 CozyClient.fetchPolicies = _policies.default; //COZY_CLIENT_VERSION_PACKAGE in replaced by babel. See babel config
 
-CozyClient.version = "46.8.0";
+CozyClient.version = "46.9.0";
 
 _microee.default.mixin(CozyClient);
 

package/dist/__tests__/mocks.js

@@ -38,7 +38,8 @@ var client = function client(implementations) {
     makeObservableQuery: jest.fn(),
     requestQuery: jest.fn(),
     all: jest.fn(),
-    setStore: jest.fn()
+    setStore: jest.fn(),
+    fetchQueryAndGetFromState: jest.fn()
   };
   mockImplementations(base, implementations);
   return base;

package/dist/helpers/index.js

@@ -63,7 +63,39 @@ Object.defineProperty(exports, "dehydrate", {
     return _dehydrateHelper.dehydrate;
   }
 });
+Object.defineProperty(exports, "editSettings", {
+  enumerable: true,
+  get: function get() {
+    return _settings.editSettings;
+  }
+});
+Object.defineProperty(exports, "getQuery", {
+  enumerable: true,
+  get: function get() {
+    return _settings.getQuery;
+  }
+});
+Object.defineProperty(exports, "getSettings", {
+  enumerable: true,
+  get: function get() {
+    return _settings.getSettings;
+  }
+});
+Object.defineProperty(exports, "normalizeSettings", {
+  enumerable: true,
+  get: function get() {
+    return _settings.normalizeSettings;
+  }
+});
+Object.defineProperty(exports, "saveAfterFetchSettings", {
+  enumerable: true,
+  get: function get() {
+    return _settings.saveAfterFetchSettings;
+  }
+});
 
 var _urlHelper = require("./urlHelper");
 
-var _dehydrateHelper = require("./dehydrateHelper");
+var _dehydrateHelper = require("./dehydrateHelper");
+
+var _settings = require("./settings");

package/dist/helpers/settings.js

@@ -0,0 +1,311 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getQuery = exports.extractKeys = exports.editSettings = exports.normalizeSettings = exports.saveAfterFetchSettings = exports.getSettings = void 0;
+
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+
+var _CozyClient = _interopRequireDefault(require("../CozyClient"));
+
+var _policies = _interopRequireDefault(require("../policies"));
+
+var _dsl = require("../queries/dsl");
+
+function _createForOfIteratorHelper(o, allowArrayLike) { var it; if (typeof Symbol === "undefined" || o[Symbol.iterator] == null) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = o[Symbol.iterator](); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { (0, _defineProperty2.default)(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+
+var defaultFetchPolicy = _policies.default.olderThan(60 * 60 * 1000);
+/**
+ * Query the cozy-app settings corresponding to the given slug and
+ * extract the values corresponding to the given `keys`
+ *
+ * @template {string} T
+ *
+ * @param {CozyClient} client - Cozy client instance
+ * @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<Record<T, any>>} - The values of the requested settings
+ */
+
+
+var getSettings = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(client, slug, keys) {
+    var query, currentSettingsResult, currentSettings;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) {
+        switch (_context.prev = _context.next) {
+          case 0:
+            query = getQuery(slug);
+            _context.next = 3;
+            return client.fetchQueryAndGetFromState({
+              definition: query.definition,
+              options: query.options
+            });
+
+          case 3:
+            currentSettingsResult = _context.sent;
+            currentSettings = normalizeSettings(currentSettingsResult.data); // @ts-ignore
+
+            return _context.abrupt("return", extractKeys(currentSettings, keys));
+
+          case 6:
+          case "end":
+            return _context.stop();
+        }
+      }
+    }, _callee);
+  }));
+
+  return function getSettings(_x, _x2, _x3) {
+    return _ref.apply(this, arguments);
+  };
+}();
+/**
+ * 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 {CozyClient} client - Cozy client instance
+ * @param {string} slug - the cozy-app's slug containing the setting (special cases are: 'instance' for global settings and 'bitwarden' for cozy-pass)
+ * @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
+ */
+
+
+exports.getSettings = getSettings;
+
+var saveAfterFetchSettings = /*#__PURE__*/function () {
+  var _ref2 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee2(client, slug, itemsOrSetter, setterKeys) {
+    var query, currentSettingsResult, currentSettings, items, currentItems, _currentItems, newSettings;
+
+    return _regenerator.default.wrap(function _callee2$(_context2) {
+      while (1) {
+        switch (_context2.prev = _context2.next) {
+          case 0:
+            query = getQuery(slug);
+            _context2.next = 3;
+            return client.fetchQueryAndGetFromState({
+              definition: query.definition,
+              options: query.options
+            });
+
+          case 3:
+            currentSettingsResult = _context2.sent;
+            currentSettings = normalizeSettings(currentSettingsResult.data);
+            items = undefined;
+
+            if (typeof itemsOrSetter === 'function') {
+              currentItems = extractKeys(currentSettings, setterKeys);
+              items = itemsOrSetter(currentItems);
+            } else {
+              _currentItems = extractKeys(currentSettings, Object.keys(itemsOrSetter));
+              items = _objectSpread(_objectSpread({}, _currentItems), itemsOrSetter);
+            }
+
+            newSettings = editSettings(slug, currentSettings, items);
+            _context2.next = 10;
+            return client.save(newSettings);
+
+          case 10:
+            return _context2.abrupt("return", _context2.sent);
+
+          case 11:
+          case "end":
+            return _context2.stop();
+        }
+      }
+    }, _callee2);
+  }));
+
+  return function saveAfterFetchSettings(_x4, _x5, _x6, _x7) {
+    return _ref2.apply(this, arguments);
+  };
+}();
+/**
+ * Convert a result from a `client.query()` or a `useQuery()` that can be
+ * an object or an array of objects into a single object
+ *
+ * @param {Array | Object} data - Result from a client.query or a useQuery
+ * @returns {Object} A single object containing the setting data
+ */
+
+
+exports.saveAfterFetchSettings = saveAfterFetchSettings;
+
+var normalizeSettings = function normalizeSettings(data) {
+  var settingsData = Array.isArray(data) ? data[0] : data;
+  return settingsData || {};
+};
+/**
+ * Edit the given settings by injecting `value` into the `key` entry
+ * This methods takes care of the kind of settings that is edited as there are
+ * some exceptions in settings formats (i.e. `io.cozy.settings.instance`)
+ *
+ * @param {string} slug - the cozy-app's slug containing the setting (can be 'instance' for global settings)
+ * @param {Object} currentSettings - the Setting object (ideally from a `client.query()` or a `useQuery()` and normalized using `normalizeSettings`)
+ * @param {Record<string, unknown>} items - The new values for the settings
+ * @returns {Object} a new Setting object containing the new value
+ */
+
+
+exports.normalizeSettings = normalizeSettings;
+
+var editSettings = function editSettings(slug, currentSettings, items) {
+  var type = getDoctype(slug);
+  var newSettings = slug === 'instance' ? mergeInstance(currentSettings, items) : mergeSettings(currentSettings, type, items);
+  return newSettings;
+};
+
+exports.editSettings = editSettings;
+
+var mergeInstance = function mergeInstance(currentSettings, items) {
+  var newSettings = _objectSpread(_objectSpread({
+    _id: currentSettings._id,
+    _type: currentSettings._type,
+    _rev: currentSettings.meta.rev
+  }, currentSettings), {}, {
+    attributes: _objectSpread({}, currentSettings.attributes)
+  });
+
+  for (var _i = 0, _Object$entries = Object.entries(items); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = (0, _slicedToArray2.default)(_Object$entries[_i], 2),
+        key = _Object$entries$_i[0],
+        value = _Object$entries$_i[1];
+
+    newSettings[key] = value;
+    newSettings.attributes[key] = value;
+  }
+
+  return newSettings;
+};
+
+var mergeSettings = function mergeSettings(currentSettings, type, items) {
+  var newSettings = _objectSpread({
+    _type: type
+  }, currentSettings);
+
+  for (var _i2 = 0, _Object$entries2 = Object.entries(items); _i2 < _Object$entries2.length; _i2++) {
+    var _Object$entries2$_i = (0, _slicedToArray2.default)(_Object$entries2[_i2], 2),
+        key = _Object$entries2$_i[0],
+        value = _Object$entries2$_i[1];
+
+    newSettings[key] = value;
+  }
+
+  return newSettings;
+};
+/**
+ * Extract values from given settings for requested keys
+ *
+ * @template {string} T
+ *
+ * @param {Record<T, any>} settings - the Setting object (ideally from a `client.query()` or a `useQuery()` and normalized using `normalizeSettings`)
+ * @param {T[]} keys - The names of the settings to extract
+ * @returns {Record<T, any>} - Dictionnary containing the values for the requested keys
+ */
+
+
+var extractKeys = function extractKeys(settings, keys) {
+  var result = {};
+
+  var _iterator = _createForOfIteratorHelper(keys),
+      _step;
+
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var key = _step.value;
+      // @ts-ignore
+      result[key] = settings[key];
+    } // @ts-ignore
+
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+
+  return result;
+};
+/**
+ * Create a Query that can be used to fetch the cozy-app settings for the given slug
+ *
+ * @param {string} slug - the cozy-app's slug containing the setting (special cases are: 'instance' for global settings and 'passwords' for bitwarden settings)
+ * @returns {import('../types').Query} - the Query that can be used to fetch the cozy-app settings
+ */
+
+
+exports.extractKeys = extractKeys;
+
+var getQuery = function getQuery(slug) {
+  if (slug === 'instance') {
+    return getNestedSettings(slug);
+  }
+
+  if (slug === 'passwords') {
+    return getNestedSettings('bitwarden');
+  }
+
+  return getRootSettings(slug);
+};
+
+exports.getQuery = getQuery;
+
+var getRootSettings = function getRootSettings(slug) {
+  var settingsDoctype = getDoctype(slug);
+  var query = {
+    definition: (0, _dsl.Q)(settingsDoctype).limitBy(1),
+    options: {
+      as: settingsDoctype,
+      fetchPolicy: defaultFetchPolicy,
+      singleDocData: true
+    }
+  };
+  return query;
+};
+
+var getNestedSettings = function getNestedSettings(slug) {
+  var doctype = "io.cozy.settings";
+  var subDoctype = getDoctype(slug);
+  var query = {
+    definition: (0, _dsl.Q)(doctype).getById(subDoctype),
+    options: {
+      as: "".concat(doctype, "/").concat(subDoctype),
+      fetchPolicy: defaultFetchPolicy,
+      singleDocData: true
+    }
+  };
+  return query;
+};
+
+var getDoctype = function getDoctype(slug) {
+  if (['instance', 'bitwarden'].includes(slug)) {
+    return "io.cozy.settings.".concat(slug);
+  }
+
+  if (slug === 'passwords') {
+    return 'io.cozy.settings.bitwarden';
+  }
+
+  return "io.cozy.".concat(slug, ".settings");
+};

package/dist/helpers/settings.spec.js

@@ -0,0 +1,493 @@
+import {
+  editSettings,
+  getSettings,
+  normalizeSettings,
+  saveAfterFetchSettings
+} from './settings'
+import { Q } from '../queries/dsl'
+
+import * as mocks from '../__tests__/mocks'
+
+describe('settings', () => {
+  describe('getSettings', () => {
+    it('should get settings for cozy-home', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            some_key: 'some_value'
+          }
+        ]
+      })
+
+      // @ts-ignore
+      const result = await getSettings(client, 'home', ['some_key'])
+
+      const query = {
+        definition: Q('io.cozy.home.settings').limitBy(1),
+        options: {
+          as: 'io.cozy.home.settings',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(result.some_key).toEqual('some_value')
+    })
+
+    it('should get settings for mespapiers', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            some_mespapiers_key: 'some_mespapiers_value'
+          }
+        ]
+      })
+
+      const result = await getSettings(
+        // @ts-ignore
+        client,
+        'mespapiers',
+        ['some_mespapiers_key']
+      )
+
+      const query = {
+        definition: Q('io.cozy.mespapiers.settings').limitBy(1),
+        options: {
+          as: 'io.cozy.mespapiers.settings',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(result.some_mespapiers_key).toEqual('some_mespapiers_value')
+    })
+
+    it('should get settings for instance', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            some_global_key: 'some_global_value'
+          }
+        ]
+      })
+
+      // @ts-ignore
+      const result = await getSettings(client, 'instance', ['some_global_key'])
+
+      const query = {
+        definition: Q('io.cozy.settings').getById('io.cozy.settings.instance'),
+        options: {
+          as: 'io.cozy.settings/io.cozy.settings.instance',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(result.some_global_key).toEqual('some_global_value')
+    })
+
+    it('should get settings for passwords', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            some_pass_key: 'some_pass_value'
+          }
+        ]
+      })
+
+      // @ts-ignore
+      const result = await getSettings(client, 'passwords', ['some_pass_key'])
+
+      const query = {
+        definition: Q('io.cozy.settings').getById('io.cozy.settings.bitwarden'),
+        options: {
+          as: 'io.cozy.settings/io.cozy.settings.bitwarden',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(result.some_pass_key).toEqual('some_pass_value')
+    })
+
+    it('should return undefined if no setting is found in database', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            some_other_key: 'some_other_value'
+          }
+        ]
+      })
+
+      // @ts-ignore
+      const result = await getSettings(client, 'home', ['some_key'])
+
+      expect(result.some_key).toBeUndefined()
+    })
+
+    it('should get settings for multiple keys', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            some_key_1: 'some_value_1',
+            some_key_2: 'some_value_2',
+            some_key_3: 'some_value_3'
+          }
+        ]
+      })
+
+      // @ts-ignore
+      const result = await getSettings(client, 'home', [
+        'some_key_1',
+        'some_key_2'
+      ])
+
+      const query = {
+        definition: Q('io.cozy.home.settings').limitBy(1),
+        options: {
+          as: 'io.cozy.home.settings',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(result.some_key_1).toEqual('some_value_1')
+      expect(result.some_key_2).toEqual('some_value_2')
+      // @ts-ignore
+      expect(result.some_key_3).toBeUndefined()
+    })
+  })
+
+  describe('saveAfterFetchSettings', () => {
+    it('should set settings for instance', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            id: 'io.cozy.settings.instance',
+            _id: 'io.cozy.settings.instance',
+            _type: 'io.cozy.settings',
+            type: 'io.cozy.settings',
+            attributes: {
+              some_setting: 'some_setting_value',
+              some_instance_key: 'some_instance_value'
+            },
+            meta: {
+              rev: 'SOME_UNIQ_REV_NUMBER'
+            },
+            some_setting: 'some_setting_value',
+            some_instance_key: 'some_instance_value'
+          }
+        ]
+      })
+
+      await saveAfterFetchSettings(
+        // @ts-ignore
+        client,
+        'instance',
+        {
+          some_instance_key: 'some_new_instance_value'
+        }
+      )
+
+      const query = {
+        definition: Q('io.cozy.settings').getById('io.cozy.settings.instance'),
+        options: {
+          as: 'io.cozy.settings/io.cozy.settings.instance',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(client.save).toHaveBeenCalledWith({
+        id: 'io.cozy.settings.instance',
+        _id: 'io.cozy.settings.instance',
+        _type: 'io.cozy.settings',
+        type: 'io.cozy.settings',
+        _rev: 'SOME_UNIQ_REV_NUMBER',
+        attributes: {
+          some_setting: 'some_setting_value',
+          some_instance_key: 'some_new_instance_value'
+        },
+        some_setting: 'some_setting_value',
+        some_instance_key: 'some_new_instance_value',
+        meta: {
+          rev: 'SOME_UNIQ_REV_NUMBER'
+        }
+      })
+    })
+
+    it('should set settings for passwords', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            _type: 'io.cozy.passwords.settings',
+            some_pass_key: 'some_pass_value'
+          }
+        ]
+      })
+
+      await saveAfterFetchSettings(
+        // @ts-ignore
+        client,
+        'passwords',
+        { some_pass_key: 'some_new_pass_value' }
+      )
+
+      const query = {
+        definition: Q('io.cozy.settings').getById('io.cozy.settings.bitwarden'),
+        options: {
+          as: 'io.cozy.settings/io.cozy.settings.bitwarden',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(client.save).toHaveBeenCalledWith({
+        _type: 'io.cozy.passwords.settings',
+        some_pass_key: 'some_new_pass_value'
+      })
+    })
+
+    it('should set settings for passwords even if key does not exist', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            _type: 'io.cozy.passwords.settings',
+            some_existing_pass_key: 'some_pass_value'
+          }
+        ]
+      })
+
+      await saveAfterFetchSettings(
+        // @ts-ignore
+        client,
+        'passwords',
+        { some_new_pass_key: 'some_new_pass_value' }
+      )
+
+      const query = {
+        definition: Q('io.cozy.settings').getById('io.cozy.settings.bitwarden'),
+        options: {
+          as: 'io.cozy.settings/io.cozy.settings.bitwarden',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(client.save).toHaveBeenCalledWith({
+        _type: 'io.cozy.passwords.settings',
+        some_existing_pass_key: 'some_pass_value',
+        some_new_pass_key: 'some_new_pass_value'
+      })
+    })
+
+    it('should set settings for passwords using method', async () => {
+      const client = mocks.client()
+
+      client.fetchQueryAndGetFromState.mockResolvedValue({
+        data: [
+          {
+            _type: 'io.cozy.passwords.settings',
+            some_pass_key: 1
+          }
+        ]
+      })
+
+      await saveAfterFetchSettings(
+        // @ts-ignore
+        client,
+        'passwords',
+        currentValue => ({
+          ...currentValue,
+          some_pass_key: currentValue.some_pass_key + 1
+        }),
+        ['some_pass_key']
+      )
+
+      const query = {
+        definition: Q('io.cozy.settings').getById('io.cozy.settings.bitwarden'),
+        options: {
+          as: 'io.cozy.settings/io.cozy.settings.bitwarden',
+          fetchPolicy: expect.anything(),
+          singleDocData: true
+        }
+      }
+      expect(client.fetchQueryAndGetFromState).toHaveBeenCalledWith({
+        definition: query.definition,
+        options: query.options
+      })
+      expect(client.save).toHaveBeenCalledWith({
+        _type: 'io.cozy.passwords.settings',
+        some_pass_key: 2
+      })
+    })
+  })
+
+  describe('normalizeSettings', () => {
+    it('should normalize data array into object', () => {
+      const result = normalizeSettings([
+        {
+          id: 'SOME_DOCUMENT_ID',
+          _id: 'SOME_DOCUMENT_ID',
+          _type: 'io.cozy.home.settings',
+          _rev: 'SOME_DOCUMENT_REV',
+          cozyMetadata: {
+            createdAt: '2024-04-03T15:00:48.961Z',
+            metadataVersion: 1,
+            updatedAt: '2024-04-03T15:00:48.961Z',
+            updatedByApps: []
+          },
+          some_attribue: true
+        }
+      ])
+
+      expect(result).toStrictEqual({
+        id: 'SOME_DOCUMENT_ID',
+        _id: 'SOME_DOCUMENT_ID',
+        _type: 'io.cozy.home.settings',
+        _rev: 'SOME_DOCUMENT_REV',
+        cozyMetadata: {
+          createdAt: '2024-04-03T15:00:48.961Z',
+          metadataVersion: 1,
+          updatedAt: '2024-04-03T15:00:48.961Z',
+          updatedByApps: []
+        },
+        some_attribue: true
+      })
+    })
+
+    it('should normalize data object into object', () => {
+      const result = normalizeSettings({
+        id: 'io.cozy.settings.instance',
+        _id: 'io.cozy.settings.instance',
+        _type: 'io.cozy.settings',
+        type: 'io.cozy.settings',
+        attributes: {
+          some_attributes: 'some_value'
+        },
+        meta: {
+          rev: '2-8803d6fda4bd3216e3fbeb0a181979d5'
+        },
+        links: {
+          self: '/settings/instance'
+        },
+        some_attributes: 'some_value'
+      })
+
+      expect(result).toStrictEqual({
+        id: 'io.cozy.settings.instance',
+        _id: 'io.cozy.settings.instance',
+        _type: 'io.cozy.settings',
+        type: 'io.cozy.settings',
+        attributes: {
+          some_attributes: 'some_value'
+        },
+        meta: {
+          rev: '2-8803d6fda4bd3216e3fbeb0a181979d5'
+        },
+        links: {
+          self: '/settings/instance'
+        },
+        some_attributes: 'some_value'
+      })
+    })
+  })
+  describe('editSettings', () => {
+    it('should inject value into settings', () => {
+      const result = editSettings(
+        'passwords',
+        {
+          _type: 'io.cozy.passwords.settings',
+          some_pass_key: 'some_pass_value'
+        },
+        { some_pass_key: 'some_new_pass_value' }
+      )
+
+      expect(result).toStrictEqual({
+        _type: 'io.cozy.passwords.settings',
+        some_pass_key: 'some_new_pass_value'
+      })
+    })
+
+    it('should inject _rev value and edit attributes for instance settings', () => {
+      const result = editSettings(
+        'instance',
+        {
+          id: 'io.cozy.settings.instance',
+          _id: 'io.cozy.settings.instance',
+          _type: 'io.cozy.settings',
+          type: 'io.cozy.settings',
+          attributes: {
+            some_setting: 'some_setting_value',
+            some_instance_key: 'some_instance_value'
+          },
+          meta: {
+            rev: 'SOME_UNIQ_REV_NUMBER'
+          },
+          some_setting: 'some_setting_value',
+          some_instance_key: 'some_instance_value'
+        },
+        { some_instance_key: 'some_new_instance_value' }
+      )
+
+      expect(result).toStrictEqual({
+        id: 'io.cozy.settings.instance',
+        _id: 'io.cozy.settings.instance',
+        _type: 'io.cozy.settings',
+        type: 'io.cozy.settings',
+        _rev: 'SOME_UNIQ_REV_NUMBER',
+        attributes: {
+          some_setting: 'some_setting_value',
+          some_instance_key: 'some_new_instance_value'
+        },
+        some_setting: 'some_setting_value',
+        some_instance_key: 'some_new_instance_value',
+        meta: {
+          rev: 'SOME_UNIQ_REV_NUMBER'
+        }
+      })
+    })
+  })
+})

package/dist/hooks/index.js

@@ -67,6 +67,12 @@ Object.defineProperty(exports, "useInstanceInfo", {
     return _useInstanceInfo.useInstanceInfo;
   }
 });
+Object.defineProperty(exports, "useSettings", {
+  enumerable: true,
+  get: function get() {
+    return _useSetting.useSettings;
+  }
+});
 
 var _useAppLinkWithStoreFallback = _interopRequireDefault(require("./useAppLinkWithStoreFallback"));
 
@@ -84,4 +90,6 @@ var _useQueryAll = _interopRequireDefault(require("./useQueryAll"));
 
 var _useMutation = require("./useMutation");
 
-var _useInstanceInfo = require("./useInstanceInfo");
+var _useInstanceInfo = require("./useInstanceInfo");
+
+var _useSetting = require("./useSetting");

package/dist/hooks/useSetting.js

@@ -0,0 +1,64 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useSettings = void 0;
+
+var _objectWithoutProperties2 = _interopRequireDefault(require("@babel/runtime/helpers/objectWithoutProperties"));
+
+var _react = require("react");
+
+var _helpers = require("../helpers");
+
+var _useMutation2 = require("./useMutation");
+
+var _useQuery2 = _interopRequireDefault(require("./useQuery"));
+
+var _utils = require("../utils");
+
+var _settings = require("../helpers/settings");
+
+/**
+ * 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
+ *
+ * @template {string} T
+ *
+ * @param {string} slug - the cozy-app's slug containing the setting (special cases are: 'instance' for global settings and 'passwords' for bitwarden settings)
+ * @param {T[]} keys - The name of the setting to retrieve
+ * @returns {import("../types").UseSettingsReturnValue<T>}
+ */
+var useSettings = function useSettings(slug, keys) {
+  var query = (0, _helpers.getQuery)(slug);
+
+  var _useQuery = (0, _useQuery2.default)(query.definition, query.options),
+      settingsData = _useQuery.data,
+      settingsQuery = (0, _objectWithoutProperties2.default)(_useQuery, ["data"]);
+
+  var _useMutation = (0, _useMutation2.useMutation)(),
+      mutate = _useMutation.mutate,
+      mutation = (0, _objectWithoutProperties2.default)(_useMutation, ["mutate"]);
+
+  var save = (0, _react.useCallback)(function (items) {
+    var settings = (0, _helpers.normalizeSettings)(settingsData);
+    var newSettings = (0, _helpers.editSettings)(slug, settings, items);
+    return mutate(newSettings);
+  }, [mutate, settingsData, slug]);
+  var settings = (0, _helpers.normalizeSettings)(settingsData);
+  var settingValue = (0, _utils.hasQueryBeenLoaded)(settingsQuery) ? (0, _settings.extractKeys)(settings, keys) : undefined;
+  return {
+    query: settingsQuery,
+    values: settingValue,
+    save: save,
+    mutation: mutation
+  };
+};
+
+exports.useSettings = useSettings;

package/dist/types.js

@@ -250,7 +250,7 @@ var _dsl = require("./queries/dsl");
  */
 
 /**
- * @typedef {object} QueryState
+ * @typedef {object} QueryStateWithoutData
  * @property {string} id
  * @property {QueryDefinition} definition
  * @property {QueryFetchStatus} fetchStatus
@@ -262,12 +262,20 @@ var _dsl = require("./queries/dsl");
  * @property {boolean} hasMore
  * @property {number} count
  * @property {number} fetchedPagesCount
- * @property {object|Array} data
  * @property {string} bookmark
  * @property {object} [execution_stats]
  * @property {QueryOptions} [options]
  */
 
+/**
+ * @typedef {object} QueryStateData
+ * @property {object|Array} data
+ */
+
+/**
+ * @typedef {QueryStateWithoutData & QueryStateData} QueryState
+ */
+
 /**
  * @typedef {object} AutoUpdateOptions
  * @param {boolean} update - Should documents be updated in the query (default: true)
@@ -290,6 +298,12 @@ var _dsl = require("./queries/dsl");
  * compatibility but will be set to true in the future.
  */
 
+/**
+ * @typedef {object} Query
+ * @property {QueryDefinition} definition
+ * @property {QueryOptions} options
+ */
+
 /**
  * @typedef {object} FetchMoreAble
  * @property {Function} fetchMore
@@ -305,13 +319,39 @@ var _dsl = require("./queries/dsl");
  */
 
 /**
- * @typedef {object} UseMutationReturnValue
- * @property {Function} mutate - Function to save the document
+ * @typedef {object} UseMutationWithoutMutate
  * @property {QueryFetchStatus} mutationStatus - Status of the current mutation
  * @property {object} [error] - Error if the mutation failed
  * @property {object} [data] - Data return after the mutation
  */
 
+/**
+ * @typedef {object} UseMutationMutate
+ * @property {Function} mutate - Function to save the document
+ */
+
+/**
+ * @typedef {UseMutationWithoutMutate & UseMutationMutate} UseMutationReturnValue
+ */
+
+/**
+ * Update the setting with corresponding value and save it.
+ *
+ * @template {string} T
+ *
+ * @callback SaveSettingsFunction
+ * @param {Partial<Record<T, any>>} items - The new setting's value
+ */
+
+/**
+ * @template {string} T
+ * @typedef {object} UseSettingsReturnValue
+ * @property {Record<T, any> | undefined} values - The setting's value
+ * @property {SaveSettingsFunction<T>} save - Function to edit the setting
+ * @property {QueryStateWithoutData} query - Function to edit the setting
+ * @property {UseMutationWithoutMutate} mutation - Status of the current mutation
+ */
+
 /**
  * A reference to a document
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozy-client",
-  "version": "46.8.0",
+  "version": "46.9.0",
   "license": "MIT",
   "main": "dist/index.node.js",
   "browser": "dist/index.js",
@@ -75,5 +75,5 @@
     "react-native-ios11-devicecheck": "https://github.com/cozy/react-native-devicecheck#app-attest-v0.1"
   },
   "sideEffects": false,
-  "gitHead": "adc2786ac0ebde0b64aff738930aef5ab67423a2"
+  "gitHead": "69f0df2adc776ecec40b14eaae495b544d42963f"
 }

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