@miso.ai/client-sdk-core 1.14.0-beta.1 → 1.14.0-beta.3

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/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({
@@ -196,4 +229,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/version.js

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

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.1"
+    "@miso.ai/commons": "1.14.0-beta.3"
   },
-  "version": "1.14.0-beta.1"
+  "version": "1.14.0-beta.3"
 }

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/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;
 
@@ -143,3 +165,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/version.js

@@ -1 +1 @@
-export default '1.14.0-beta.1';
+export default '1.14.0-beta.3';