@miso.ai/client-sdk-core 1.13.0-beta.1 → 1.13.0-beta.2

package/dist/cjs/plugin/analytics.js

@@ -0,0 +1,161 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _commons = require("@miso.ai/commons");
+function _objectDestructuringEmpty(t) { if (null == t) throw new TypeError("Cannot destructure " + t); }
+const PLUGIN_ID = 'std:analytics';
+class AnalyticsPlugin extends _commons.Component {
+  static get id() {
+    return PLUGIN_ID;
+  }
+  constructor() {
+    super('analytics');
+    this._members = [];
+    this._engagement = undefined;
+  }
+  config(options = {}) {
+    this._options = options;
+    for (const member of this._members) {
+      // notify update
+      // TODO: merge with global options
+      //member.config(options);
+    }
+  }
+  install(MisoClient, context) {
+    context.addSubtree(this);
+    this._engagement = new _commons.UserEngagementObserver(this._handleEngagement.bind(this));
+    // TODO: should we provide a way to stop the observer? 
+    MisoClient.on('create', this._injectClient.bind(this));
+  }
+  _injectClient(client) {
+    client.on('workflow', this._injectWorkflow.bind(this));
+  }
+  _injectWorkflow(workflow) {
+    workflow.analytics = new Analytics(this, workflow);
+  }
+  _handleEngagement() {
+    for (const member of this._members) {
+      member._syncEngagementState();
+    }
+  }
+}
+exports.default = AnalyticsPlugin;
+function normalizeOptions(_ref = {}) {
+  let options = Object.assign({}, (_objectDestructuringEmpty(_ref), _ref));
+  return Object.assign({}, options);
+}
+function mergeTwoOptions(base, overrides) {
+  return Object.assign({}, base, overrides);
+}
+class Analytics {
+  constructor(plugin, workflow) {
+    this._plugin = plugin;
+    plugin._members.push(this);
+    this._workflow = workflow;
+    this._timer = new _commons.Stopwatch();
+    this._options = normalizeOptions();
+    this._injectWorkflow(workflow);
+    this._session = undefined;
+    this._startAt = undefined;
+    this._loadingAt = undefined;
+    this._readyAt = undefined;
+    this.config();
+  }
+  _injectWorkflow(workflow) {
+    this._listenToLiftcycleEvents(workflow);
+    this._injectProcessInteraction(workflow);
+  }
+  _listenToLiftcycleEvents(workflow) {
+    workflow.on('session', this._handleSession.bind(this));
+    workflow.on('loading', this._handleLoading.bind(this));
+    workflow.on('ready', this._handleReady.bind(this));
+  }
+  _injectProcessInteraction(workflow) {
+    // TODO: ad-hoc, find a way to provide plugin API in plugin root
+    workflow._pluginContext.processInteractionPasses.push(this._writeStateToInteraction.bind(this));
+  }
+  _handleSession(session) {
+    if (this._session && session.index === this._session.index) {
+      return;
+    }
+    if (this._session) {
+      // send a last heartbeat event for the old session
+      this._sendHeartbeat();
+    }
+    this._session = session;
+    this._timer.reset();
+    this._startAt = Date.now();
+    this._loadingAt = undefined;
+    this._readyAt = undefined;
+  }
+  _handleLoading({
+    session
+  } = {}) {
+    this._loadingAt = Date.now();
+  }
+  _handleReady({
+    session
+  } = {}) {
+    this._readyAt = Date.now();
+    // start timer if user is engaged
+    this._syncEngagementState();
+  }
+  _sendHeartbeat() {
+    const tracker = this._workflow.trackers.container;
+    tracker && tracker.heartbeat();
+  }
+  _writeStateToInteraction(payload) {
+    const {
+      state
+    } = this;
+    return (0, _commons.mergeInteractions)(payload, {
+      context: {
+        custom_context: {
+          analytics_timestamp: state.timestamp,
+          user_engagement_time: state.userEngagementTime,
+          user_idle_time: state.userIdleTime,
+          user_waiting_time: state.userWaitingTime
+        }
+      }
+    });
+  }
+  config(options = {}) {
+    this._options = mergeTwoOptions(this._options, normalizeOptions(options));
+  }
+  get options() {
+    return Object.assign({}, this._options);
+  }
+  get state() {
+    const currentTime = Date.now();
+    const loadingAt = this._loadingAt;
+    const readyAt = this._readyAt;
+    let userEngagementTime = 0,
+      userIdleTime = 0,
+      userWaitingTime = 0;
+    if (loadingAt !== undefined) {
+      userWaitingTime = currentTime - loadingAt;
+    }
+    if (readyAt !== undefined) {
+      userWaitingTime = readyAt - loadingAt;
+      userEngagementTime = this._timer.getDuration(currentTime);
+      userIdleTime = currentTime - readyAt - userEngagementTime;
+    }
+    return (0, _commons.trimObj)({
+      timestamp: currentTime,
+      userWaitingTime,
+      userEngagementTime,
+      userIdleTime
+    });
+  }
+  _syncEngagementState() {
+    const shallStart = this._plugin._engagement.engaged;
+    if (shallStart) {
+      this._timer.start();
+    } else {
+      this._timer.stop();
+    }
+  }
+}

package/dist/cjs/plugin/index.js

@@ -3,6 +3,12 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "AnalyticsPlugin", {
+  enumerable: true,
+  get: function () {
+    return _analytics.default;
+  }
+});
 Object.defineProperty(exports, "ApiPatchPlugin", {
   enumerable: true,
   get: function () {
@@ -52,4 +58,5 @@ var _interactions = _interopRequireDefault(require("./interactions.js"));
 var _nativeFetch = _interopRequireDefault(require("./native-fetch.js"));
 var _apiPatch = _interopRequireDefault(require("./api-patch.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/version.js

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

package/package.json

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

package/src/plugin/CLAUDE.md

@@ -0,0 +1,106 @@
+# Plugin System
+
+This directory contains the core plugin infrastructure and standard plugins for the Miso Client SDK.
+
+## Architecture
+
+### PluginRoot (`plugin-root.js`)
+
+The central registry that manages plugin lifecycle:
+
+- **Registration**: `register(PluginClass)` - Makes a plugin available by its ID
+- **Activation**: `use(id, options)` - Instantiates and installs a registered plugin
+- **Installation**: `install(id, options)` - Combines register + use, supports remote loading for `std:*` plugins
+
+### PluginContext
+
+Exposed to plugins during `install()`, provides hooks into the SDK:
+
+```javascript
+context.addPayloadPass(fn)    // Modify API request payloads
+context.addHeadersPass(fn)    // Modify request headers
+context.addUrlPass(fn)        // Modify request URLs
+context.setCustomFetch(fn)    // Override fetch implementation
+context.setCustomSendBeacon(fn) // Override sendBeacon
+context.addSubtree(component) // Register as component subtree for event propagation
+context.onHubUpdate(fn)       // Listen to hub state updates
+context.onHubEmit(fn)         // Listen to hub emissions
+context.whenInstalled(id)     // Wait for another plugin
+context.classes               // Access to SDK classes
+```
+
+## Creating a Plugin
+
+### Basic Structure
+
+```javascript
+const PLUGIN_ID = 'std:my-plugin';
+
+export default class MyPlugin {
+  static get id() {
+    return PLUGIN_ID;
+  }
+
+  // Optional: extend Component for event support
+  // constructor() { super('my-plugin'); }
+
+  install(MisoClient, context) {
+    // Setup logic here
+    MisoClient.on('create', this._injectClient.bind(this));
+  }
+
+  // Optional: allow runtime configuration
+  config(options) {
+    this._options = options;
+  }
+
+  _injectClient(client) {
+    // Extend client instances
+    client.myFeature = new MyFeature(this, client);
+  }
+}
+```
+
+### Plugin Patterns
+
+1. **Payload Modifier** (e.g., `context.js`, `interactions.js`): Intercept and modify API payloads
+2. **Client Injector**: Add properties/methods to each MisoClient instance
+3. **Component-based** (extend `Component`): For plugins needing event emission and subtree registration
+
+## Standard Plugins
+
+| Plugin | ID | Purpose |
+|--------|-----|---------|
+| `ContextPlugin` | `std:context` | User identity (anonymous_id, user_id, site) |
+| `PageInfoPlugin` | `std:page-info` | Adds page metadata to requests |
+| `AutoEventsPlugin` | `std:auto-events` | Automatic interaction tracking |
+| `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 |
+| `HeaderApiKeyPlugin` | `std:header-api-key` | Sends API key in header instead of query |
+| `AnalyticsPlugin` | `std:analytics` | User engagement timing and analytics |
+
+## Pass Functions
+
+Pass functions receive a context object and return modified values:
+
+```javascript
+// Payload pass signature
+function modifyPayload({ client, apiGroup, apiName, payload }) {
+  // apiGroup: 'search', 'ask', 'interactions', etc.
+  // apiName: 'search', 'upload', 'questions', etc.
+  return modifiedPayload;
+}
+
+// Headers pass signature
+function modifyHeaders({ client, headers }) {
+  return { ...headers, 'X-Custom': 'value' };
+}
+```
+
+## Lifecycle
+
+1. `register()` - Plugin class stored by ID
+2. `use()` - Plugin instantiated, `config()` called if options provided
+3. `install()` - Plugin's `install(MisoClient, context)` called
+4. `MisoClient.on('create')` - Hook to extend new client instances

package/src/plugin/analytics.js

@@ -0,0 +1,185 @@
+import { Component, UserEngagementObserver, Stopwatch, trimObj, mergeInteractions } from '@miso.ai/commons';
+
+const PLUGIN_ID = 'std:analytics';
+
+export default class AnalyticsPlugin extends Component {
+
+  static get id() {
+    return PLUGIN_ID;
+  }
+
+  constructor() {
+    super('analytics');
+    this._members = [];
+    this._engagement = undefined;
+  }
+
+  config(options = {}) {
+    this._options = options;
+    for (const member of this._members) {
+      // notify update
+      // TODO: merge with global options
+      //member.config(options);
+    }
+  }
+
+  install(MisoClient, context) {
+    context.addSubtree(this);
+    this._engagement = new UserEngagementObserver(this._handleEngagement.bind(this));
+    // TODO: should we provide a way to stop the observer? 
+    MisoClient.on('create', this._injectClient.bind(this));
+  }
+
+  _injectClient(client) {
+    client.on('workflow', this._injectWorkflow.bind(this));
+  }
+
+  _injectWorkflow(workflow) {
+    workflow.analytics = new Analytics(this, workflow);
+  }
+
+  _handleEngagement() {
+    for (const member of this._members) {
+      member._syncEngagementState();
+    }
+  }
+
+}
+
+function normalizeOptions({ ...options } = {}) {
+  return {
+    ...options,
+  };
+}
+
+function mergeTwoOptions(base, overrides) {
+  return {
+    ...base,
+    ...overrides,
+  };
+}
+
+class Analytics {
+
+  constructor(plugin, workflow) {
+    this._plugin = plugin;
+    plugin._members.push(this);
+    this._workflow = workflow;
+    this._timer = new Stopwatch();
+    this._options = normalizeOptions();
+
+    this._injectWorkflow(workflow);
+
+    this._session = undefined;
+    this._startAt = undefined;
+    this._loadingAt = undefined;
+    this._readyAt = undefined;
+
+    this.config();
+  }
+
+  _injectWorkflow(workflow) {
+    this._listenToLiftcycleEvents(workflow);
+    this._injectProcessInteraction(workflow);
+  }
+
+  _listenToLiftcycleEvents(workflow) {
+    workflow.on('session', this._handleSession.bind(this));
+    workflow.on('loading', this._handleLoading.bind(this));
+    workflow.on('ready', this._handleReady.bind(this));
+  }
+
+  _injectProcessInteraction(workflow) {
+    // TODO: ad-hoc, find a way to provide plugin API in plugin root
+    workflow._pluginContext.processInteractionPasses.push(this._writeStateToInteraction.bind(this));
+  }
+
+  _handleSession(session) {
+    if (this._session && session.index === this._session.index) {
+      return;
+    }
+
+    if (this._session) {
+      // send a last heartbeat event for the old session
+      this._sendHeartbeat();
+    }
+
+    this._session = session;
+    this._timer.reset();
+    this._startAt = Date.now();
+    this._loadingAt = undefined;
+    this._readyAt = undefined;
+  }
+
+  _handleLoading({ session } = {}) {
+    this._loadingAt = Date.now();
+  }
+
+  _handleReady({ session } = {}) {
+    this._readyAt = Date.now();
+    // start timer if user is engaged
+    this._syncEngagementState();
+  }
+
+  _sendHeartbeat() {
+    const tracker = this._workflow.trackers.container;
+    tracker && tracker.heartbeat();
+  }
+
+  _writeStateToInteraction(payload) {
+    const { state } = this;
+    return mergeInteractions(payload, {
+      context: {
+        custom_context: {
+          analytics_timestamp: state.timestamp,
+          user_engagement_time: state.userEngagementTime,
+          user_idle_time: state.userIdleTime,
+          user_waiting_time: state.userWaitingTime,
+        },
+      },
+    });
+  }
+
+  config(options = {}) {
+    this._options = mergeTwoOptions(this._options, normalizeOptions(options));
+  }
+
+  get options() {
+    return {
+      ...this._options,
+    };
+  }
+
+  get state() {
+    const currentTime = Date.now();
+    const loadingAt = this._loadingAt;
+    const readyAt = this._readyAt;
+    let userEngagementTime = 0, userIdleTime = 0, userWaitingTime = 0;
+
+    if (loadingAt !== undefined) {
+      userWaitingTime = currentTime - loadingAt;
+    }
+    if (readyAt !== undefined) {
+      userWaitingTime = readyAt - loadingAt;
+      userEngagementTime = this._timer.getDuration(currentTime);
+      userIdleTime = currentTime - readyAt - userEngagementTime;
+    }
+
+    return trimObj({
+      timestamp: currentTime,
+      userWaitingTime,
+      userEngagementTime,
+      userIdleTime,
+    });
+  }
+
+  _syncEngagementState() {
+    const shallStart = this._plugin._engagement.engaged;
+    if (shallStart) {
+      this._timer.start();
+    } else {
+      this._timer.stop();
+    }
+  }
+
+}

package/src/plugin/index.js

@@ -5,3 +5,4 @@ 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 HeaderApiKeyPlugin } from './header-api-key.js';
+export { default as AnalyticsPlugin } from './analytics.js';

package/src/version.js

@@ -1 +1 @@
-export default '1.13.0-beta.1';
+export default '1.13.0-beta.2';