@rimori/client 2.3.0-next.6 → 2.3.0-next.8

package/README.md

@@ -155,7 +155,7 @@ Use `client.runtime.fetchBackend` for authenticated calls to Rimori-managed HTTP
 - `on(topic, handler)` / `once(topic, handler)` / `respond(topic, handler)` – subscribe and reply (each call returns an object with `off()` for cleanup).
 - `emitAccomplishment(payload)` / `onAccomplishment(topic, handler)` – report learning milestones.
 - `emitSidebarAction(pluginId, actionKey, text?)` – trigger sidebar plugins.
-- `onMainPanelAction(handler, actionsToListen?)` – react to dashboard actions.
+- `onMainPanelAction(handler, actionsToListen?)` – react to dashboard actions. Returns an `EventListener` with an `off()` method. **Important:** Call `listener.off()` when your component unmounts or when you no longer need to listen, especially to prevent the event from firing again when navigating away from or returning to the page.
 - `client.navigation.toDashboard()` – navigate the user back to Rimori.
 
 ### Community Content

package/dist/plugin/RimoriClient.d.ts

@@ -5,7 +5,7 @@ import { ObjectRequest } from '../controller/ObjectController';
 import { UserInfo } from '../controller/SettingsController';
 import { SharedContent, SharedContentFilter, SharedContentObjectRequest } from '../controller/SharedContentController';
 import { CreateExerciseParams } from '../controller/ExerciseController';
-import { EventBusMessage, EventHandler, EventPayload } from '../fromRimori/EventBus';
+import { EventBusMessage, EventHandler, EventPayload, EventListener } from '../fromRimori/EventBus';
 import { ActivePlugin, MainPanelAction, Plugin, Tool } from '../fromRimori/PluginTypes';
 import { AccomplishmentPayload } from '../controller/AccomplishmentController';
 import { Translator } from '../controller/TranslationController';
@@ -112,7 +112,7 @@ export declare class RimoriClient {
          * @param callback The callback to call when the event is emitted.
          * @returns An EventListener object containing an off() method to unsubscribe the listeners.
          */
-        on: <T = EventPayload>(topic: string | string[], callback: EventHandler<T>) => import("../fromRimori/EventBus").EventListener;
+        on: <T = EventPayload>(topic: string | string[], callback: EventHandler<T>) => EventListener;
         /**
          * Subscribe to an event once.
          * @param topic The topic to subscribe to.
@@ -143,8 +143,31 @@ export declare class RimoriClient {
          * @param text Optional text to be used for the action like for example text that the translator would look up.
          */
         emitSidebarAction: (pluginId: string, actionKey: string, text?: string) => void;
-        onMainPanelAction: (callback: (data: MainPanelAction) => void, actionsToListen?: string | string[]) => void;
-        onSidePanelAction: (callback: (data: MainPanelAction) => void, actionsToListen?: string | string[]) => void;
+        /**
+         * Subscribe to main panel actions triggered by the user from the dashboard.
+         * @param callback Handler function that receives the action data when a matching action is triggered.
+         * @param actionsToListen Optional filter to listen only to specific action keys. If empty or not provided, all actions will trigger the callback.
+         * @returns An EventListener object with an `off()` method for cleanup.
+         *
+         * @example
+         * ```ts
+         * const listener = client.event.onMainPanelAction((data) => {
+         *   console.log('Action received:', data.action_key);
+         * }, ['startSession', 'pauseSession']);
+         *
+         * // Clean up when component unmounts to prevent events from firing
+         * // when navigating away or returning to the page
+         * useEffect(() => {
+         *   return () => listener.off();
+         * }, []);
+         * ```
+         *
+         * **Important:** Always call `listener.off()` when your component unmounts or when you no longer need to listen.
+         * This prevents the event handler from firing when navigating away from or returning to the page, which could
+         * cause unexpected behavior or duplicate event handling.
+         */
+        onMainPanelAction: (callback: (data: MainPanelAction) => void, actionsToListen?: string | string[]) => EventListener;
+        onSidePanelAction: (callback: (data: MainPanelAction) => void, actionsToListen?: string | string[]) => EventListener;
     };
     navigation: {
         toDashboard: () => void;

package/dist/plugin/RimoriClient.js

@@ -96,11 +96,34 @@ export class RimoriClient {
             emitSidebarAction: (pluginId, actionKey, text) => {
                 this.event.emit('global.sidebar.triggerAction', { plugin_id: pluginId, action_key: actionKey, text });
             },
+            /**
+             * Subscribe to main panel actions triggered by the user from the dashboard.
+             * @param callback Handler function that receives the action data when a matching action is triggered.
+             * @param actionsToListen Optional filter to listen only to specific action keys. If empty or not provided, all actions will trigger the callback.
+             * @returns An EventListener object with an `off()` method for cleanup.
+             *
+             * @example
+             * ```ts
+             * const listener = client.event.onMainPanelAction((data) => {
+             *   console.log('Action received:', data.action_key);
+             * }, ['startSession', 'pauseSession']);
+             *
+             * // Clean up when component unmounts to prevent events from firing
+             * // when navigating away or returning to the page
+             * useEffect(() => {
+             *   return () => listener.off();
+             * }, []);
+             * ```
+             *
+             * **Important:** Always call `listener.off()` when your component unmounts or when you no longer need to listen.
+             * This prevents the event handler from firing when navigating away from or returning to the page, which could
+             * cause unexpected behavior or duplicate event handling.
+             */
             onMainPanelAction: (callback, actionsToListen = []) => {
                 const listeningActions = Array.isArray(actionsToListen) ? actionsToListen : [actionsToListen];
                 // this needs to be a emit and on because the main panel action is triggered by the user and not by the plugin
                 this.event.emit('action.requestMain');
-                this.event.on('action.requestMain', ({ data }) => {
+                return this.event.on('action.requestMain', ({ data }) => {
                     // console.log('Received action for main panel ' + data.action_key);
                     // console.log('Listening to actions', listeningActions);
                     if (listeningActions.length === 0 || listeningActions.includes(data.action_key)) {
@@ -112,7 +135,7 @@ export class RimoriClient {
                 const listeningActions = Array.isArray(actionsToListen) ? actionsToListen : [actionsToListen];
                 // this needs to be a emit and on because the main panel action is triggered by the user and not by the plugin
                 this.event.emit('action.requestSidebar');
-                this.event.on('action.requestSidebar', ({ data }) => {
+                return this.event.on('action.requestSidebar', ({ data }) => {
                     // console.log("eventHandler .onSidePanelAction", data);
                     // console.log('Received action for sidebar ' + data.action);
                     // console.log('Listening to actions', listeningActions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimori/client",
-  "version": "2.3.0-next.6",
+  "version": "2.3.0-next.8",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {

package/src/plugin/RimoriClient.ts

@@ -12,7 +12,7 @@ import {
 } from '../controller/SharedContentController';
 import { getSTTResponse, getTTSResponse } from '../controller/VoiceController';
 import { ExerciseController, CreateExerciseParams } from '../controller/ExerciseController';
-import { EventBus, EventBusMessage, EventHandler, EventPayload } from '../fromRimori/EventBus';
+import { EventBus, EventBusMessage, EventHandler, EventPayload, EventListener } from '../fromRimori/EventBus';
 import { ActivePlugin, MainPanelAction, Plugin, Tool } from '../fromRimori/PluginTypes';
 import { AccomplishmentController, AccomplishmentPayload } from '../controller/AccomplishmentController';
 import { RimoriCommunicationHandler, RimoriInfo } from './CommunicationHandler';
@@ -201,7 +201,7 @@ export class RimoriClient {
      * @param callback The callback to call when the event is emitted.
      * @returns An EventListener object containing an off() method to unsubscribe the listeners.
      */
-    on: <T = EventPayload>(topic: string | string[], callback: EventHandler<T>) => {
+    on: <T = EventPayload>(topic: string | string[], callback: EventHandler<T>): EventListener => {
       const topics = Array.isArray(topic) ? topic : [topic];
       return EventBus.on<T>(
         topics.map((t) => this.pluginController.getGlobalEventTopic(t)),
@@ -260,11 +260,37 @@ export class RimoriClient {
       this.event.emit('global.sidebar.triggerAction', { plugin_id: pluginId, action_key: actionKey, text });
     },
 
-    onMainPanelAction: (callback: (data: MainPanelAction) => void, actionsToListen: string | string[] = []) => {
+    /**
+     * Subscribe to main panel actions triggered by the user from the dashboard.
+     * @param callback Handler function that receives the action data when a matching action is triggered.
+     * @param actionsToListen Optional filter to listen only to specific action keys. If empty or not provided, all actions will trigger the callback.
+     * @returns An EventListener object with an `off()` method for cleanup.
+     *
+     * @example
+     * ```ts
+     * const listener = client.event.onMainPanelAction((data) => {
+     *   console.log('Action received:', data.action_key);
+     * }, ['startSession', 'pauseSession']);
+     *
+     * // Clean up when component unmounts to prevent events from firing
+     * // when navigating away or returning to the page
+     * useEffect(() => {
+     *   return () => listener.off();
+     * }, []);
+     * ```
+     *
+     * **Important:** Always call `listener.off()` when your component unmounts or when you no longer need to listen.
+     * This prevents the event handler from firing when navigating away from or returning to the page, which could
+     * cause unexpected behavior or duplicate event handling.
+     */
+    onMainPanelAction: (
+      callback: (data: MainPanelAction) => void,
+      actionsToListen: string | string[] = [],
+    ): EventListener => {
       const listeningActions = Array.isArray(actionsToListen) ? actionsToListen : [actionsToListen];
       // this needs to be a emit and on because the main panel action is triggered by the user and not by the plugin
       this.event.emit('action.requestMain');
-      this.event.on<MainPanelAction>('action.requestMain', ({ data }) => {
+      return this.event.on<MainPanelAction>('action.requestMain', ({ data }) => {
         // console.log('Received action for main panel ' + data.action_key);
         // console.log('Listening to actions', listeningActions);
         if (listeningActions.length === 0 || listeningActions.includes(data.action_key)) {
@@ -273,11 +299,14 @@ export class RimoriClient {
       });
     },
 
-    onSidePanelAction: (callback: (data: MainPanelAction) => void, actionsToListen: string | string[] = []) => {
+    onSidePanelAction: (
+      callback: (data: MainPanelAction) => void,
+      actionsToListen: string | string[] = [],
+    ): EventListener => {
       const listeningActions = Array.isArray(actionsToListen) ? actionsToListen : [actionsToListen];
       // this needs to be a emit and on because the main panel action is triggered by the user and not by the plugin
       this.event.emit('action.requestSidebar');
-      this.event.on<MainPanelAction>('action.requestSidebar', ({ data }) => {
+      return this.event.on<MainPanelAction>('action.requestSidebar', ({ data }) => {
         // console.log("eventHandler .onSidePanelAction", data);
         // console.log('Received action for sidebar ' + data.action);
         // console.log('Listening to actions', listeningActions);