@knime/hub-features 1.22.4 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @knime/hub-features
 
+## 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
+
+- 368d638: Fix error when fetching versions if user that created the version is no longer available
+
 ## 1.22.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knime/hub-features",
-  "version": "1.22.4",
+  "version": "1.24.0",
   "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,9 +39,9 @@
     "lodash-es": "4.17.23",
     "ofetch": "^1.4.1",
     "typescript": "^5.9.3",
-    "@knime/components": "1.45.9",
-    "@knime/utils": "1.10.1",
-    "@knime/styles": "1.15.0"
+    "@knime/components": "1.45.10",
+    "@knime/styles": "1.15.0",
+    "@knime/utils": "1.10.1"
   },
   "peerDependencies": {
     "consola": "3.x",
@@ -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;
+}