cozy-client 60.30.6 → 60.32.0

package/dist/models/banner.js

@@ -0,0 +1,399 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dismiss = exports.getActiveBanner = exports.getActiveBanners = exports.BANNERS_DOCTYPE = void 0;
+
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+
+var _dsl = require("../queries/dsl");
+
+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 BANNERS_DOCTYPE = 'io.cozy.banners';
+exports.BANNERS_DOCTYPE = BANNERS_DOCTYPE;
+var KNOWN_SEVERITIES = ['info', 'warning', 'error'];
+var KNOWN_SURFACES = ['banner', 'modal'];
+/**
+ * @typedef {object} BannerCta
+ * @property {string} label - The label, plain text
+ * @property {string} url - Where the label points
+ */
+
+/**
+ * @typedef {object} Banner An io.cozy.banners document
+ * @property {string} [_id] - Identifier of the document
+ * @property {string} bannerId - Identifier of the banner itself
+ * @property {string} category - What the banner is about
+ * @property {'info'|'warning'|'error'} severity - How loudly to render it
+ * @property {'banner'|'modal'} surface - Where to render it
+ * @property {string} [title] - Optional heading, used on the modal surface
+ * @property {string} text - The message, already localized
+ * @property {string} lang - BCP 47 tag of the language `text` and `cta.label` are in
+ * @property {BannerCta} [cta] - Optional call to action
+ * @property {BannerCta} [secondaryCta] - Optional lesser action, needs a cta
+ * @property {boolean} dismissible - Whether the client offers a dismiss control
+ * @property {string} [dismissedAt] - When the user dismissed it
+ * @property {number} priority - Sort order, highest first
+ * @property {string} startsAt - Start of the validity window, inclusive
+ * @property {string} [endsAt] - End of the validity window, exclusive
+ */
+
+/**
+ * The doctype writes an ISO 8601 timestamp with an explicit offset, and nothing
+ * else parses. `Date.parse` on its own falls back to the engine's legacy parser
+ * for anything it does not recognise, so a malformed bound would resolve to a
+ * real instant in one browser and to NaN in another, and the shared contract
+ * vectors could no longer say what every client displays.
+ */
+
+var ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+/** A bound that is absent leaves that end of the window open, unlike an unparseable one. */
+
+var toTime = function toTime(value) {
+  if (value == null) return null;
+  if (typeof value !== 'string' || !ISO_TIMESTAMP.test(value)) return NaN;
+  return Date.parse(value);
+};
+
+var isDismissed = function isDismissed(banner) {
+  return (banner === null || banner === void 0 ? void 0 : banner.dismissedAt) != null;
+};
+/** The window is inclusive on startsAt, exclusive on endsAt, open when absent. */
+
+
+var isInWindow = function isInWindow(banner, now) {
+  var startsAt = toTime(banner === null || banner === void 0 ? void 0 : banner.startsAt);
+  var endsAt = toTime(banner === null || banner === void 0 ? void 0 : banner.endsAt);
+
+  if (startsAt === null || Number.isNaN(startsAt) || Number.isNaN(endsAt)) {
+    return false;
+  }
+
+  var at = now.getTime();
+  if (at < startsAt) return false;
+  return endsAt === null || at < endsAt;
+};
+/**
+ * Highest priority first, then bannerId, compared code unit by code unit so
+ * that every client orders equal priorities the same way. `localeCompare`
+ * would depend on the runtime locale.
+ */
+
+
+var rankOf = function rankOf(banner) {
+  return Number.isFinite(banner === null || banner === void 0 ? void 0 : banner.priority) ? banner.priority : 0;
+};
+
+var byPriority = function byPriority(a, b) {
+  var byRank = rankOf(b) - rankOf(a);
+  if (byRank !== 0) return byRank;
+  if (a.bannerId < b.bannerId) return -1;
+  if (a.bannerId > b.bannerId) return 1;
+  return 0;
+};
+/**
+ * The doctype specifies an absolute `https://` URL, so anything else is dropped
+ * rather than handed to a client that would put it in an `href`: the documents
+ * live in a database the applications can write, and a `javascript:` URL there
+ * would run in the origin of whichever application rendered the banner.
+ */
+
+
+var isSafeCta = function isSafeCta(cta) {
+  return typeof (cta === null || cta === void 0 ? void 0 : cta.url) === 'string' && /^https:\/\//i.test(cta.url);
+};
+/**
+ * The doctype allows a new severity or surface without a version bump, so a
+ * value this client does not know is rendered rather than dropped.
+ */
+
+
+var withFallbacks = function withFallbacks(banner) {
+  var cta = isSafeCta(banner.cta) ? banner.cta : undefined;
+  return _objectSpread(_objectSpread({}, banner), {}, {
+    severity: KNOWN_SEVERITIES.includes(banner.severity) ? banner.severity : 'warning',
+    surface: KNOWN_SURFACES.includes(banner.surface) ? banner.surface : 'banner',
+    cta: cta,
+    // The secondary action is the lesser one, so it is never promoted to the
+    // only thing on offer: without a primary it is dropped rather than shown.
+    secondaryCta: cta && isSafeCta(banner.secondaryCta) ? banner.secondaryCta : undefined
+  });
+};
+/**
+ * `client.query` resolves undefined instead of rejecting when the client has an
+ * `onError` callback, which would otherwise read as "no banners apply".
+ */
+
+
+var readData = function readData(response) {
+  if (response === null || response === undefined) {
+    throw new Error("The ".concat(BANNERS_DOCTYPE, " query resolved nothing"));
+  }
+
+  return response.data;
+};
+/** The stack link answers a missing document with null, the pouch link with []. */
+
+
+var readOne = function readOne(response) {
+  var data = readData(response);
+  var doc = Array.isArray(data) ? data[0] : data;
+  return doc !== null && doc !== void 0 && doc._id ? doc : null;
+};
+
+var isConflict = function isConflict(error) {
+  var _error$message;
+
+  return (error === null || error === void 0 ? void 0 : error.status) === 409 || /Document update conflict/.test((_error$message = error === null || error === void 0 ? void 0 : error.message) !== null && _error$message !== void 0 ? _error$message : '');
+};
+/**
+ * The banners to display, in order.
+ *
+ * @param {object} client - A CozyClient instance
+ * @param {object} [options] - Options
+ * @param {Date} [options.now] - The current time
+ * @returns {Promise<Banner[]>} The banners to render
+ */
+
+
+var getActiveBanners = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(client) {
+    var _ref2,
+        _ref2$now,
+        now,
+        data,
+        _args = arguments;
+
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) {
+        switch (_context.prev = _context.next) {
+          case 0:
+            _ref2 = _args.length > 1 && _args[1] !== undefined ? _args[1] : {}, _ref2$now = _ref2.now, now = _ref2$now === void 0 ? new Date() : _ref2$now;
+            _context.t0 = readData;
+            _context.next = 4;
+            return client.query((0, _dsl.Q)(BANNERS_DOCTYPE).UNSAFE_noLimit(), {
+              as: "".concat(BANNERS_DOCTYPE, "/all")
+            });
+
+          case 4:
+            _context.t1 = _context.sent;
+            data = (0, _context.t0)(_context.t1);
+            return _context.abrupt("return", (Array.isArray(data) ? data : []).filter(function (banner) {
+              return !isDismissed(banner) && isInWindow(banner, now);
+            }).sort(byPriority).map(withFallbacks));
+
+          case 7:
+          case "end":
+            return _context.stop();
+        }
+      }
+    }, _callee);
+  }));
+
+  return function getActiveBanners(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();
+/**
+ * The single banner to display, for a surface that shows one at a time.
+ *
+ * A native client rendering one slot reads this rather than taking the head of
+ * the list itself, so the ordering rules stay in one place.
+ *
+ * @param {object} client - A CozyClient instance
+ * @param {object} [options] - Options
+ * @param {Date} [options.now] - The current time
+ * @returns {Promise<Banner|null>} The highest priority banner, or null
+ */
+
+
+exports.getActiveBanners = getActiveBanners;
+
+var getActiveBanner = /*#__PURE__*/function () {
+  var _ref3 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee2(client, options) {
+    var _yield$getActiveBanne;
+
+    return _regenerator.default.wrap(function _callee2$(_context2) {
+      while (1) {
+        switch (_context2.prev = _context2.next) {
+          case 0:
+            _context2.next = 2;
+            return getActiveBanners(client, options);
+
+          case 2:
+            _context2.t1 = _yield$getActiveBanne = _context2.sent[0];
+            _context2.t0 = _context2.t1 !== null;
+
+            if (!_context2.t0) {
+              _context2.next = 6;
+              break;
+            }
+
+            _context2.t0 = _yield$getActiveBanne !== void 0;
+
+          case 6:
+            if (!_context2.t0) {
+              _context2.next = 10;
+              break;
+            }
+
+            _context2.t2 = _yield$getActiveBanne;
+            _context2.next = 11;
+            break;
+
+          case 10:
+            _context2.t2 = null;
+
+          case 11:
+            return _context2.abrupt("return", _context2.t2);
+
+          case 12:
+          case "end":
+            return _context2.stop();
+        }
+      }
+    }, _callee2);
+  }));
+
+  return function getActiveBanner(_x2, _x3) {
+    return _ref3.apply(this, arguments);
+  };
+}();
+/**
+ * Records a dismissal on the stored document, retrying once on a conflict.
+ *
+ * The stored document is written back rather than the one the caller holds,
+ * whose severity and surface have had the fallbacks applied.
+ *
+ * @param {object} client - A CozyClient instance
+ * @param {Banner} banner - The banner to dismiss
+ * @param {object} [options] - Options
+ * @param {string} [options.dismissedAt] - The timestamp to record
+ * @returns {Promise<{data: Banner|null}>} The dismissed document, null when gone
+ */
+
+
+exports.getActiveBanner = getActiveBanner;
+
+var dismiss = /*#__PURE__*/function () {
+  var _ref4 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee4(client, banner) {
+    var _ref5,
+        dismissedAt,
+        at,
+        write,
+        _args4 = arguments;
+
+    return _regenerator.default.wrap(function _callee4$(_context4) {
+      while (1) {
+        switch (_context4.prev = _context4.next) {
+          case 0:
+            _ref5 = _args4.length > 2 && _args4[2] !== undefined ? _args4[2] : {}, dismissedAt = _ref5.dismissedAt;
+
+            if (banner !== null && banner !== void 0 && banner._id) {
+              _context4.next = 3;
+              break;
+            }
+
+            throw new Error('A banner needs an _id to be dismissed');
+
+          case 3:
+            at = dismissedAt !== null && dismissedAt !== void 0 ? dismissedAt : new Date().toISOString();
+
+            write = /*#__PURE__*/function () {
+              var _ref6 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee3() {
+                var stored;
+                return _regenerator.default.wrap(function _callee3$(_context3) {
+                  while (1) {
+                    switch (_context3.prev = _context3.next) {
+                      case 0:
+                        _context3.t0 = readOne;
+                        _context3.next = 3;
+                        return client.query((0, _dsl.Q)(BANNERS_DOCTYPE).getById(banner._id));
+
+                      case 3:
+                        _context3.t1 = _context3.sent;
+                        stored = (0, _context3.t0)(_context3.t1);
+
+                        if (stored) {
+                          _context3.next = 7;
+                          break;
+                        }
+
+                        return _context3.abrupt("return", {
+                          data: null
+                        });
+
+                      case 7:
+                        if (!isDismissed(stored)) {
+                          _context3.next = 9;
+                          break;
+                        }
+
+                        return _context3.abrupt("return", {
+                          data: stored
+                        });
+
+                      case 9:
+                        return _context3.abrupt("return", client.save(_objectSpread(_objectSpread({}, stored), {}, {
+                          _type: BANNERS_DOCTYPE,
+                          dismissedAt: at
+                        })));
+
+                      case 10:
+                      case "end":
+                        return _context3.stop();
+                    }
+                  }
+                }, _callee3);
+              }));
+
+              return function write() {
+                return _ref6.apply(this, arguments);
+              };
+            }();
+
+            _context4.prev = 5;
+            _context4.next = 8;
+            return write();
+
+          case 8:
+            return _context4.abrupt("return", _context4.sent);
+
+          case 11:
+            _context4.prev = 11;
+            _context4.t0 = _context4["catch"](5);
+
+            if (isConflict(_context4.t0)) {
+              _context4.next = 15;
+              break;
+            }
+
+            throw _context4.t0;
+
+          case 15:
+            return _context4.abrupt("return", write());
+
+          case 16:
+          case "end":
+            return _context4.stop();
+        }
+      }
+    }, _callee4, null, [[5, 11]]);
+  }));
+
+  return function dismiss(_x4, _x5) {
+    return _ref4.apply(this, arguments);
+  };
+}();
+
+exports.dismiss = dismiss;