@miso.ai/client-sdk-core 1.14.0-beta.2 → 1.14.0-beta.4

package/dist/cjs/api/ask.js

@@ -42,7 +42,11 @@ class Ask extends _base.default {
   }
 
   /**
-   * Retrieve multiple question-answer pairs at once.
+   * Retrieve multiple question-answer pairs at once: an iterable that polls
+   * the answers endpoint, like questions(). The id set is mutable between
+   * polls: `question_ids` may be a function returning the id array, resolved
+   * for every poll, and a fixed initial array settles out record by record
+   * (see Answers).
    */
   async answers(payload, options = {}) {
     if (Array.isArray(payload)) {
@@ -50,7 +54,9 @@ class Ask extends _base.default {
         question_ids: payload
       };
     }
-    return this._run(NAME.ANSWERS, payload, options);
+    return new Answers(this, payload, Object.assign({
+      immediate: true
+    }, options));
   }
   async relatedQuestions(payload, options = {}) {
     return this._run(NAME.RELATED_QUESTIONS, payload, options);
@@ -95,6 +101,76 @@ class Answer extends _iterable.IdBasedIterableApiStub {
     return this._id;
   }
 }
+
+/**
+ * The answer contents of a set of questions, polled until settled — the id
+ * set is mutable between polls, and the stream ends when it runs dry. The
+ * question ids may be given as a function returning the id array, resolved
+ * for every poll (settled ids drop out, new ones join, at the provider's
+ * discretion); a fixed initial id array is mutable all the same — its ids
+ * settle out as their records come back finished (_settle). Each fetch's
+ * issue order acts as the response revision, so a late, outdated response
+ * is discarded by the polling.
+ */
+class Answers extends _iterable.IterableApiStub {
+  constructor(api, payload, options = {}) {
+    super(mergeCustomApiIterator(api, options));
+    this._api = api;
+    this._payload = payload;
+    const {
+      question_ids
+    } = payload;
+    this._pending = typeof question_ids === 'function' ? undefined : new Set(question_ids || []);
+  }
+  async _get(options) {
+    // a plain one-shot read of the current ids' answers
+    return this._api._run(NAME.ANSWERS, Object.assign({}, this._payload, {
+      question_ids: this._questionIds()
+    }), options);
+  }
+  _questionIds() {
+    return this._pending ? [...this._pending] : this._payload.question_ids();
+  }
+
+  // a fixed id set settles by the records themselves: a record that came
+  // back with its finished answer needs no further polling
+  _settle(response) {
+    if (!this._pending || !Array.isArray(response)) {
+      return;
+    }
+    for (const record of response) {
+      if (record && record.answer !== undefined && record.finished !== false) {
+        this._pending.delete(record.question_id);
+      }
+    }
+  }
+  _fetch() {
+    let index = 0;
+    return async ({
+      signal
+    } = {}) => {
+      const i = ++index; // taken at issue time: a stale response resolves with a lower revision
+      const question_ids = this._questionIds();
+      if (!question_ids || !question_ids.length) {
+        return [undefined, true, i]; // nothing left to fetch; the stream ends
+      }
+      // TODO: use single answer endpoint when array length = 1
+      const response = await this._api._run(NAME.ANSWERS, Object.assign({}, this._payload, {
+        question_ids
+      }), {
+        signal
+      });
+      this._settle(response);
+      return [response, false, i];
+    };
+  }
+
+  // any response is progress for the stall timeout: the record-diff test of
+  // the base class reads a single answer's shape, not an array of records
+  _isUpdated() {
+    return true;
+  }
+}
 class SearchResult extends _iterable.IdBasedIterableApiStub {
   constructor(api, response, options = {}) {
     super(api, '_searchGet', response.question_id, mergeCustomApiIterator(api, options));

package/dist/cjs/api/base.js

@@ -16,6 +16,18 @@ class ApiBase extends _commons.Component {
     this.context = api._client.context;
   }
   async _run(apiName, payload, options = {}) {
+    const apiGroup = this._apiPath;
+    return this.helpers.applyMiddlewares({
+      apiGroup,
+      apiName,
+      payload,
+      options
+    }, () => this._request(apiName, payload, options));
+  }
+
+  // one round of the request: the passes run per round, so a round run again
+  // by a middleware picks up the context as of then (e.g. a renewed token)
+  async _request(apiName, payload, options) {
     const {
       bulk
     } = options;

package/dist/cjs/api/helpers.js

@@ -6,7 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _commons = require("@miso.ai/commons");
 var _constants = require("../constants.js");
-const _excluded = ["method", "headers", "timeout"];
+const _excluded = ["method", "headers", "timeout", "retry"],
+  _excluded2 = ["method", "headers", "timeout", "body"];
 function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
 class ApiHelpers {
   constructor(client, root) {
@@ -18,18 +19,50 @@ class ApiHelpers {
     let {
         method = 'POST',
         headers,
-        timeout
+        timeout,
+        retry
       } = _ref,
       options = _objectWithoutPropertiesLoose(_ref, _excluded);
     const {
-      apiKey,
       request = {}
     } = this._client.options;
     timeout = timeout || request.timeout;
+    // retries on top of the first attempt, for failures that may be
+    // transient — network errors, timeouts, and server (5xx) errors;
+    // client (4xx) and application errors are deterministic, not retried.
+    // Off by default: a retried POST is not safe for non-idempotent calls
+    // (e.g. posting a question), so it is opted in per request via the
+    // request options, or client-wide via `options.request.retry`
+    retry = retry !== undefined ? retry : request.retry || 0;
 
     // TODO: organize arguments
     const body = method !== 'GET' && payload != undefined ? JSON.stringify(payload) : undefined;
+    for (let attempt = 0;; attempt++) {
+      try {
+        return await this._fetch(url, Object.assign({
+          method,
+          headers,
+          timeout,
+          body
+        }, options));
+      } catch (error) {
+        if (attempt >= retry || !isRetryableFetchError(error)) {
+          throw error;
+        }
+      }
+    }
+  }
 
+  // one attempt; the timeout signal is created per attempt, so a retried
+  // attempt gets a full window of its own
+  async _fetch(url, _ref2) {
+    let {
+        method,
+        headers,
+        timeout,
+        body
+      } = _ref2,
+      options = _objectWithoutPropertiesLoose(_ref2, _excluded2);
     // TODO: merge signal from options if any
     const signal = timeout ? AbortSignal.timeout(timeout) : undefined;
     const res = await (this._root._customFetch || fetch)(url, (0, _commons.trimObj)(Object.assign({
@@ -131,6 +164,27 @@ class ApiHelpers {
     } = this._client.options;
     return apiName === 'interactions' ? eventEndpoint : dataEndpoint;
   }
+
+  // middlewares wrap the whole request — passes, send, and postprocess —
+  // in registration order, the first being the outermost. Each is called
+  // with the request info and a `next` function that runs the rest of the
+  // chain, which it may defer, catch the failure of, or call again
+  async applyMiddlewares({
+    apiGroup,
+    apiName,
+    payload,
+    options
+  }, run) {
+    const client = this._client;
+    const request = Object.freeze({
+      client,
+      apiGroup,
+      apiName,
+      payload,
+      options
+    });
+    return this._root._apiMiddlewares.reduceRight((next, middleware) => () => middleware(request, next), run)();
+  }
   applyUrlPasses(component, {
     apiGroup,
     apiName,
@@ -196,4 +250,11 @@ class ApiHelpers {
     return headers;
   }
 }
-exports.default = ApiHelpers;
+
+// no status: a network failure, a timeout, or an unparsable body — all
+// transport-level; 5xx: the server's own failure. A 4xx or an
+// application-level error (2xx with `errors`) is deterministic
+exports.default = ApiHelpers;
+function isRetryableFetchError(error) {
+  return error.status === undefined || error.status >= 500;
+}

package/dist/cjs/api/history.js

@@ -14,13 +14,13 @@ class UserHistory extends _base.default {
   constructor(api) {
     super(api, GROUP.ASK_USER_HISTORY);
   }
-  async getThreads(options) {
-    return this._run('threads', undefined, Object.assign({}, options, {
+  async getThreads(payload, options) {
+    return this._run('threads', payload, Object.assign({}, options, {
       method: 'GET'
     }));
   }
-  async getThread(threadId, options) {
-    return this._run(`threads/${threadId}`, undefined, Object.assign({}, options, {
+  async getThread(threadId, payload, options) {
+    return this._run(`threads/${threadId}`, payload, Object.assign({}, options, {
       method: 'GET'
     }));
   }

package/dist/cjs/api/iterable.js

@@ -22,13 +22,7 @@ class IterableApiStub {
     this._ac.abort(reason);
   }
   [Symbol.asyncIterator]() {
-    const fetch = async ({
-      signal
-    } = {}) => {
-      // TODO: pass signal
-      const response = await this.get();
-      return [response, isFinished(response), revisionOf(response)];
-    };
+    const fetch = this._fetch();
     if (typeof this._options.customIterator === 'function') {
       return this._options.customIterator.call(this, fetch);
     }
@@ -54,7 +48,7 @@ class IterableApiStub {
     const onResponse = (response, finished) => {
       if (finished) {
         stac.clear();
-      } else if (isUpdated(prevResponse, response)) {
+      } else if (this._isUpdated(prevResponse, response)) {
         stac.touch();
       }
       prevResponse = response;
@@ -65,6 +59,27 @@ class IterableApiStub {
       onResponse
     }, options))[Symbol.asyncIterator]();
   }
+
+  /**
+   * Compose the polling fetch: () => [response, finished, revision].
+   * Overridable by a subclass with its own finish or revision semantics
+   * (e.g. Answers, whose question ids may run dry).
+   */
+  _fetch() {
+    return async ({
+      signal
+    } = {}) => {
+      // TODO: pass signal
+      const response = await this.get();
+      return [response, isFinished(response), revisionOf(response)];
+    };
+  }
+
+  // whether the new response carries progress, keeping the stall timeout at
+  // bay; overridable by a subclass with its own response shape
+  _isUpdated(previousResponse, newResponse) {
+    return isUpdated(previousResponse, newResponse);
+  }
 }
 exports.IterableApiStub = IterableApiStub;
 class IdBasedIterableApiStub extends IterableApiStub {

package/dist/cjs/classes.js

@@ -7,7 +7,8 @@ exports.default = void 0;
 var api = _interopRequireWildcard(require("./api/index.js"));
 var _context = _interopRequireDefault(require("./context.js"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 var _default = exports.default = {
   api,
   context: {

package/dist/cjs/client.js

@@ -9,7 +9,8 @@ var _root = require("./root.js");
 var _index = require("./api/index.js");
 var _context = _interopRequireDefault(require("./context.js"));
 var helpers = _interopRequireWildcard(require("./utils.js"));
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const currentScript = _commons.isInBrowser ? document.currentScript : undefined;
 class MisoClient extends _commons.Component {

package/dist/cjs/plugin/api-recovery.js

@@ -0,0 +1,123 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _commons = require("@miso.ai/commons");
+const _excluded = ["client"];
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
+const PLUGIN_ID = 'std:api-recovery';
+
+// a safety net against a callback that resends unconditionally
+const MAX_RESENT = 10;
+
+/**
+ * Lets the application intercept failed API requests, per client:
+ *
+ * ```js
+ * client.api.onError = async (error, { request, hold, resend }) => { ... };
+ * ```
+ *
+ * The request settles with the outcome of the callback: the error it throws,
+ * the value it returns (taken as the API result), or — by returning
+ * `resend()` — the outcome of sending the request again.
+ *
+ * A resent request that fails is intercepted like any other, with
+ * `error.resent` telling how many times the request has been resent so far
+ * (0 for the original failure), so the callback can give up at some count.
+ * As a safety net, a request resent 10 times fails for good, its error
+ * thrown without reaching the callback.
+ *
+ * `hold()` holds the requests issued from then on (resent ones included)
+ * until the unhold function it returns is called. Requests already in flight
+ * are not affected, so several errors may reach the callback before a hold
+ * takes effect: managing them in one go (e.g. sharing a single token renewal)
+ * is up to the application.
+ */
+class ApiRecoveryPlugin {
+  static get id() {
+    return PLUGIN_ID;
+  }
+  constructor() {
+    this._recoveries = new WeakMap();
+  }
+  install(MisoClient, context) {
+    context.addApiMiddleware(this._middleware.bind(this));
+    MisoClient.on('create', this._injectClient.bind(this));
+  }
+  _injectClient(client) {
+    const recovery = new ApiRecovery();
+    this._recoveries.set(client, recovery);
+    (0, _commons.delegateProperties)(client.api, recovery, ['onError']);
+  }
+  async _middleware(_ref, next) {
+    let {
+        client
+      } = _ref,
+      request = _objectWithoutPropertiesLoose(_ref, _excluded);
+    const recovery = this._recoveries.get(client);
+    return recovery ? recovery.run(request, next) : next();
+  }
+}
+exports.default = ApiRecoveryPlugin;
+class ApiRecovery {
+  constructor() {
+    this._callback = undefined;
+    this._holds = new Set();
+    this._gate = undefined;
+  }
+  get onError() {
+    return this._callback;
+  }
+
+  // a single callback: setting it replaces the current one, and setting it
+  // to undefined removes it
+  set onError(callback) {
+    if (callback != undefined && typeof callback !== 'function') {
+      throw new Error(`Expect onError to be a function: ${callback}`);
+    }
+    this._callback = callback || undefined;
+  }
+  async run(request, next, resent = 0) {
+    try {
+      return await this._send(next);
+    } catch (error) {
+      const callback = this._callback;
+      if (!callback || resent >= MAX_RESENT) {
+        throw error;
+      }
+      if (error && typeof error === 'object') {
+        error.resent = resent;
+      }
+      return callback(error, Object.freeze({
+        request,
+        hold: () => this._hold(),
+        resend: () => this.run(request, next, resent + 1)
+      }));
+    }
+  }
+  async _send(next) {
+    // loop: a new hold may be placed by the time the gate opens
+    while (this._gate) {
+      await this._gate.promise;
+    }
+    return next();
+  }
+  _hold() {
+    const hold = {};
+    this._holds.add(hold);
+    if (!this._gate) {
+      this._gate = new _commons.Resolution();
+    }
+    // holds overlap: the gate opens when the last one is released
+    return () => {
+      if (!this._holds.delete(hold) || this._holds.size) {
+        return;
+      }
+      const gate = this._gate;
+      this._gate = undefined;
+      gate.resolve();
+    };
+  }
+}

package/dist/cjs/plugin/index.js

@@ -15,6 +15,12 @@ Object.defineProperty(exports, "ApiPatchPlugin", {
     return _apiPatch.default;
   }
 });
+Object.defineProperty(exports, "ApiRecoveryPlugin", {
+  enumerable: true,
+  get: function () {
+    return _apiRecovery.default;
+  }
+});
 Object.defineProperty(exports, "AutoEventsPlugin", {
   enumerable: true,
   get: function () {
@@ -57,6 +63,7 @@ var _autoEvents = _interopRequireDefault(require("./auto-events.js"));
 var _interactions = _interopRequireDefault(require("./interactions.js"));
 var _nativeFetch = _interopRequireDefault(require("./native-fetch.js"));
 var _apiPatch = _interopRequireDefault(require("./api-patch.js"));
+var _apiRecovery = _interopRequireDefault(require("./api-recovery.js"));
 var _headerApiKey = _interopRequireDefault(require("./header-api-key.js"));
 var _analytics = _interopRequireDefault(require("./analytics.js"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/dist/cjs/plugin/plugin-root.js

@@ -106,6 +106,12 @@ class PluginRoot extends _commons.Registry {
     }
     this._root._urlPasses.push(pass);
   }
+  addApiMiddleware(middleware) {
+    if (typeof middleware !== 'function') {
+      throw new Error(`Expect parameter to be a function: ${middleware}`);
+    }
+    this._root._apiMiddlewares.push(middleware);
+  }
   setCustomFetch(fetch) {
     if (typeof fetch !== 'function') {
       throw new Error(`Expect parameter to be a function: ${fetch}`);
@@ -253,7 +259,7 @@ const PLUGIN_QUERY_METHODS = ['installed', 'registered', 'isInstalled', 'isRegis
  */
 class PluginContext {
   constructor(root, classes) {
-    (0, _commons.delegateGetters)(this, root, [...PLUGIN_QUERY_METHODS, 'getPluginClass', 'addSubtree', 'addExtensionPoints', 'addPayloadPass', 'addHeadersPass', 'addUrlPass', 'setCustomFetch', 'setCustomSendBeacon', 'setCustomApiIterator', 'onHubUpdate', 'onHubEmit']);
+    (0, _commons.delegateGetters)(this, root, [...PLUGIN_QUERY_METHODS, 'getPluginClass', 'addSubtree', 'addExtensionPoints', 'addPayloadPass', 'addHeadersPass', 'addUrlPass', 'addApiMiddleware', 'setCustomFetch', 'setCustomSendBeacon', 'setCustomApiIterator', 'onHubUpdate', 'onHubEmit']);
     (0, _commons.defineValues)(this, {
       classes
     });

package/dist/cjs/root.js

@@ -23,6 +23,7 @@ class Root extends _commons.Component {
     this._payloadPasses = [];
     this._headersPasses = [];
     this._urlPasses = [];
+    this._apiMiddlewares = [];
     this._customFetch = undefined;
     this._customSendBeacon = undefined;
     this._hubUpdateCallbacks = [];

package/dist/cjs/version.js

@@ -4,4 +4,4 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _default = exports.default = '1.14.0-beta.2';
+var _default = exports.default = '1.14.0-beta.4';

package/package.json

@@ -30,7 +30,7 @@
     "url": "https://github.com/MisoAI/miso-client-js-sdk/issues"
   },
   "dependencies": {
-    "@miso.ai/commons": "1.14.0-beta.2"
+    "@miso.ai/commons": "1.14.0-beta.4"
   },
-  "version": "1.14.0-beta.2"
+  "version": "1.14.0-beta.4"
 }

package/src/api/ask.js

@@ -1,7 +1,7 @@
 import { API, defineValues, trimObj } from '@miso.ai/commons';
 import ApiBase from './base.js';
 import UserHistoryV0 from './history.0.js';
-import { IdBasedIterableApiStub } from './iterable.js';
+import { IterableApiStub, IdBasedIterableApiStub } from './iterable.js';
 
 const { GROUP, NAME } = API;
 
@@ -34,13 +34,17 @@ export default class Ask extends ApiBase {
   }
 
   /**
-   * Retrieve multiple question-answer pairs at once.
+   * Retrieve multiple question-answer pairs at once: an iterable that polls
+   * the answers endpoint, like questions(). The id set is mutable between
+   * polls: `question_ids` may be a function returning the id array, resolved
+   * for every poll, and a fixed initial array settles out record by record
+   * (see Answers).
    */
   async answers(payload, options = {}) {
     if (Array.isArray(payload)) {
       payload = { question_ids: payload };
     }
-    return this._run(NAME.ANSWERS, payload, options);
+    return new Answers(this, payload, { immediate: true, ...options });
   }
 
   async relatedQuestions(payload, options = {}) {
@@ -93,6 +97,71 @@ class Answer extends IdBasedIterableApiStub {
 
 }
 
+/**
+ * The answer contents of a set of questions, polled until settled — the id
+ * set is mutable between polls, and the stream ends when it runs dry. The
+ * question ids may be given as a function returning the id array, resolved
+ * for every poll (settled ids drop out, new ones join, at the provider's
+ * discretion); a fixed initial id array is mutable all the same — its ids
+ * settle out as their records come back finished (_settle). Each fetch's
+ * issue order acts as the response revision, so a late, outdated response
+ * is discarded by the polling.
+ */
+class Answers extends IterableApiStub {
+
+  constructor(api, payload, options = {}) {
+    super(mergeCustomApiIterator(api, options));
+    this._api = api;
+    this._payload = payload;
+    const { question_ids } = payload;
+    this._pending = typeof question_ids === 'function' ? undefined : new Set(question_ids || []);
+  }
+
+  async _get(options) {
+    // a plain one-shot read of the current ids' answers
+    return this._api._run(NAME.ANSWERS, { ...this._payload, question_ids: this._questionIds() }, options);
+  }
+
+  _questionIds() {
+    return this._pending ? [...this._pending] : this._payload.question_ids();
+  }
+
+  // a fixed id set settles by the records themselves: a record that came
+  // back with its finished answer needs no further polling
+  _settle(response) {
+    if (!this._pending || !Array.isArray(response)) {
+      return;
+    }
+    for (const record of response) {
+      if (record && record.answer !== undefined && record.finished !== false) {
+        this._pending.delete(record.question_id);
+      }
+    }
+  }
+
+  _fetch() {
+    let index = 0;
+    return async ({ signal } = {}) => {
+      const i = ++index; // taken at issue time: a stale response resolves with a lower revision
+      const question_ids = this._questionIds();
+      if (!question_ids || !question_ids.length) {
+        return [undefined, true, i]; // nothing left to fetch; the stream ends
+      }
+      // TODO: use single answer endpoint when array length = 1
+      const response = await this._api._run(NAME.ANSWERS, { ...this._payload, question_ids }, { signal });
+      this._settle(response);
+      return [response, false, i];
+    };
+  }
+
+  // any response is progress for the stall timeout: the record-diff test of
+  // the base class reads a single answer's shape, not an array of records
+  _isUpdated() {
+    return true;
+  }
+
+}
+
 class SearchResult extends IdBasedIterableApiStub {
 
   constructor(api, response, options = {}) {

package/src/api/base.js

@@ -11,6 +11,13 @@ export default class ApiBase extends Component {
   }
 
   async _run(apiName, payload, options = {}) {
+    const apiGroup = this._apiPath;
+    return this.helpers.applyMiddlewares({ apiGroup, apiName, payload, options }, () => this._request(apiName, payload, options));
+  }
+
+  // one round of the request: the passes run per round, so a round run again
+  // by a middleware picks up the context as of then (e.g. a renewed token)
+  async _request(apiName, payload, options) {
     const { bulk } = options;
     const bulkInfo = bulk ? { bulk: this.helpers.bulkInfo } : undefined;
     const apiGroup = this._apiPath;

package/src/api/helpers.js

@@ -13,14 +13,36 @@ export default class ApiHelpers {
     method = 'POST',
     headers,
     timeout,
+    retry,
     ...options
   } = {}) {
-    const { apiKey, request = {} } = this._client.options;
+    const { request = {} } = this._client.options;
     timeout = timeout || request.timeout;
+    // retries on top of the first attempt, for failures that may be
+    // transient — network errors, timeouts, and server (5xx) errors;
+    // client (4xx) and application errors are deterministic, not retried.
+    // Off by default: a retried POST is not safe for non-idempotent calls
+    // (e.g. posting a question), so it is opted in per request via the
+    // request options, or client-wide via `options.request.retry`
+    retry = retry !== undefined ? retry : (request.retry || 0);
 
     // TODO: organize arguments
     const body = method !== 'GET' && payload != undefined ? JSON.stringify(payload) : undefined;
 
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await this._fetch(url, { method, headers, timeout, body, ...options });
+      } catch (error) {
+        if (attempt >= retry || !isRetryableFetchError(error)) {
+          throw error;
+        }
+      }
+    }
+  }
+
+  // one attempt; the timeout signal is created per attempt, so a retried
+  // attempt gets a full window of its own
+  async _fetch(url, { method, headers, timeout, body, ...options }) {
     // TODO: merge signal from options if any
     const signal = timeout ? AbortSignal.timeout(timeout) : undefined;
 
@@ -106,6 +128,16 @@ export default class ApiHelpers {
     return apiName === 'interactions' ? eventEndpoint : dataEndpoint;
   }
 
+  // middlewares wrap the whole request — passes, send, and postprocess —
+  // in registration order, the first being the outermost. Each is called
+  // with the request info and a `next` function that runs the rest of the
+  // chain, which it may defer, catch the failure of, or call again
+  async applyMiddlewares({ apiGroup, apiName, payload, options }, run) {
+    const client = this._client;
+    const request = Object.freeze({ client, apiGroup, apiName, payload, options });
+    return this._root._apiMiddlewares.reduceRight((next, middleware) => () => middleware(request, next), run)();
+  }
+
   applyUrlPasses(component, { apiGroup, apiName, url }) {
     const client = this._client;
     for (const pass of this._root._urlPasses) {
@@ -143,3 +175,10 @@ export default class ApiHelpers {
   }
 
 }
+
+// no status: a network failure, a timeout, or an unparsable body — all
+// transport-level; 5xx: the server's own failure. A 4xx or an
+// application-level error (2xx with `errors`) is deterministic
+function isRetryableFetchError(error) {
+  return error.status === undefined || error.status >= 500;
+}

package/src/api/history.js

@@ -9,12 +9,12 @@ export default class UserHistory extends ApiBase {
     super(api, GROUP.ASK_USER_HISTORY);
   }
 
-  async getThreads(options) {
-    return this._run('threads', undefined, { ...options, method: 'GET' });
+  async getThreads(payload, options) {
+    return this._run('threads', payload, { ...options, method: 'GET' });
   }
 
-  async getThread(threadId, options) {
-    return this._run(`threads/${threadId}`, undefined, { ...options, method: 'GET' });
+  async getThread(threadId, payload, options) {
+    return this._run(`threads/${threadId}`, payload, { ...options, method: 'GET' });
   }
 
   async updateThread(threadId, payload, options) {

package/src/api/iterable.js

@@ -20,11 +20,7 @@ export class IterableApiStub {
   }
 
   [Symbol.asyncIterator]() {
-    const fetch = async ({ signal } = {}) => {
-      // TODO: pass signal
-      const response = await this.get();
-      return [response, isFinished(response), revisionOf(response)];
-    };
+    const fetch = this._fetch();
 
     if (typeof this._options.customIterator === 'function') {
       return this._options.customIterator.call(this, fetch);
@@ -47,7 +43,7 @@ export class IterableApiStub {
     const onResponse = (response, finished) => {
       if (finished) {
         stac.clear();
-      } else if (isUpdated(prevResponse, response)) {
+      } else if (this._isUpdated(prevResponse, response)) {
         stac.touch();
       }
       prevResponse = response;
@@ -55,6 +51,25 @@ export class IterableApiStub {
     return polling(fetch, { interval, signal, onResponse, ...options })[Symbol.asyncIterator]();
   }
 
+  /**
+   * Compose the polling fetch: () => [response, finished, revision].
+   * Overridable by a subclass with its own finish or revision semantics
+   * (e.g. Answers, whose question ids may run dry).
+   */
+  _fetch() {
+    return async ({ signal } = {}) => {
+      // TODO: pass signal
+      const response = await this.get();
+      return [response, isFinished(response), revisionOf(response)];
+    };
+  }
+
+  // whether the new response carries progress, keeping the stall timeout at
+  // bay; overridable by a subclass with its own response shape
+  _isUpdated(previousResponse, newResponse) {
+    return isUpdated(previousResponse, newResponse);
+  }
+
 }
 
 export class IdBasedIterableApiStub extends IterableApiStub {

package/src/plugin/CLAUDE.md

@@ -20,6 +20,7 @@ Exposed to plugins during `install()`, provides hooks into the SDK:
 context.addPayloadPass(fn)    // Modify API request payloads
 context.addHeadersPass(fn)    // Modify request headers
 context.addUrlPass(fn)        // Modify request URLs
+context.addApiMiddleware(fn)  // Wrap API requests: defer, catch failures, resend
 context.setCustomFetch(fn)    // Override fetch implementation
 context.setCustomSendBeacon(fn) // Override sendBeacon
 context.addSubtree(component) // Register as component subtree for event propagation
@@ -77,6 +78,7 @@ export default class MyPlugin {
 | `InteractionsPlugin` | `std:interactions` | Enriches interaction records with SDK version/UUID |
 | `NativeFetchPlugin` | `std:native-fetch` | Uses native fetch, bypassing custom implementations |
 | `ApiPatchPlugin` | `std:api-patch` | Applies patches to API responses |
+| `ApiRecoveryPlugin` | `std:api-recovery` | `client.api.onError`: intercept failed requests, hold and resend |
 | `HeaderApiKeyPlugin` | `std:header-api-key` | Sends API key in header instead of query |
 | `AnalyticsPlugin` | `std:analytics` | User engagement timing and analytics |
 
@@ -98,6 +100,22 @@ function modifyHeaders({ client, headers }) {
 }
 ```
 
+## API Middlewares
+
+A middleware wraps a whole API request (passes, send, postprocess). It may defer the request, catch its failure, or run it again — each round re-applies the passes, so it picks up the context as of then:
+
+```javascript
+// request: { client, apiGroup, apiName, payload, options }
+async function middleware(request, next) {
+  try {
+    return await next();
+  } catch (error) {
+    // ...
+    return next();
+  }
+}
+```
+
 ## Lifecycle
 
 1. `register()` - Plugin class stored by ID

package/src/plugin/api-recovery.js

@@ -0,0 +1,124 @@
+import { Resolution, delegateProperties } from '@miso.ai/commons';
+
+const PLUGIN_ID = 'std:api-recovery';
+
+// a safety net against a callback that resends unconditionally
+const MAX_RESENT = 10;
+
+/**
+ * Lets the application intercept failed API requests, per client:
+ *
+ * ```js
+ * client.api.onError = async (error, { request, hold, resend }) => { ... };
+ * ```
+ *
+ * The request settles with the outcome of the callback: the error it throws,
+ * the value it returns (taken as the API result), or — by returning
+ * `resend()` — the outcome of sending the request again.
+ *
+ * A resent request that fails is intercepted like any other, with
+ * `error.resent` telling how many times the request has been resent so far
+ * (0 for the original failure), so the callback can give up at some count.
+ * As a safety net, a request resent 10 times fails for good, its error
+ * thrown without reaching the callback.
+ *
+ * `hold()` holds the requests issued from then on (resent ones included)
+ * until the unhold function it returns is called. Requests already in flight
+ * are not affected, so several errors may reach the callback before a hold
+ * takes effect: managing them in one go (e.g. sharing a single token renewal)
+ * is up to the application.
+ */
+export default class ApiRecoveryPlugin {
+
+  static get id() {
+    return PLUGIN_ID;
+  }
+
+  constructor() {
+    this._recoveries = new WeakMap();
+  }
+
+  install(MisoClient, context) {
+    context.addApiMiddleware(this._middleware.bind(this));
+    MisoClient.on('create', this._injectClient.bind(this));
+  }
+
+  _injectClient(client) {
+    const recovery = new ApiRecovery();
+    this._recoveries.set(client, recovery);
+    delegateProperties(client.api, recovery, ['onError']);
+  }
+
+  async _middleware({ client, ...request }, next) {
+    const recovery = this._recoveries.get(client);
+    return recovery ? recovery.run(request, next) : next();
+  }
+
+}
+
+class ApiRecovery {
+
+  constructor() {
+    this._callback = undefined;
+    this._holds = new Set();
+    this._gate = undefined;
+  }
+
+  get onError() {
+    return this._callback;
+  }
+
+  // a single callback: setting it replaces the current one, and setting it
+  // to undefined removes it
+  set onError(callback) {
+    if (callback != undefined && typeof callback !== 'function') {
+      throw new Error(`Expect onError to be a function: ${callback}`);
+    }
+    this._callback = callback || undefined;
+  }
+
+  async run(request, next, resent = 0) {
+    try {
+      return await this._send(next);
+    } catch (error) {
+      const callback = this._callback;
+      if (!callback || resent >= MAX_RESENT) {
+        throw error;
+      }
+      if (error && typeof error === 'object') {
+        error.resent = resent;
+      }
+      return callback(error, Object.freeze({
+        request,
+        hold: () => this._hold(),
+        resend: () => this.run(request, next, resent + 1),
+      }));
+    }
+  }
+
+  async _send(next) {
+    // loop: a new hold may be placed by the time the gate opens
+    while (this._gate) {
+      await this._gate.promise;
+    }
+    return next();
+  }
+
+  _hold() {
+    const hold = {};
+    this._holds.add(hold);
+    if (!this._gate) {
+      this._gate = new Resolution();
+    }
+    // holds overlap: the gate opens when the last one is released
+    return () => {
+      if (!this._holds.delete(hold) || this._holds.size) {
+        return;
+      }
+      const gate = this._gate;
+      this._gate = undefined;
+      gate.resolve();
+    };
+  }
+
+}

package/src/plugin/index.js

@@ -4,5 +4,6 @@ export { default as AutoEventsPlugin } from './auto-events.js';
 export { default as InteractionsPlugin } from './interactions.js';
 export { default as NativeFetchPlugin } from './native-fetch.js';
 export { default as ApiPatchPlugin } from './api-patch.js';
+export { default as ApiRecoveryPlugin } from './api-recovery.js';
 export { default as HeaderApiKeyPlugin } from './header-api-key.js';
 export { default as AnalyticsPlugin } from './analytics.js';

package/src/plugin/plugin-root.js

@@ -111,6 +111,13 @@ export default class PluginRoot extends Registry {
     this._root._urlPasses.push(pass);
   }
 
+  addApiMiddleware(middleware) {
+    if (typeof middleware !== 'function') {
+      throw new Error(`Expect parameter to be a function: ${middleware}`);
+    }
+    this._root._apiMiddlewares.push(middleware);
+  }
+
   setCustomFetch(fetch) {
     if (typeof fetch !== 'function') {
       throw new Error(`Expect parameter to be a function: ${fetch}`);
@@ -276,6 +283,7 @@ class PluginContext {
       'addPayloadPass',
       'addHeadersPass',
       'addUrlPass',
+      'addApiMiddleware',
       'setCustomFetch',
       'setCustomSendBeacon',
       'setCustomApiIterator',

package/src/root.js

@@ -15,6 +15,7 @@ class Root extends Component {
     this._payloadPasses = [];
     this._headersPasses = [];
     this._urlPasses = [];
+    this._apiMiddlewares = [];
     this._customFetch = undefined;
     this._customSendBeacon = undefined;
     this._hubUpdateCallbacks = [];

package/src/version.js

@@ -1 +1 @@
-export default '1.14.0-beta.2';
+export default '1.14.0-beta.4';