cozy-client 60.30.6 → 60.31.0

package/dist/models/banner.js

@@ -0,0 +1,978 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dismiss = exports.getActiveBanner = exports.getActiveBanners = exports.getVisibleBanners = exports.getCta = exports.getSurface = exports.getSeverity = exports.byPriority = exports.isInWindow = exports.isDismissed = exports.isSupported = exports.isTrusted = exports.buildBannersQuery = exports.BANNERS_QUERY_NAME = exports.KNOWN_SURFACES = exports.KNOWN_SEVERITIES = exports.SUPPORTED_DOCTYPE_VERSION = exports.BANNERS_DOCTYPE = void 0;
+
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+
+var _isValid = _interopRequireDefault(require("date-fns/isValid"));
+
+var _parseISO = _interopRequireDefault(require("date-fns/parseISO"));
+
+var _dsl = require("../queries/dsl");
+
+var _utils = require("./utils");
+
+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; }
+
+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; }
+
+var BANNERS_DOCTYPE = 'io.cozy.banners';
+/**
+ * The version of the io.cozy.banners shape this code was written against.
+ * A document declaring a higher cozyMetadata.doctypeVersion is skipped.
+ */
+
+exports.BANNERS_DOCTYPE = BANNERS_DOCTYPE;
+var SUPPORTED_DOCTYPE_VERSION = 1;
+/**
+ * The severities the doctype defines. A value outside this list is rendered
+ * with DEFAULT_SEVERITY. Frozen because the fallbacks read it at call time, so
+ * a consumer mutating it would change what every other consumer renders.
+ *
+ * @type {readonly BannerSeverity[]}
+ */
+
+exports.SUPPORTED_DOCTYPE_VERSION = SUPPORTED_DOCTYPE_VERSION;
+var KNOWN_SEVERITIES = ['info', 'warning', 'error'];
+exports.KNOWN_SEVERITIES = KNOWN_SEVERITIES;
+Object.freeze(KNOWN_SEVERITIES);
+/**
+ * The surfaces the doctype defines. A value outside this list is rendered on
+ * DEFAULT_SURFACE. Frozen for the same reason as KNOWN_SEVERITIES.
+ *
+ * @type {readonly BannerSurface[]}
+ */
+
+var KNOWN_SURFACES = ['banner', 'modal'];
+exports.KNOWN_SURFACES = KNOWN_SURFACES;
+Object.freeze(KNOWN_SURFACES);
+/** @type {BannerSeverity} */
+
+var DEFAULT_SEVERITY = 'warning';
+/** @type {BannerSurface} */
+
+var DEFAULT_SURFACE = 'banner';
+var STACK_APP = 'stack';
+/**
+ * @typedef {object} BannerCta
+ * @property {string} label - The label, plain text, in the same language as the banner text
+ * @property {string} url - Absolute https URL the label points to
+ */
+
+/**
+ * @typedef {'quota'|'billing'|'trial'|'account'|'system'} BannerCategory
+ */
+
+/**
+ * @typedef {'info'|'warning'|'error'} BannerSeverity
+ */
+
+/**
+ * @typedef {'banner'|'modal'} BannerSurface
+ */
+
+/**
+ * @typedef {object} VisibleBannersOptions
+ * @property {Date} [now] - The current time, defaults to now
+ * @property {number} [supportedDoctypeVersion] - The highest version this client handles
+ */
+
+/**
+ * @typedef {import("../CozyClient").default} BannerClient A CozyClient instance
+ */
+
+/**
+ * @typedef {object} DismissOptions
+ * @property {string} [dismissedAt] - The timestamp to record, defaults to now
+ */
+
+/**
+ * @typedef {object} Banner An io.cozy.banners document
+ * @property {string} [_id] - Identifier of the document, minted by CouchDB
+ * @property {string} [_rev] - Revision identifier of the document
+ * @property {string} bannerId - Identifier of the banner itself
+ * @property {BannerCategory} category - What the banner is about
+ * @property {BannerSeverity} severity - info, warning or error
+ * @property {BannerSurface} surface - banner or modal
+ * @property {string} text - The message, in the language given by lang
+ * @property {string} lang - BCP 47 tag of the language text is written in
+ * @property {BannerCta|null} [cta] - Optional call to action
+ * @property {boolean} dismissible - Whether the client offers a dismiss control
+ * @property {string|null} [dismissedAt] - When the user dismissed this banner
+ * @property {number} priority - Sort order, highest first
+ * @property {string} startsAt - Start of the validity window, inclusive
+ * @property {string|null} [endsAt] - End of the validity window, exclusive
+ * @property {object} [source] - What produced the document
+ * @property {object} [cozyMetadata] - Document lifecycle metadata
+ */
+
+/**
+ * The name the banners query is stored under. It is namespaced rather than the
+ * bare doctype: `client.query` keys the store entry on this name but keys the
+ * in-flight promise on the definition, so an unrelated consumer naming its own
+ * `io.cozy.banners` query would make this one resolve nothing while that query
+ * is loading.
+ */
+
+var BANNERS_QUERY_NAME = "".concat(BANNERS_DOCTYPE, "/all");
+/**
+ * Query for the banners of the current instance.
+ *
+ * The query is named so every consumer shares one store entry rather than
+ * minting a new one per call, and the limit is lifted because the whole
+ * collection is read in full.
+ *
+ * @returns {import('../types').Query} A named query
+ */
+
+exports.BANNERS_QUERY_NAME = BANNERS_QUERY_NAME;
+
+var buildBannersQuery = function buildBannersQuery() {
+  return {
+    definition: (0, _dsl.Q)(BANNERS_DOCTYPE).UNSAFE_noLimit(),
+    options: {
+      as: BANNERS_QUERY_NAME
+    }
+  };
+};
+/**
+ * Documents are only trusted when the stack wrote them. Permissions scope by
+ * doctype and verb, never by field, so any application allowed to record a
+ * dismissal is also able to author a document that looks like a platform
+ * message.
+ *
+ * This is not a security boundary, and should not be read as one. The stack
+ * does not own this field: cozy-client keeps whatever `cozyMetadata` the caller
+ * passes (CozyClient.js, ensureCozyMetadata spreads it last), so an application
+ * can set `createdByApp: 'stack'` on a document it authored itself and pass
+ * this check. It catches an application writing under its own name, which is
+ * the ordinary mistake, not one deliberately impersonating the stack. Enforcing
+ * that needs the doctype to be stack write only on the server side.
+ *
+ * It also only speaks to who created the document. An application holding write
+ * permission can rewrite the fields of a stack authored one, which the platform
+ * cannot prevent, so a client escapes text and never interprets markup in it.
+ *
+ * @param {Banner} banner - The document to check
+ * @returns {boolean} True when the stack is the author
+ */
+
+
+exports.buildBannersQuery = buildBannersQuery;
+
+var isTrusted = function isTrusted(banner) {
+  return (0, _utils.getCreatedByApp)(banner) === STACK_APP;
+};
+/**
+ * cozy-stack writes numbers as strings in places, `cozyMetadata` declares
+ * `doctypeVersion` that way platform wide, so a value is parsed rather than
+ * compared as it comes. `Number()` alone is not enough: it maps null, "", false
+ * and [] to a finite 0, which would read as a real version or a real priority
+ * rather than as an unusable value, so only a number or a non blank string is
+ * parsed at all.
+ *
+ * @param {any} value - The value to read
+ * @param {number} fallback - What an absent or unusable value means
+ * @returns {number} The parsed number, or the fallback
+ */
+
+
+exports.isTrusted = isTrusted;
+
+var toNumber = function toNumber(value, fallback) {
+  var parsed = typeof value === 'number' || typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+/**
+ * @param {Banner} banner - The document to read
+ * @returns {number} The version, defaulting to 1 for a missing or unusable one
+ */
+
+
+var doctypeVersion = function doctypeVersion(banner) {
+  var _banner$cozyMetadata;
+
+  return toNumber(banner === null || banner === void 0 ? void 0 : (_banner$cozyMetadata = banner.cozyMetadata) === null || _banner$cozyMetadata === void 0 ? void 0 : _banner$cozyMetadata.doctypeVersion, 1);
+};
+/**
+ * @param {Banner} banner - The document to check
+ * @param {number} [supportedVersion] - The highest version this client handles
+ * @returns {boolean} True when the shape is one this client can read
+ */
+
+
+var isSupported = function isSupported(banner) {
+  var supportedVersion = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : SUPPORTED_DOCTYPE_VERSION;
+  return doctypeVersion(banner) <= supportedVersion;
+};
+/**
+ * A null value and an absent key mean the same thing for dismissedAt and
+ * endsAt, and `new Date(null)` is the Unix epoch rather than "no date", so
+ * every date is null checked before being parsed.
+ *
+ * Returns a timestamp rather than a Date so the comparisons stay primitive,
+ * and NaN when the value is present but unparseable, which the callers reject
+ * rather than silently treating as "no bound".
+ *
+ * This is the only date parser in the file. `Date.parse` is deliberately not
+ * used anywhere: it accepts implementation defined formats that `parseISO`
+ * rejects, and the two disagree by the local UTC offset on a date only value,
+ * so mixing them would give one document two different instants.
+ *
+ * @param {string|null|undefined} value - An ISO 8601 timestamp
+ * @returns {number|null} The timestamp, NaN when malformed, null when absent
+ */
+
+
+exports.isSupported = isSupported;
+
+var toTime = function toTime(value) {
+  if (value === null || value === undefined) return null;
+  var parsed = (0, _parseISO.default)(value);
+  return (0, _isValid.default)(parsed) ? parsed.getTime() : NaN;
+};
+/**
+ * @param {Banner} banner - The document to check
+ * @returns {boolean} True when the user dismissed it
+ */
+
+
+var isDismissed = function isDismissed(banner) {
+  return (banner === null || banner === void 0 ? void 0 : banner.dismissedAt) != null;
+};
+/**
+ * The window is inclusive on startsAt and exclusive on endsAt, and an absent
+ * endsAt is open ended. A malformed bound hides the banner: a document whose
+ * window cannot be read is not one a client can decide to show.
+ *
+ * An absent startsAt hides it too. The doctype makes cta, dismissedAt and
+ * endsAt the only fields that may be missing, so a document with no lower bound
+ * is not open ended, it is unreadable. Treating it as "no bound" would make the
+ * missing field more permissive than a malformed one, and would let anything
+ * able to rewrite the document turn a scheduled banner into a permanent one by
+ * deleting both bounds.
+ *
+ * @param {Banner} banner - The document to check
+ * @param {Date} [now] - The current time
+ * @returns {boolean} True when the banner applies at that time
+ */
+
+
+exports.isDismissed = isDismissed;
+
+var isInWindow = function isInWindow(banner) {
+  var now = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Date();
+  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)) return false;
+  if (Number.isNaN(endsAt)) return false;
+  var at = now.getTime();
+  if (Number.isNaN(at)) return false;
+  if (at < startsAt) return false;
+  if (endsAt !== null && at >= endsAt) return false;
+  return true;
+};
+
+exports.isInWindow = isInWindow;
+
+var priorityOf = function priorityOf(banner) {
+  return toNumber(banner === null || banner === void 0 ? void 0 : banner.priority, 0);
+};
+/**
+ * Highest priority first, then bannerId ascending so every client orders
+ * identically when priorities are equal.
+ *
+ * The tie break compares code units rather than calling localeCompare, whose
+ * result depends on the runtime's locale and ICU build. A missing or non
+ * numeric priority sorts as 0 instead of producing NaN, which would make the
+ * comparator intransitive and the sort order engine defined.
+ *
+ * Documents that lost their bannerId fall back on _id, as the deduplication
+ * does, so two of them do not compare equal and land in whatever order the
+ * database returned them in.
+ *
+ * @param {Banner} a - A banner
+ * @param {Banner} b - Another banner
+ * @returns {number} The comparison result
+ */
+
+
+var byPriority = function byPriority(a, b) {
+  var _ref, _a$bannerId, _ref2, _b$bannerId;
+
+  var byRank = priorityOf(b) - priorityOf(a);
+  if (byRank !== 0) return byRank;
+  var idA = String((_ref = (_a$bannerId = a === null || a === void 0 ? void 0 : a.bannerId) !== null && _a$bannerId !== void 0 ? _a$bannerId : a === null || a === void 0 ? void 0 : a._id) !== null && _ref !== void 0 ? _ref : '');
+  var idB = String((_ref2 = (_b$bannerId = b === null || b === void 0 ? void 0 : b.bannerId) !== null && _b$bannerId !== void 0 ? _b$bannerId : b === null || b === void 0 ? void 0 : b._id) !== null && _ref2 !== void 0 ? _ref2 : '');
+  if (idA < idB) return -1;
+  if (idA > idB) return 1;
+  return 0;
+};
+/**
+ * @param {Banner} banner - The document to read
+ * @returns {BannerSeverity} The severity to render, falling back when unknown
+ */
+
+
+exports.byPriority = byPriority;
+
+var getSeverity = function getSeverity(banner) {
+  return KNOWN_SEVERITIES.includes(banner === null || banner === void 0 ? void 0 : banner.severity) ? banner.severity : DEFAULT_SEVERITY;
+};
+/**
+ * @param {Banner} banner - The document to read
+ * @returns {BannerSurface} The surface to render on, falling back when unknown
+ */
+
+
+exports.getSeverity = getSeverity;
+
+var getSurface = function getSurface(banner) {
+  return KNOWN_SURFACES.includes(banner === null || banner === void 0 ? void 0 : banner.surface) ? banner.surface : DEFAULT_SURFACE;
+};
+/**
+ * Whitespace plus the zero width characters `trim` leaves behind. A label made
+ * only of these renders as a button with nothing on it. They are stripped to
+ * decide whether the label is empty, never from the label itself, so a script
+ * that uses a zero width joiner between glyphs keeps it.
+ */
+
+
+exports.getSurface = getSurface;
+var BLANK = /[\s\u200B-\u200D\uFEFF]/g;
+/**
+ * A call to action is only rendered when it carries a label and points at
+ * https, so a locally authored document cannot turn into a platform styled
+ * link on any scheme, and no banner renders a button the user cannot read.
+ * The scheme is matched case insensitively since URL schemes are.
+ *
+ * @param {Banner} banner - The document to read
+ * @returns {BannerCta|null} The call to action, or null when there is none to show
+ */
+
+var getCta = function getCta(banner) {
+  var cta = banner === null || banner === void 0 ? void 0 : banner.cta;
+  if (!cta || typeof cta.url !== 'string') return null;
+
+  if (typeof cta.label !== 'string' || cta.label.replace(BLANK, '') === '') {
+    return null;
+  }
+
+  return isHttpsUrl(cta.url) ? cta : null;
+};
+/**
+ * A prefix check accepts "https://" and "https:example.org", which do not point
+ * where they look like they point, so the value is parsed instead. The parser
+ * rejects an https URL with no host outright, so reaching the scheme comparison
+ * already means there is one.
+ *
+ * @param {string} raw - The candidate URL
+ * @returns {boolean} True when it is an absolute https URL
+ */
+
+
+exports.getCta = getCta;
+
+var isHttpsUrl = function isHttpsUrl(raw) {
+  try {
+    return new URL(raw).protocol === 'https:';
+  } catch (error) {
+    return false;
+  }
+};
+
+var updatedAtOf = function updatedAtOf(banner) {
+  var _banner$cozyMetadata2;
+
+  var at = toTime(banner === null || banner === void 0 ? void 0 : (_banner$cozyMetadata2 = banner.cozyMetadata) === null || _banner$cozyMetadata2 === void 0 ? void 0 : _banner$cozyMetadata2.updatedAt);
+  return Number.isFinite(at) ? at : 0;
+};
+/**
+ * Orders two documents carrying the same bannerId, most relevant first. The
+ * highest supported doctypeVersion wins; equal versions fall back on the most
+ * recently written document and then on _id, so the winner never depends on
+ * the order the rows came back in.
+ *
+ * @param {Banner} candidate - The document being considered
+ * @param {Banner} current - The document currently held
+ * @returns {boolean} True when candidate should replace current
+ */
+
+
+var supersedes = function supersedes(candidate, current) {
+  var _candidate$_id, _current$_id;
+
+  var byVersion = doctypeVersion(candidate) - doctypeVersion(current);
+  if (byVersion !== 0) return byVersion > 0;
+  var byUpdate = updatedAtOf(candidate) - updatedAtOf(current);
+  if (byUpdate !== 0) return byUpdate > 0;
+  return String((_candidate$_id = candidate === null || candidate === void 0 ? void 0 : candidate._id) !== null && _candidate$_id !== void 0 ? _candidate$_id : '') < String((_current$_id = current === null || current === void 0 ? void 0 : current._id) !== null && _current$_id !== void 0 ? _current$_id : '');
+};
+/**
+ * The identity two documents are grouped and dismissed under. bannerId and _id
+ * are kept in separate namespaces: sharing one would let a document whose _id
+ * happens to equal another document's bannerId dismiss or supersede it. A
+ * document carrying neither keys on itself, so unrelated ones do not collapse
+ * onto a single `undefined` key.
+ *
+ * @param {Banner} banner - The document to key
+ * @returns {string|Banner} The grouping key
+ */
+
+
+var groupKey = function groupKey(banner) {
+  if ((banner === null || banner === void 0 ? void 0 : banner.bannerId) != null) return "bannerId:".concat(banner.bannerId);
+  if ((banner === null || banner === void 0 ? void 0 : banner._id) != null) return "_id:".concat(banner._id);
+  return banner;
+};
+/**
+ * Keeps the highest supported version of each bannerId. Without this the
+ * documents materialized on both sides of a version bump render twice.
+ *
+ * @param {Banner[]} banners - The documents to reduce
+ * @returns {Banner[]} One document per bannerId
+ */
+
+
+var keepHighestVersion = function keepHighestVersion(banners) {
+  var best = new Map();
+
+  var _iterator = _createForOfIteratorHelper(banners),
+      _step;
+
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var banner = _step.value;
+      var key = groupKey(banner);
+      var current = best.get(key);
+
+      if (current === undefined || supersedes(banner, current)) {
+        best.set(key, banner);
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+
+  return Array.from(best.values());
+};
+/**
+ * The banners a client displays, in the order it displays them.
+ *
+ * A dismissal applies to the bannerId rather than to the single document
+ * carrying it, so a banner dismissed against one version stays hidden once the
+ * client moves to another. Deduplication runs last, on the documents that are
+ * actually renderable, so a newer version sitting outside its validity window
+ * never suppresses the older one that is still live.
+ *
+ * @param {Banner[]} banners - The documents read from the doctype
+ * @param {VisibleBannersOptions} [options] - Options
+ * @returns {Banner[]} The visible banners, ordered
+ */
+
+
+var getVisibleBanners = function getVisibleBanners(banners) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var now = options.now instanceof Date && !Number.isNaN(options.now.getTime()) ? options.now : new Date(); // Validated rather than defaulted with ??, which only guards null and
+  // undefined: a NaN reaching isSupported makes every comparison false and
+  // hides every banner with no error.
+
+  var supportedVersion = toNumber(options.supportedDoctypeVersion, SUPPORTED_DOCTYPE_VERSION); // Only documents the stack wrote are read at all, dismissals included: a
+  // dismissal on a document an application authored must not hide a platform
+  // message.
+
+  var trusted = (banners !== null && banners !== void 0 ? banners : []).filter(isTrusted); // Collected before the version filter: a dismissal recorded by a client on a
+  // newer version of the document still applies to a client that only reads the
+  // older one, which would otherwise render a banner the user has closed.
+
+  var dismissed = new Set(trusted.filter(isDismissed).map(groupKey));
+  return keepHighestVersion(trusted.filter(function (banner) {
+    return isSupported(banner, supportedVersion) && !dismissed.has(groupKey(banner)) && isInWindow(banner, now);
+  })).sort(byPriority).map(resolve);
+};
+/**
+ * Applies every fallback the doctype defines, so a caller renders what it is
+ * given instead of reaching for the helpers itself: an unknown severity or
+ * surface is already replaced, and a call to action that is not an absolute
+ * https URL is already dropped.
+ *
+ * The doctype guarantees that a non dismissible banner on the modal surface
+ * carries a call to action, so the user is never left without a way out.
+ * Dropping an unusable one would break that guarantee and paint a blocking
+ * dialog with no dismiss control and no button, so the banner falls back to the
+ * surface that is never blocking.
+ *
+ * The document is returned unchanged when no fallback applied. The store relies
+ * on referential equality, and copying every banner on every read would make a
+ * memoized renderer repaint on every poll tick. An absent cta is not left
+ * absent though: the resolved shape always carries the key, so a caller reads
+ * one value rather than checking for both null and undefined.
+ *
+ * @param {Banner} banner - A visible banner
+ * @returns {Banner} The same banner, ready to render
+ */
+
+
+exports.getVisibleBanners = getVisibleBanners;
+
+var resolve = function resolve(banner) {
+  var severity = getSeverity(banner);
+  var cta = getCta(banner);
+  var surface = getSurface(banner) === 'modal' && cta === null && !(banner !== null && banner !== void 0 && banner.dismissible) ? DEFAULT_SURFACE : getSurface(banner);
+
+  if (severity === (banner === null || banner === void 0 ? void 0 : banner.severity) && surface === (banner === null || banner === void 0 ? void 0 : banner.surface) && cta === (banner === null || banner === void 0 ? void 0 : banner.cta)) {
+    return banner;
+  }
+
+  return _objectSpread(_objectSpread({}, banner), {}, {
+    severity: severity,
+    surface: surface,
+    cta: cta
+  });
+};
+/**
+ * A conflict reaches this code in two shapes: a FetchError from the stack,
+ * which carries the HTTP status, and a PouchDB conflict, which the pouch link
+ * rewraps into a plain Error that only keeps the message.
+ *
+ * @param {Error & {status?: number}} error - The error to classify
+ * @returns {boolean} True when the write lost a revision race
+ */
+
+
+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 : '');
+};
+/**
+ * `client.query` does not always resolve a response. It resolves undefined when
+ * the client was built with an `onError` callback, which swallows the rejection,
+ * and when a query named the same as this one is already in flight with a
+ * different definition. Both are indistinguishable from an empty collection
+ * once the response is read, so they are rejected here instead: reporting a
+ * failed read as "there is nothing" hides a banner the user should see, and
+ * reports a dismissal that never happened as done.
+ *
+ * @param {object} response - The response of a query
+ * @returns {object} The same response
+ * @throws {Error} When the query resolved nothing
+ */
+
+
+var requireResponse = function requireResponse(response) {
+  if (response === null || response === undefined) {
+    throw new Error("The ".concat(BANNERS_DOCTYPE, " query resolved nothing. Either the client swallowed the error through its onError option, or another query is registered under the name ").concat(BANNERS_QUERY_NAME, "."));
+  }
+
+  return response;
+};
+/**
+ * The links disagree on how a missing document comes back: the stack link
+ * resolves `{data: null}` while the pouch link resolves `{data: []}`, and an
+ * empty array is truthy. Both mean there is nothing to write to.
+ *
+ * @param {object} response - The response of a getById query
+ * @returns {Banner|null} The document, or null when there is none
+ */
+
+
+var readOne = function readOne(response) {
+  var _requireResponse;
+
+  var data = (_requireResponse = requireResponse(response)) === null || _requireResponse === void 0 ? void 0 : _requireResponse.data;
+  var doc = Array.isArray(data) ? data[0] : data;
+  return doc !== null && doc !== void 0 && doc._id ? doc : null;
+};
+/**
+ * The banners to display, in the order to display them. This is the entry
+ * point: it queries the doctype and applies every rule the contract defines,
+ * so a caller does not compose the helpers itself.
+ *
+ * The whole collection is read rather than filtered by a Mango selector. The
+ * validity window, the dismissal and the version filter would each need their
+ * own index, and the doctype keeps the collection small on purpose: the stack
+ * deletes a banner when its condition clears.
+ *
+ * @param {BannerClient} client - A CozyClient instance
+ * @param {VisibleBannersOptions} [options] - Options
+ * @returns {Promise<Banner[]>} The banners to display, ready to render
+ * @throws {Error} When the doctype cannot be read, a missing permission included
+ */
+
+
+var getActiveBanners = /*#__PURE__*/function () {
+  var _ref3 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(client) {
+    var _requireResponse2;
+
+    var options,
+        _buildBannersQuery,
+        definition,
+        queryOptions,
+        data,
+        _args = arguments;
+
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) {
+        switch (_context.prev = _context.next) {
+          case 0:
+            options = _args.length > 1 && _args[1] !== undefined ? _args[1] : {};
+            _buildBannersQuery = buildBannersQuery(), definition = _buildBannersQuery.definition, queryOptions = _buildBannersQuery.options;
+            _context.t1 = requireResponse;
+            _context.next = 5;
+            return client.query(definition, queryOptions);
+
+          case 5:
+            _context.t2 = _context.sent;
+            _context.t3 = _requireResponse2 = (0, _context.t1)(_context.t2);
+            _context.t0 = _context.t3 === null;
+
+            if (_context.t0) {
+              _context.next = 10;
+              break;
+            }
+
+            _context.t0 = _requireResponse2 === void 0;
+
+          case 10:
+            if (!_context.t0) {
+              _context.next = 14;
+              break;
+            }
+
+            _context.t4 = void 0;
+            _context.next = 15;
+            break;
+
+          case 14:
+            _context.t4 = _requireResponse2.data;
+
+          case 15:
+            data = _context.t4;
+            return _context.abrupt("return", getVisibleBanners(Array.isArray(data) ? data : [], options));
+
+          case 17:
+          case "end":
+            return _context.stop();
+        }
+      }
+    }, _callee);
+  }));
+
+  return function getActiveBanners(_x) {
+    return _ref3.apply(this, arguments);
+  };
+}();
+/**
+ * The single banner to display, for a surface that shows one at a time.
+ *
+ * @param {BannerClient} client - A CozyClient instance
+ * @param {VisibleBannersOptions} [options] - Options
+ * @returns {Promise<Banner|null>} The highest priority banner, or null
+ * @throws {Error} When the doctype cannot be read, a missing permission included
+ */
+
+
+exports.getActiveBanners = getActiveBanners;
+
+var getActiveBanner = /*#__PURE__*/function () {
+  var _ref4 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee2(client) {
+    var options,
+        _yield$getActiveBanne,
+        _yield$getActiveBanne2,
+        first,
+        _args2 = arguments;
+
+    return _regenerator.default.wrap(function _callee2$(_context2) {
+      while (1) {
+        switch (_context2.prev = _context2.next) {
+          case 0:
+            options = _args2.length > 1 && _args2[1] !== undefined ? _args2[1] : {};
+            _context2.next = 3;
+            return getActiveBanners(client, options);
+
+          case 3:
+            _yield$getActiveBanne = _context2.sent;
+            _yield$getActiveBanne2 = (0, _slicedToArray2.default)(_yield$getActiveBanne, 1);
+            first = _yield$getActiveBanne2[0];
+            return _context2.abrupt("return", first !== null && first !== void 0 ? first : null);
+
+          case 7:
+          case "end":
+            return _context2.stop();
+        }
+      }
+    }, _callee2);
+  }));
+
+  return function getActiveBanner(_x2) {
+    return _ref4.apply(this, arguments);
+  };
+}();
+/**
+ * Records a dismissal. The field is idempotent, so a conflict is resolved by
+ * reading the document again and writing the value on the fresh revision.
+ *
+ * The dismissal is written to the document it is given. During a doctypeVersion
+ * migration the stack materializes the same bannerId under several versions,
+ * and the sibling documents are not reached from here.
+ *
+ * @param {BannerClient} client - A CozyClient instance
+ * @param {Banner & {_id: string}} banner - The banner to dismiss, as stored
+ * @param {DismissOptions} [options] - Options
+ * @returns {Promise<{data: Banner|null}>} The dismissed document, null when it is gone
+ */
+
+
+exports.getActiveBanner = getActiveBanner;
+
+var dismiss = /*#__PURE__*/function () {
+  var _ref5 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee3(client, banner) {
+    var _options$dismissedAt;
+
+    var options,
+        dismissedAt,
+        id,
+        siblings,
+        result,
+        _iterator2,
+        _step2,
+        sibling,
+        written,
+        _args3 = arguments;
+
+    return _regenerator.default.wrap(function _callee3$(_context3) {
+      while (1) {
+        switch (_context3.prev = _context3.next) {
+          case 0:
+            options = _args3.length > 2 && _args3[2] !== undefined ? _args3[2] : {};
+            dismissedAt = (_options$dismissedAt = options.dismissedAt) !== null && _options$dismissedAt !== void 0 ? _options$dismissedAt : new Date().toISOString();
+            id = banner === null || banner === void 0 ? void 0 : banner._id;
+
+            if (id) {
+              _context3.next = 5;
+              break;
+            }
+
+            throw new Error('A banner needs an _id to be dismissed');
+
+          case 5:
+            _context3.next = 7;
+            return findSiblings(client, banner);
+
+          case 7:
+            siblings = _context3.sent;
+            result = {
+              data: null
+            };
+            _iterator2 = _createForOfIteratorHelper(siblings);
+            _context3.prev = 10;
+
+            _iterator2.s();
+
+          case 12:
+            if ((_step2 = _iterator2.n()).done) {
+              _context3.next = 20;
+              break;
+            }
+
+            sibling = _step2.value;
+            _context3.next = 16;
+            return writeDismissal(client, sibling._id, dismissedAt);
+
+          case 16:
+            written = _context3.sent;
+            // The caller is answered with the document it asked about.
+            if (sibling._id === id) result = written;
+
+          case 18:
+            _context3.next = 12;
+            break;
+
+          case 20:
+            _context3.next = 25;
+            break;
+
+          case 22:
+            _context3.prev = 22;
+            _context3.t0 = _context3["catch"](10);
+
+            _iterator2.e(_context3.t0);
+
+          case 25:
+            _context3.prev = 25;
+
+            _iterator2.f();
+
+            return _context3.finish(25);
+
+          case 28:
+            return _context3.abrupt("return", result);
+
+          case 29:
+          case "end":
+            return _context3.stop();
+        }
+      }
+    }, _callee3, null, [[10, 22, 25, 28]]);
+  }));
+
+  return function dismiss(_x3, _x4) {
+    return _ref5.apply(this, arguments);
+  };
+}();
+/**
+ * Every stored document sharing the banner's identity, the one the caller holds
+ * included. The whole collection is read because the versions of a bannerId are
+ * not reachable by id, and the doctype keeps the collection small on purpose.
+ *
+ * @param {BannerClient} client - A CozyClient instance
+ * @param {Banner} banner - The banner being dismissed
+ * @returns {Promise<Banner[]>} The documents to write the dismissal to
+ */
+
+
+exports.dismiss = dismiss;
+
+var findSiblings = /*#__PURE__*/function () {
+  var _ref6 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee4(client, banner) {
+    var _buildBannersQuery2, definition, queryOptions, response, data, key, siblings;
+
+    return _regenerator.default.wrap(function _callee4$(_context4) {
+      while (1) {
+        switch (_context4.prev = _context4.next) {
+          case 0:
+            _buildBannersQuery2 = buildBannersQuery(), definition = _buildBannersQuery2.definition, queryOptions = _buildBannersQuery2.options;
+            _context4.t0 = requireResponse;
+            _context4.next = 4;
+            return client.query(definition, queryOptions);
+
+          case 4:
+            _context4.t1 = _context4.sent;
+            response = (0, _context4.t0)(_context4.t1);
+            data = Array.isArray(response.data) ? response.data : [];
+            key = groupKey(banner);
+            siblings = data.filter(function (doc) {
+              return (doc === null || doc === void 0 ? void 0 : doc._id) && groupKey(doc) === key;
+            }); // The document may have been deleted between the read and the click, in which
+            // case there is nothing left to write to.
+
+            return _context4.abrupt("return", siblings.length > 0 ? siblings : []);
+
+          case 10:
+          case "end":
+            return _context4.stop();
+        }
+      }
+    }, _callee4);
+  }));
+
+  return function findSiblings(_x5, _x6) {
+    return _ref6.apply(this, arguments);
+  };
+}();
+/** How many times the write is attempted before a conflict reaches the caller. */
+
+
+var DISMISS_ATTEMPTS = 2;
+
+var writeDismissal = /*#__PURE__*/function () {
+  var _ref7 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee5(client, id, dismissedAt) {
+    var attempt, stored;
+    return _regenerator.default.wrap(function _callee5$(_context5) {
+      while (1) {
+        switch (_context5.prev = _context5.next) {
+          case 0:
+            attempt = 1;
+
+          case 1:
+            if (!(attempt <= DISMISS_ATTEMPTS)) {
+              _context5.next = 24;
+              break;
+            }
+
+            _context5.t0 = readOne;
+            _context5.next = 5;
+            return client.query((0, _dsl.Q)(BANNERS_DOCTYPE).getById(id));
+
+          case 5:
+            _context5.t1 = _context5.sent;
+            stored = (0, _context5.t0)(_context5.t1);
+
+            if (stored) {
+              _context5.next = 9;
+              break;
+            }
+
+            return _context5.abrupt("return", {
+              data: null
+            });
+
+          case 9:
+            if (!isDismissed(stored)) {
+              _context5.next = 11;
+              break;
+            }
+
+            return _context5.abrupt("return", {
+              data: stored
+            });
+
+          case 11:
+            _context5.prev = 11;
+            _context5.next = 14;
+            return client.save(_objectSpread(_objectSpread({}, stored), {}, {
+              _type: BANNERS_DOCTYPE,
+              dismissedAt: dismissedAt
+            }));
+
+          case 14:
+            return _context5.abrupt("return", _context5.sent);
+
+          case 17:
+            _context5.prev = 17;
+            _context5.t2 = _context5["catch"](11);
+
+            if (!(!isConflict(_context5.t2) || attempt === DISMISS_ATTEMPTS)) {
+              _context5.next = 21;
+              break;
+            }
+
+            throw _context5.t2;
+
+          case 21:
+            attempt++;
+            _context5.next = 1;
+            break;
+
+          case 24:
+          case "end":
+            return _context5.stop();
+        }
+      }
+    }, _callee5, null, [[11, 17]]);
+  }));
+
+  return function writeDismissal(_x7, _x8, _x9) {
+    return _ref7.apply(this, arguments);
+  };
+}();