@knime/hub-features 1.23.0 → 1.24.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @knime/hub-features
 
+## 1.24.1
+
+### Patch Changes
+
+- Updated dependencies [6a0afa2]
+  - @knime/components@1.46.0
+
+## 1.24.0
+
+### Minor Changes
+
+- 9bc7a76: Add authUtils package
+- 182d2d7: Added analyticEvents package. See README for usage and feature overview
+  Changed embeddingSDK analytics property on the embedding context.
+
+### Patch Changes
+
+- Updated dependencies [c4e0bfd]
+  - @knime/components@1.45.10
+
 ## 1.23.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knime/hub-features",
-  "version": "1.23.0",
+  "version": "1.24.1",
   "description": "Vue components & composables for shared hub features",
   "repository": {
     "type": "git",
@@ -26,6 +26,9 @@
     },
     "./versions": {
       "import": "./src/components/versions/index.ts"
+    },
+    "./analytics": {
+      "import": "./src/analytics/index.ts"
     }
   },
   "dependencies": {
@@ -36,7 +39,7 @@
     "lodash-es": "4.17.23",
     "ofetch": "^1.4.1",
     "typescript": "^5.9.3",
-    "@knime/components": "1.45.9",
+    "@knime/components": "1.46.0",
     "@knime/styles": "1.15.0",
     "@knime/utils": "1.10.1"
   },
@@ -48,6 +51,7 @@
     "@vitejs/plugin-vue": "^6.0.1",
     "@vue/test-utils": "2.4.6",
     "consola": "3.4.2",
+    "json-schema-to-typescript": "^15.0.4",
     "vite": "^7.3.1",
     "vite-svg-loader": "5.1.0",
     "vue-tsc": "3.0.4"
@@ -57,6 +61,7 @@
   },
   "scripts": {
     "type-check": "vue-tsc --noEmit -p tsconfig.vitest.json --composite false",
-    "test:unit": "TZ='Europe/Berlin' vitest"
+    "test:unit": "TZ='Europe/Berlin' vitest",
+    "generate-analytics-events": "json2ts ./src/analyticsEvents/schema/schema.json > ./src/analyticsEvents/schema/schema.d.ts"
   }
 }

package/src/analytics/README.md

@@ -0,0 +1,87 @@
+# @knime/hub-features — analyticsEvents
+
+## Preface
+
+This package provides helpers related to analytics events. It provides 2 main behaviors:
+
+- Provides a builder function that creates and normalizes event payloads
+- Provides a sender function that forwards a given event payload to a third party API.
+  The implementation of the third-party API is up to the consumer as long as it satisfies the adapter contract
+
+The main reason why these behaviors are split are for increased flexibility and to also enable this feature being used on a setup where the creation of the event is separated to the sending of the event. Like for example, on host/guest application combination where there's an iframe communication layer between both apps.
+
+## Usage examples
+
+### Building event payloads
+
+As stated above, some applications might only care (or have the correct setup) to construct events based on different code paths and user interactions.
+
+```ts
+import { analyticsEvents } from "@knime/hub-features/analytics";
+
+// Create a small factory bound to your context
+const { newEvent } = analyticsEvents.eventBuilder({ jobId: "job-123" });
+
+// Build an event. Event ids are strongly-typed, combining their special format
+// and validating payloads, if required
+const event = newEvent({ id: "kai_prompted::kaiqa_button_prompt" });
+
+// once you have this event object, the application can decide what to do with it.
+// Whether that is sending it through an iframe as a message or some other event bus. OR sending it directly if it's so desired (see Sending events section)
+```
+
+### Keeping types in-sync
+
+Due to the strict-type setup and the shape of the API of this package, reusing the type signature
+of the function that creates the events can be tricky. However, this is helpful, for example, if you want to
+wrap the create function with some other behavior of your own but keep the strong-type guarantees.
+Below you can see an example for this use-case:
+
+```ts
+import {
+  analyticsEvents,
+  type CreateEventFn,
+} from "@knime/hub-features/analytics";
+
+const myCustomFunction: CreateEventFn = (...args) => {
+  const { newEvent } = analyticsEvents.eventBuilder(TheNeededContext);
+
+  // do something before
+
+  const event = newEvent(...args);
+
+  // do something with event
+};
+```
+
+In this case, the type signature of `myCustomFunction` will match the one of `newEvent`, just like
+in the previous example.
+
+### Sending events
+
+As stated in the preface, to send events, you need to provide an adapter
+
+```ts
+import {
+  analyticsEvents,
+  type AnalyticsAdapter,
+} from "@knime/hub-features/analytics";
+
+const myAdapter: AnalyticsAdapter = {
+  sendEvent({ event, metadata, idParser }) {
+    console.log("Parsed id", idParser(event.id));
+    console.log("Metadata", metadata);
+    console.log("Event", event)
+  }
+}
+
+// create the sender
+const sender = analyticsEvents.eventSender(myAdapter);
+
+// some event
+const { newEvent } = analyticsEvents.eventBuilder(TheNeededContext);
+const event = newEvent(...);
+
+// then...
+sender.send(event);
+```

package/src/analytics/analytics.ts

@@ -0,0 +1,76 @@
+import type {
+  AnalyticsAdapter,
+  AnalyticsPayload,
+  Context,
+  CreateEventFn,
+  Metadata,
+} from "./types";
+import { eventID } from "./utils/eventIds";
+import { toSnakeCaseDeep } from "./utils/toSnakeCaseDeep";
+
+const METADATA: Metadata = Object.freeze({
+  version: "v1.0",
+});
+
+export const analyticsEvents = Object.freeze({
+  METADATA,
+  /**
+   * This function creates an event builder, which lets you construct correct and strongly-typed
+   * event payloads according to the current schema used by this package
+   * @param context
+   * @returns
+   */
+  eventBuilder: (context: Context) => {
+    const newEvent: CreateEventFn<AnalyticsPayload> = ({
+      id: eventId,
+      payload: eventData,
+    }) => {
+      // runtime check just in case - shouldn't be needed due to TS
+      if (!eventID(eventId).isValid()) {
+        throw new Error(`Implementation error: Invalid event id: ${eventId}`);
+      }
+
+      const uniqueEventId = crypto.randomUUID();
+
+      const data = (() => {
+        if (!eventData) {
+          return undefined;
+        }
+
+        return toSnakeCaseDeep((eventData as unknown) ?? {});
+      })();
+
+      const event = {
+        id: `editor_${eventId}`,
+        data: {
+          ...data,
+          // eslint-disable-next-line camelcase
+          job_id: context.jobId,
+          // eslint-disable-next-line camelcase
+          event_id: uniqueEventId,
+          timestamp: new Date().toISOString(),
+        },
+      };
+
+      return event;
+    };
+
+    return { newEvent };
+  },
+  /**
+   * This function creates an event sender which will use an internal implementation of an adapter
+   * to forward the event's data to an external third-party provider
+   * @returns
+   */
+  eventSender: (adapter: AnalyticsAdapter) => {
+    const send = (event: AnalyticsPayload) => {
+      adapter.sendEvent({
+        event,
+        idParser: eventID(event.id).parse,
+        metadata: METADATA,
+      });
+    };
+
+    return { send };
+  },
+});

package/src/analytics/index.ts

@@ -0,0 +1,2 @@
+export * from "./analytics";
+export type { CreateEventFn, AnalyticsAdapter } from "./types";

package/src/analytics/schema/schema.d.ts

@@ -0,0 +1,129 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+export type EmptyPayload = null;
+export type NodeCreated_Base = NodeCreated_Common & NodeOrComponent;
+export type NodeCreated_WithOptionalConnectedTo = NodeCreated_Common &
+  NodeOrComponent & {
+    connectedTo?: ConnectedTo_Basic;
+  };
+export type NodeCreated_WithOptionalConnectedToPorts = NodeCreated_Common &
+  NodeOrComponent & {
+    connectedTo?: ConnectedTo_WithPorts;
+  };
+
+export interface AnalyticsEventSchema {
+  version: "v1.0";
+  events: {
+    kai_prompted: {
+      kaiqa_button_: EmptyPayload;
+      kaibuild_button_: EmptyPayload;
+      qam_button_: KaiPromptedPayload;
+    };
+    layouteditor_opened: {
+      canvas_ctxmenu_openlayouteditor: EmptyPayload;
+      keyboard_shortcut_openlayouteditor: EmptyPayload;
+      wftoolbar_button_openlayouteditor: EmptyPayload;
+    };
+    annotation_created: {
+      canvas_ctxmenu_newannotation: EmptyPayload;
+      canvas_ctxmenu_kaiexplain: EmptyPayload;
+    };
+    workflow_saved: {
+      wftoolbar_button_save: WorkflowSavedPayload;
+      keyboard_shortcut_savewf: WorkflowSavedPayload;
+    };
+    connection_created: {
+      port_dragdrop_fwd: ConnectionCreatedPayload;
+      port_dragdrop_bwd: ConnectionCreatedPayload;
+      keyboard_shortcut_connectnodes: EmptyPayload;
+      keyboard_shortcut_connectflowvar: EmptyPayload;
+      canvas_ctxmenu_connectnodes: EmptyPayload;
+      canvas_ctxmenu_connectflowvar: EmptyPayload;
+    };
+    node_created: {
+      noderepo_dragdrop_: NodeCreated_Base;
+      noderepo_doubleclick_: NodeCreated_WithOptionalConnectedTo;
+      noderepo_keyboard_enter: NodeCreated_WithOptionalConnectedTo;
+      explorer_dragdrop_: NodeCreated_Base;
+      qam_click_: NodeCreated_WithOptionalConnectedToPorts;
+      qam_keyboard_enter: NodeCreated_WithOptionalConnectedToPorts;
+      kaiqa_dragdrop_: NodeCreated_Base;
+      kaiqa_keyboard_enter: NodeCreated_Base;
+    };
+    qam_opened: {
+      port_dragdrop_fwd: QAMOpened_Payload;
+      port_dragdrop_bwd: QAMOpened_Payload;
+      canvas_doubleclick_: EmptyPayload;
+      keyboard_shortcut_: QAMOpened_PartialPayload;
+      canvas_ctxmenu_quickaddnode: EmptyPayload;
+    };
+    node_searched: {
+      noderepo_type_: SearchPayload;
+      qam_type_: SearchPayload;
+    };
+    sidepanel_opened: {
+      sidepanel_click_info: EmptyPayload;
+      sidepanel_click_noderepo: EmptyPayload;
+      sidepanel_click_explorer: EmptyPayload;
+      sidepanel_click_kai: EmptyPayload;
+      sidepanel_click_monitor: EmptyPayload;
+      wftoolbar_dropdownmenu_versionhistory: EmptyPayload;
+    };
+    action_undone: {
+      wftoolbar_button_: EmptyPayload;
+      keyboard_shortcut_: EmptyPayload;
+    };
+    action_redone: {
+      wftoolbar_button_: EmptyPayload;
+      keyboard_shortcut_: EmptyPayload;
+    };
+  };
+}
+export interface KaiPromptedPayload {
+  nodeFactoryId?: string;
+  nodeType?: "node" | "component" | "metanode";
+}
+export interface WorkflowSavedPayload {
+  isAutosyncEnabled: boolean;
+}
+export interface ConnectionCreatedPayload {
+  fromNode: ConnectionCreated_NodePayload;
+  toNode: ConnectionCreated_NodePayload;
+}
+export interface ConnectionCreated_NodePayload {
+  nodeType: "node" | "component" | "metanode";
+  nodePortIndex: number;
+  nodePortId: string;
+  nodeFactoryId?: string;
+}
+export interface NodeCreated_Common {
+  nodeType: "node" | "component";
+}
+export interface NodeOrComponent {
+  nodeFactoryId?: string;
+  nodeHubId?: string;
+}
+export interface ConnectedTo_Basic {
+  nodeType: "node" | "component" | "metanode";
+  nodeFactoryId: string;
+}
+export interface ConnectedTo_WithPorts {
+  nodeType: "node" | "component" | "metanode";
+  nodeFactoryId: string;
+  nodePortIndex?: number;
+  nodePortId?: string;
+}
+export interface QAMOpened_Payload {
+  connectedTo: ConnectedTo_WithPorts;
+}
+export interface QAMOpened_PartialPayload {
+  connectedTo?: ConnectedTo_WithPorts;
+}
+export interface SearchPayload {
+  repoType: "node" | "component";
+  keyword: string;
+}

package/src/analytics/schema/schema.json

@@ -0,0 +1,472 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "inmemory://schemas/analytics-events.json",
+  "title": "AnalyticsEventSchema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "events"],
+  "properties": {
+    "version": {
+      "$comment": "Version of this document",
+      "type": "string",
+      "const": "v1.0"
+    },
+    "events": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kai_prompted",
+        "layouteditor_opened",
+        "annotation_created",
+        "workflow_saved",
+        "connection_created",
+        "node_created",
+        "qam_opened",
+        "node_searched",
+        "sidepanel_opened",
+        "action_undone",
+        "action_redone"
+      ],
+      "properties": {
+        "kai_prompted": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kaiqa_button_", "kaibuild_button_", "qam_button_"],
+          "properties": {
+            "kaiqa_button_": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "kaibuild_button_": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "qam_button_": {
+              "$ref": "#/definitions/KaiPromptedPayload"
+            }
+          }
+        },
+        "layouteditor_opened": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "canvas_ctxmenu_openlayouteditor",
+            "keyboard_shortcut_openlayouteditor",
+            "wftoolbar_button_openlayouteditor"
+          ],
+          "properties": {
+            "canvas_ctxmenu_openlayouteditor": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "keyboard_shortcut_openlayouteditor": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "wftoolbar_button_openlayouteditor": {
+              "$ref": "#/definitions/EmptyPayload"
+            }
+          }
+        },
+        "annotation_created": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "canvas_ctxmenu_newannotation",
+            "canvas_ctxmenu_kaiexplain"
+          ],
+          "properties": {
+            "canvas_ctxmenu_newannotation": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "canvas_ctxmenu_kaiexplain": {
+              "$ref": "#/definitions/EmptyPayload"
+            }
+          }
+        },
+        "workflow_saved": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["wftoolbar_button_save", "keyboard_shortcut_savewf"],
+          "properties": {
+            "wftoolbar_button_save": {
+              "$ref": "#/definitions/WorkflowSavedPayload"
+            },
+            "keyboard_shortcut_savewf": {
+              "$ref": "#/definitions/WorkflowSavedPayload"
+            }
+          }
+        },
+        "connection_created": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "port_dragdrop_fwd",
+            "port_dragdrop_bwd",
+            "keyboard_shortcut_connectnodes",
+            "keyboard_shortcut_connectflowvar",
+            "canvas_ctxmenu_connectnodes",
+            "canvas_ctxmenu_connectflowvar"
+          ],
+          "properties": {
+            "port_dragdrop_fwd": {
+              "$ref": "#/definitions/ConnectionCreatedPayload"
+            },
+            "port_dragdrop_bwd": {
+              "$ref": "#/definitions/ConnectionCreatedPayload"
+            },
+            "keyboard_shortcut_connectnodes": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "keyboard_shortcut_connectflowvar": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "canvas_ctxmenu_connectnodes": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "canvas_ctxmenu_connectflowvar": {
+              "$ref": "#/definitions/EmptyPayload"
+            }
+          }
+        },
+        "node_created": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "noderepo_dragdrop_",
+            "noderepo_doubleclick_",
+            "noderepo_keyboard_enter",
+            "explorer_dragdrop_",
+            "qam_click_",
+            "qam_keyboard_enter",
+            "kaiqa_dragdrop_",
+            "kaiqa_keyboard_enter"
+          ],
+          "properties": {
+            "noderepo_dragdrop_": {
+              "$ref": "#/definitions/NodeCreated_Base"
+            },
+            "noderepo_doubleclick_": {
+              "$ref": "#/definitions/NodeCreated_WithOptionalConnectedTo"
+            },
+            "noderepo_keyboard_enter": {
+              "$ref": "#/definitions/NodeCreated_WithOptionalConnectedTo"
+            },
+            "explorer_dragdrop_": {
+              "$ref": "#/definitions/NodeCreated_Base"
+            },
+            "qam_click_": {
+              "$ref": "#/definitions/NodeCreated_WithOptionalConnectedToPorts"
+            },
+            "qam_keyboard_enter": {
+              "$ref": "#/definitions/NodeCreated_WithOptionalConnectedToPorts"
+            },
+            "kaiqa_dragdrop_": {
+              "$ref": "#/definitions/NodeCreated_Base"
+            },
+            "kaiqa_keyboard_enter": {
+              "$ref": "#/definitions/NodeCreated_Base"
+            }
+          }
+        },
+        "qam_opened": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "port_dragdrop_fwd",
+            "port_dragdrop_bwd",
+            "canvas_doubleclick_",
+            "keyboard_shortcut_",
+            "canvas_ctxmenu_quickaddnode"
+          ],
+          "properties": {
+            "port_dragdrop_fwd": {
+              "$ref": "#/definitions/QAMOpened_Payload"
+            },
+            "port_dragdrop_bwd": {
+              "$ref": "#/definitions/QAMOpened_Payload"
+            },
+            "canvas_doubleclick_": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "keyboard_shortcut_": {
+              "$ref": "#/definitions/QAMOpened_PartialPayload"
+            },
+            "canvas_ctxmenu_quickaddnode": {
+              "$ref": "#/definitions/EmptyPayload"
+            }
+          }
+        },
+        "node_searched": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["noderepo_type_", "qam_type_"],
+          "properties": {
+            "noderepo_type_": {
+              "$ref": "#/definitions/SearchPayload"
+            },
+            "qam_type_": {
+              "$ref": "#/definitions/SearchPayload"
+            }
+          }
+        },
+        "sidepanel_opened": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "sidepanel_click_info",
+            "sidepanel_click_noderepo",
+            "sidepanel_click_explorer",
+            "sidepanel_click_kai",
+            "sidepanel_click_monitor",
+            "wftoolbar_dropdownmenu_versionhistory"
+          ],
+          "properties": {
+            "sidepanel_click_info": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "sidepanel_click_noderepo": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "sidepanel_click_explorer": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "sidepanel_click_kai": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "sidepanel_click_monitor": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "wftoolbar_dropdownmenu_versionhistory": {
+              "$ref": "#/definitions/EmptyPayload"
+            }
+          }
+        },
+        "action_undone": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["wftoolbar_button_", "keyboard_shortcut_"],
+          "properties": {
+            "wftoolbar_button_": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "keyboard_shortcut_": {
+              "$ref": "#/definitions/EmptyPayload"
+            }
+          }
+        },
+        "action_redone": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["wftoolbar_button_", "keyboard_shortcut_"],
+          "properties": {
+            "wftoolbar_button_": {
+              "$ref": "#/definitions/EmptyPayload"
+            },
+            "keyboard_shortcut_": {
+              "$ref": "#/definitions/EmptyPayload"
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "EmptyPayload": {
+      "type": "null",
+      "additionalProperties": false,
+      "maxProperties": 0
+    },
+    "WorkflowSavedPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["isAutosyncEnabled"],
+      "properties": {
+        "isAutosyncEnabled": {
+          "type": "boolean"
+        }
+      }
+    },
+    "ConnectionCreated_NodePayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodeType", "nodePortIndex", "nodePortId"],
+      "properties": {
+        "nodeType": {
+          "type": "string",
+          "enum": ["node", "component", "metanode"]
+        },
+        "nodePortIndex": {
+          "type": "number"
+        },
+        "nodePortId": {
+          "type": "string"
+        },
+        "nodeFactoryId": {
+          "type": "string"
+        }
+      }
+    },
+    "ConnectionCreatedPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fromNode", "toNode"],
+      "properties": {
+        "fromNode": {
+          "$ref": "#/definitions/ConnectionCreated_NodePayload"
+        },
+        "toNode": {
+          "$ref": "#/definitions/ConnectionCreated_NodePayload"
+        }
+      }
+    },
+    "KaiPromptedPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "nodeFactoryId": {
+          "type": "string"
+        },
+        "nodeType": {
+          "type": "string",
+          "enum": ["node", "component", "metanode"]
+        }
+      }
+    },
+    "NodeOrComponent": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "nodeFactoryId": {
+          "type": "string",
+          "$comment": "asdasd"
+        },
+        "nodeHubId": {
+          "type": "string"
+        }
+      }
+    },
+    "NodeCreated_Common": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodeType"],
+      "properties": {
+        "nodeType": {
+          "type": "string",
+          "enum": ["node", "component"]
+        }
+      }
+    },
+    "ConnectedTo_Basic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodeType", "nodeFactoryId"],
+      "properties": {
+        "nodeType": {
+          "type": "string",
+          "enum": ["node", "component", "metanode"]
+        },
+        "nodeFactoryId": {
+          "type": "string"
+        }
+      }
+    },
+    "ConnectedTo_WithPorts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodeType", "nodeFactoryId"],
+      "properties": {
+        "nodeType": {
+          "type": "string",
+          "enum": ["node", "component", "metanode"]
+        },
+        "nodeFactoryId": {
+          "type": "string"
+        },
+        "nodePortIndex": {
+          "type": "number"
+        },
+        "nodePortId": {
+          "type": "string"
+        }
+      }
+    },
+    "NodeCreated_Base": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/NodeCreated_Common"
+        },
+        {
+          "$ref": "#/definitions/NodeOrComponent"
+        }
+      ]
+    },
+    "NodeCreated_WithOptionalConnectedTo": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/NodeCreated_Common"
+        },
+        {
+          "$ref": "#/definitions/NodeOrComponent"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "connectedTo": {
+              "$ref": "#/definitions/ConnectedTo_Basic"
+            }
+          }
+        }
+      ]
+    },
+    "NodeCreated_WithOptionalConnectedToPorts": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/NodeCreated_Common"
+        },
+        {
+          "$ref": "#/definitions/NodeOrComponent"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "connectedTo": {
+              "$ref": "#/definitions/ConnectedTo_WithPorts"
+            }
+          }
+        }
+      ]
+    },
+    "QAMOpened_Payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["connectedTo"],
+      "properties": {
+        "connectedTo": {
+          "$ref": "#/definitions/ConnectedTo_WithPorts"
+        }
+      }
+    },
+    "QAMOpened_PartialPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "connectedTo": {
+          "$ref": "#/definitions/ConnectedTo_WithPorts"
+        }
+      }
+    },
+    "SearchPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repoType", "keyword"],
+      "properties": {
+        "repoType": {
+          "type": "string",
+          "enum": ["node", "component"]
+        },
+        "keyword": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/src/analytics/types.ts

@@ -0,0 +1,62 @@
+import type { AnalyticsEventSchema } from "./schema/schema";
+
+export const SEPARATOR = "::";
+type Separator = typeof SEPARATOR;
+
+type EventDefinitions = AnalyticsEventSchema["events"];
+
+/**
+ * Group names (top-level keys in `events`, e.g. "kai_prompted").
+ */
+type GroupName = keyof EventDefinitions;
+
+/**
+ * Event names in the flattened "group::event" form. This makes event calls
+ * single keys using the `::` separator (for example "kai_prompted::kaiqa_button_prompt").
+ */
+export type EventNames = {
+  [G in GroupName]: `${G}${Separator}${keyof EventDefinitions[G] & string}`;
+}[GroupName];
+
+export type Metadata = Omit<AnalyticsEventSchema, "events">;
+
+export type Context = { jobId: string };
+
+/**
+ * Resolve the payload type for a flattened event name like
+ * "group::eventKey". If the referenced payload is `null`, the args are
+ * just the type; otherwise a payload must be provided.
+ */
+type PayloadFor<KN extends EventNames> =
+  KN extends `${infer G}${Separator}${infer E}`
+    ? G extends GroupName
+      ? E extends keyof EventDefinitions[G]
+        ? EventDefinitions[G][E]
+        : never
+      : never
+    : never;
+
+type EventArgs<K extends EventNames> =
+  PayloadFor<K> extends null
+    ? { id: K; payload?: never }
+    : { id: K; payload: PayloadFor<K> };
+
+export type AnalyticsPayload = {
+  id: string;
+  data: unknown;
+};
+
+export type CreateEventFn<TReturn = void> = <K extends EventNames>(
+  args: EventArgs<K>,
+) => TReturn;
+
+export interface AnalyticsAdapter {
+  /**
+   * Function to send the event according to the API the adapter is implementing
+   */
+  sendEvent: (params: {
+    idParser: (id: string) => { category: string; action: string };
+    event: AnalyticsPayload;
+    metadata: Metadata;
+  }) => void;
+}

package/src/analytics/utils/eventIds.ts

@@ -0,0 +1,35 @@
+import { SEPARATOR } from "../types";
+
+const isValid = (id: string) => id.includes(SEPARATOR);
+
+/**
+ * Parses the given event id, splitting it by a known separator. Each id is expected to have
+ * two components to it: The event category and a specific action within that category
+ * @returns
+ * @throws when id format is invalid
+ */
+const parse = (id: string): { category: string; action: string } => {
+  if (!isValid(id)) {
+    throw new Error(`Cannot parse event id. Invalid format found: ${id}`);
+  }
+
+  const out = id.split(SEPARATOR);
+
+  if (out.length !== 2) {
+    throw new Error(`Cannot parse event id. Invalid format found: ${id}`);
+  }
+
+  const [category, action] = out;
+  return { category, action };
+};
+
+export const eventID = (id: string) => ({
+  isValid: () => isValid(id),
+  /**
+   * Parses the given event id, splitting it by a known separator. Each id is expected to have
+   * two components to it: The event category and a specific action within that category
+   * @returns
+   * @throws when id format is invalid
+   */
+  parse: () => parse(id),
+});

package/src/analytics/utils/toSnakeCaseDeep.ts

@@ -0,0 +1,33 @@
+// eslint-disable-next-line depend/ban-dependencies
+import { snakeCase } from "lodash-es";
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+};
+
+/**
+ * Deeply converts all properties in the given object from camelCase to snake_case.
+ */
+export const toSnakeCaseDeep = (object: Partial<Record<string, unknown>>) =>
+  Object.entries(object).reduce(
+    (acc, [rawKey, rawValue]) => {
+      const key = rawKey.toString();
+
+      if (isPlainObject(rawValue)) {
+        acc[snakeCase(key)] = toSnakeCaseDeep(rawValue);
+      } else if (Array.isArray(rawValue)) {
+        acc[snakeCase(key)] = rawValue.map((v) =>
+          isPlainObject(v) ? toSnakeCaseDeep(v) : v,
+        );
+      } else {
+        acc[snakeCase(key)] = rawValue;
+      }
+
+      return acc;
+    },
+    {} as Record<string, unknown>,
+  );

package/src/authUtils/README.md

@@ -0,0 +1,123 @@
+# KNIME® Hub Auth Utils
+
+The auth utils can be used to implement authentication in the hub. The idea is to use them in conjunction with the [knime-hub-auth-rely] service. Please check the service docs for detailed infos about the authentication flow.
+
+[knime-hub-auth-rely]: https://github.com/knime/knime-hub-auth-rely
+
+## Common usage pattern
+
+First you need to setup the auth refresher. This will make sure that the auth identity information
+is fetched on critical authenticated paths. Normally, this means as part of a `vue-router` route guard
+or a `Nuxt` middleware.
+
+```ts
+/// router.ts
+import { authUtils } from "@knime/hub-features";
+
+const myMiddleware = (): NavigationGuard => {
+  // 1. First we create the refresher. This returns the function that
+  // schedules running the token refresher periodically
+  const authRefresher = authUtils.createAuthRefresher({
+    // `getIdentity` is just a fetch function that hits the API to get the
+    // account information; in a nutshell a user `id` and a `name`
+    getIdentity,
+  });
+
+  // 2. Here we're now returning the _actual_ navigation guard
+  return async () => {
+    try {
+      await authRefresher();
+      return true; // allow navigation
+    } catch (error) {
+      consola.error("Navigation middleware error", error);
+      return false; // cancel navigation
+    }
+  };
+};
+
+const router = createRouter({
+  history: createWebHistory(base),
+  routes: [
+    {
+      path: "/",
+      name: "Home",
+      component: HomeRouteComponent,
+      // 3. Simply setup your middleware for usage
+      beforeEnter: [myMiddleware()],
+
+      // 4. A simpler usage could have been
+      // beforeEnter: [authUtils.createAuthRefresher({ getIdentity })],
+    },
+  ],
+});
+```
+
+### Handle auth errors
+
+Another common pattern you'll need is to react to authentication errors (401/403) on your requests. There's different ways
+to do this depending on the setup, but it usually revolves around setting up some HTTP request interceptor that runs some
+code upon receveing a 401 (and optionally sometimes a 403).
+
+Below is an example of an `ofetch` interceptor and how you would use these utils for such a case
+
+```ts
+// interceptor.ts
+import { authUtils } from "@knime/hub-features";
+
+export const unauthorizedInterceptor: HttpInterceptor = {
+  response: {
+    onError: ({ response }) => {
+      if (response?.status === 401) {
+        // This function performs the redirection automatically.
+        authUtils.client.navigateToLogin({ wdywtg: window.location.href });
+
+        throw new Error("Auth failure");
+      }
+    },
+  },
+};
+```
+
+However, in the above example, the usage of `authUtils.client.navigateToLogin` is client-side code, which uses the `window` object to
+redirect. Therefore, this doesn't work on SSR. If you need a server-side redirect, or if you want more control of _how_ you redirect (e.g using Nuxt's `navigateTo` function)
+you can instead call another util which returns the login url and you can perform the redirection on your own:
+
+```ts
+// some-file.ts
+
+import { authUtils } from "@knime/hub-features";
+
+const someHandler = () => {
+  // ...
+  const loginPath = authUtils.paths.login({ wdywtg: to.fullPath });
+  return navigateTo(loginPath, {
+    external: true,
+    redirectCode: TEMPORARY_REDIRECT,
+  });
+
+  // ...
+};
+```
+
+### Accessing auth state
+
+With the middleware in place, you can now reference the auth state in your app by making use of the provided stateful composable:
+
+```ts
+/// some-file.ts
+import { authUtils } from "@knime/hub-features";
+
+const { loggedInUser, isLoggedIn } = authUtils.useAuthState();
+```
+
+This state is immutable and is owned and controlled by the auth refresher internally.
+
+### Stop refreshing the auth token
+
+In addition to the route middleware setup, you might run into cases where you want to stop the refresher manually. For this, simply import the corresponding function and call it:
+
+```ts
+import { authUtils } from "@knime/hub-features";
+
+authUtils.stopTokenRefresh();
+```

package/src/authUtils/client.ts

@@ -0,0 +1,18 @@
+import { logger } from "./logger";
+import { buildLoginPath, buildLogoutPath } from "./shared";
+
+/**
+ * Navigates to the login path. This function does not work on SSR
+ */
+export const navigateToLogin = ({ wdywtg }: { wdywtg?: string } = {}) => {
+  logger().debug("Navigating to login");
+  window.location.href = buildLoginPath({ wdywtg }); // NOSONAR - intended window usage
+};
+
+/**
+ * Navigates to the logout path. This function does not work on SSR
+ */
+export const navigateToLogout = ({ wdywtg }: { wdywtg?: string } = {}) => {
+  logger().debug("Navigating to logout");
+  window.location.href = buildLogoutPath({ wdywtg }); // NOSONAR - intended window usage
+};

package/src/authUtils/index.ts

@@ -0,0 +1,61 @@
+import * as client from "./client";
+import { logger } from "./logger";
+import { startRefresher, stopRefresher } from "./refresher";
+import { buildLoginPath, buildLogoutPath } from "./shared";
+import type { AuthRefresher } from "./types";
+import { setLoggedInUser, useAuthState } from "./useAuthState";
+
+/**
+ * This function does two main things:
+ * 1. Fetch the user identity and store it via the auth composable.
+ * 2. Start the background refresher which will renew tokens according to the
+ *    auth service TTL.
+ *
+ * Typical usage is from a route middleware for routes that require
+ * authentication. See README for a more in-depth example usage
+ *
+ * @param options AuthRefresher
+ * @returns a function that, when called, will load the identity (if needed)
+ * and start the token refresher. The returned function will throw if the
+ * underlying identity fetch fails.
+ */
+function createAuthRefresher(options: AuthRefresher) {
+  return async () => {
+    const { isLoggedIn } = useAuthState();
+
+    if (!isLoggedIn.value) {
+      try {
+        const identity = await options.getIdentity();
+
+        if (identity) {
+          logger().info("Fetched user identity", {
+            id: identity.id,
+            name: identity.name,
+          });
+
+          setLoggedInUser(identity);
+          startRefresher({ onRefreshComplete: options.onRefreshComplete });
+        } else {
+          logger().error("Logged in, but could not retrieve logged in user");
+        }
+      } catch (e) {
+        logger().error(
+          "Not logged in, http request interceptor should redirect to login",
+          e,
+        );
+        throw e;
+      }
+    }
+  };
+}
+
+export const authUtils = {
+  createAuthRefresher,
+  stopTokenRefresh: stopRefresher,
+  useAuthState,
+  /**
+   * These utilities don't work in SSR. You can leverage the `paths` helpers to redirect manually
+   */
+  client,
+  paths: { login: buildLoginPath, logout: buildLogoutPath },
+};

package/src/authUtils/logger.ts

@@ -0,0 +1 @@
+export const logger = () => consola.withTag("Auth Utils");

package/src/authUtils/refresher.ts

@@ -0,0 +1,65 @@
+import { navigateToLogout } from "./client";
+import { logger } from "./logger";
+import { AUTH_SERVICE_PATH } from "./shared";
+import type { AuthRefresher } from "./types";
+
+type Options = Pick<AuthRefresher, "onRefreshComplete">;
+
+const REFRESH_BUFFER = 10;
+/**
+ * Subtracts a random noise value from the ttl to refresh the token before it actually expires.
+ *
+ * @param {number}  ttlSeconds - time-to-live (TTL) in seconds
+ */
+const subtractRandomNoise = (ttlSeconds: number) => {
+  const randomBuffer = Math.random() * (REFRESH_BUFFER / 2); // NOSONAR using random numbers is safe here
+  return Math.floor((ttlSeconds - REFRESH_BUFFER - randomBuffer) * 1000);
+};
+
+let timeout: number | NodeJS.Timeout;
+
+/**
+ * Start proactively refreshing the token before it expires.
+ */
+export const startRefresher = (options: Options = {}) => {
+  logger().debug("Starting token refresher");
+
+  globalThis.clearTimeout(timeout);
+
+  const fetchData = async () => {
+    try {
+      const response = await fetch(`${AUTH_SERVICE_PATH}/refresh`);
+
+      if (!response.ok) {
+        throw new Error(`Error during auth refresh: ${response.status}`);
+      }
+
+      options?.onRefreshComplete?.();
+      const { expiry } = await response.json();
+
+      const msUntilRefresh = subtractRandomNoise(expiry);
+
+      logger().debug(
+        `Token is valid. Expires in ${expiry}s, refreshing in ${msUntilRefresh / 1000}s`,
+      );
+
+      timeout = globalThis.setTimeout(() => {
+        // eslint-disable-next-line no-void
+        void fetchData();
+      }, msUntilRefresh);
+    } catch (error) {
+      logger().warn(`Token refresh failed: ${error}, logging out`);
+      navigateToLogout({ wdywtg: "/?authError=refresh" });
+    }
+  };
+
+  // eslint-disable-next-line no-void
+  void fetchData();
+};
+
+export const stopRefresher = () => {
+  if (timeout !== undefined) {
+    logger().info("Stopping auth refresh timer");
+    globalThis.clearTimeout(timeout);
+  }
+};

package/src/authUtils/shared.ts

@@ -0,0 +1,25 @@
+/**
+ * Adds a "where do you want to go" `wdywtg` query param to the url. This
+ * will take the user to the URL contained within that param after the auth flow completes
+ */
+const addWdywtg = (url: string, wdywtg?: string) => {
+  if (wdywtg) {
+    const decodedWdywtg = decodeURIComponent(wdywtg);
+
+    // we decode an already-encoded wdywtg so that we can properly encode spaces
+    if (decodedWdywtg !== wdywtg) {
+      wdywtg = decodedWdywtg;
+    }
+
+    url += `?wdywtg=${encodeURIComponent(wdywtg)}`;
+  }
+  return url;
+};
+
+export const AUTH_SERVICE_PATH = "/_/auth";
+
+export const buildLoginPath = ({ wdywtg }: { wdywtg?: string } = {}) =>
+  addWdywtg(`${AUTH_SERVICE_PATH}/login`, wdywtg);
+
+export const buildLogoutPath = ({ wdywtg }: { wdywtg?: string } = {}) =>
+  addWdywtg(`${AUTH_SERVICE_PATH}/logout`, wdywtg);

package/src/authUtils/types.ts

@@ -0,0 +1,12 @@
+export type UserIdentity = { id: string; name: string };
+
+export type AuthRefresher = {
+  /**
+   * Fetcher function to obtain the basic user identity information
+   */
+  getIdentity: () => Promise<UserIdentity>;
+  /**
+   * Callback that runs after each completion of an auth token refresh
+   */
+  onRefreshComplete?: () => unknown;
+};

package/src/authUtils/useAuthState.ts

@@ -0,0 +1,19 @@
+import { computed, readonly, shallowRef } from "vue";
+
+import type { UserIdentity } from "./types";
+
+// Value is cached in the module scope
+const loggedInUser = shallowRef<UserIdentity | null>(null);
+
+export const setLoggedInUser = (user: UserIdentity) => {
+  loggedInUser.value = user;
+};
+
+export const useAuthState = () => {
+  const isLoggedIn = computed(() => Boolean(loggedInUser.value));
+
+  return {
+    loggedInUser: readonly(loggedInUser),
+    isLoggedIn,
+  };
+};

package/src/embeddingSDK/types.ts

@@ -35,9 +35,14 @@ export type EmbeddingContext = {
    */
   userIdleTimeout?: number;
   /**
-   * Whether the embedded application can send analytic and tracking events
+   * Configuration for analytics
    */
-  enableAnalytics?: boolean;
+  analytics?: {
+    /**
+     * Whether the embedded application can send analytic and tracking events
+     */
+    enabled: boolean;
+  };
 };
 
 type ShowNotificationEvent = {

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./useFileUpload";
 export * from "./useDownloadArtifact";
 export * from "./components/avatars";
 export * from "./embeddingSDK";
+export * from "./authUtils";