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

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

@@ -164,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,

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

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

@@ -128,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) {

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.3';
+export default '1.14.0-beta.4';