@knime/hub-features 1.26.2 → 1.28.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @knime/hub-features
 
+## 1.28.0
+
+### Minor Changes
+
+- 2908385: - split returned events based on event source (editor/cloudhome)
+  - add secret created event (cloudhome)
+  - introduce page property to interaction property (only for cloudhome events)
+
+### Patch Changes
+
+- a2f988b: add cloudhome events for creating and sharing deployments
+
+## 1.27.0
+
+### Minor Changes
+
+- 3a49573: Rework API for analytic events and the underlying schema
+
 ## 1.26.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knime/hub-features",
-  "version": "1.26.2",
+  "version": "1.28.0",
   "description": "Vue components & composables for shared hub features",
   "repository": {
     "type": "git",
@@ -39,8 +39,8 @@
     "lodash-es": "4.18.1",
     "ofetch": "^1.4.1",
     "typescript": "^5.9.3",
-    "@knime/components": "1.46.6",
     "@knime/styles": "1.15.1",
+    "@knime/components": "1.46.6",
     "@knime/utils": "1.11.0"
   },
   "peerDependencies": {
@@ -62,6 +62,8 @@
   "scripts": {
     "type-check": "vue-tsc --noEmit -p tsconfig.vitest.json --composite false",
     "test:unit": "TZ='Europe/Berlin' vitest",
-    "generate-analytics-events": "json2ts ./src/analytics/schema/schema.json > ./src/analytics/schema/schema.d.ts"
+    "generate-analytics-events": "pnpm generate-event-types && pnpm generate-event-functions",
+    "generate-event-types": "json2ts ./src/analytics/schema/schema.json > ./src/analytics/schema/schema.d.ts",
+    "generate-event-functions": "node ./src/analytics/schema/code-generator.js"
   }
 }

package/src/analytics/README.md

@@ -2,86 +2,32 @@
 
 ## 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.
+This package provides functions that can produce analytics events.
 
 ## 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.
+This package makes no assumption of how the events are sent. Therefore, one must supply a "sender" as
+part of the initialization.
 
 ```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
+// Create a sender, which can be pretty much any object that provides a `send` function
+const mySender = {
+  send: ({ event }) => {
+    // do something with event (e.g send over WS, dispatch to an iframe's parent, etc)
+  },
 };
-```
-
-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);
+// Initialize the tracker
+type SomeContext = { myContextField: string };
+const eventTracker = analyticsEvents.init<SomeContext>({
+  context: { myContextField: "foo-123" },
+  sender: mySender,
+});
+
+// Track an event. `someEvent` here is a placeholder name. In reality, the API will provide named functions that
+// strongly-typed and may or may not require payload depending on the event's definition. Under the hood this will
+// use the configured sender to forward your event
+eventTracker.someEvent();
 ```

package/src/analytics/analytics.ts

@@ -1,76 +1,116 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as cloudHomeFunctions from "./schema/cloudhome-event-functions";
+import * as editorFunctions from "./schema/editor-event-functions";
 import type {
-  AnalyticsAdapter,
-  AnalyticsPayload,
-  Context,
-  CreateEventFn,
+  AnalyticsEvent,
+  AnalyticsEventSender,
+  DefaultContext,
   Metadata,
 } from "./types";
-import { eventID } from "./utils/eventIds";
-import { toSnakeCaseDeep } from "./utils/toSnakeCaseDeep";
 
 const METADATA: Metadata = Object.freeze({
-  version: "v1.0",
+  version: "v2.0",
 });
 
+/**
+ * Unwraps the inner function imported from the generated functions.
+ * With this supply the context here and just expose the inner function
+ * but also ensure we keep the same names and type constraints
+ */
+type UnwrapFunction<T> = T extends (ctx: DefaultContext) => infer R
+  ? R extends (...args: infer P) => infer Q
+    ? (...args: P) => Q
+    : never
+  : never;
+
+type EditorFunctionMap = typeof editorFunctions;
+type CloudHomeFunctionMap = typeof cloudHomeFunctions;
+
+type EditorBuilderFunctions = {
+  [K in keyof EditorFunctionMap]: UnwrapFunction<EditorFunctionMap[K]>;
+};
+type CloudHomeBuilderFunctions = {
+  [K in keyof CloudHomeFunctionMap]: UnwrapFunction<CloudHomeFunctionMap[K]>;
+};
+
+type EditorSenderFunctions = {
+  [K in keyof EditorBuilderFunctions]: (
+    ...args: Parameters<EditorBuilderFunctions[K]>
+  ) => void;
+};
+type CloudHomeSenderFunctions = {
+  [K in keyof CloudHomeBuilderFunctions]: (
+    ...args: Parameters<CloudHomeBuilderFunctions[K]>
+  ) => void;
+};
+
+type BuilderFunctions<T extends DefaultContext> =
+  T["eventSource"] extends "editor"
+    ? EditorBuilderFunctions
+    : CloudHomeBuilderFunctions;
+
+type SenderFunctions<T extends DefaultContext> =
+  T["eventSource"] extends "editor"
+    ? EditorSenderFunctions
+    : CloudHomeSenderFunctions;
+
+/**
+ * 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
+ */
+function eventBuilder<T extends DefaultContext>(
+  context: T,
+): BuilderFunctions<T> {
+  const unwrapped = Object.fromEntries(
+    Object.entries(
+      context.eventSource === "editor" ? editorFunctions : cloudHomeFunctions,
+    ).map(([name, fn]) => [name, fn(context)]),
+  ) as BuilderFunctions<T>;
+
+  return { ...unwrapped };
+}
+
 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
+   * Initialize the analytic event tracker
    */
-  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}`);
-      }
+  init: <T extends DefaultContext>(params: {
+    /**
+     * Context for the initialized tracker. This will remain unchanged throughout the lifecycle
+     * of this tracker
+     */
+    context: T;
+    /**
+     * Sender interface; will be used to determine how to handle each event when its
+     * corresponding track function is invoked
+     */
+    sender: AnalyticsEventSender;
+  }) => {
+    const builder = eventBuilder(params.context);
 
-      const uniqueEventId = crypto.randomUUID();
+    type AnyFn = (...args: any[]) => any;
 
-      const data = (() => {
-        if (!eventData) {
-          return undefined;
-        }
+    const wrapper = {} as SenderFunctions<T>;
 
-        return toSnakeCaseDeep((eventData as unknown) ?? {});
-      })();
+    // keep all the same functions of the builder but wrap around them for extra behavior
+    Object.keys(builder).forEach((fnName) => {
+      const key = fnName as keyof SenderFunctions<T>;
+      (wrapper as any)[key] = (...args: any[]) => {
+        // TS issue:
+        // ```A spread argument must either have a tuple type or be passed to a rest parameter.```
+        // This happens because when calling the methods generically, TS tries to join all function signatures
+        // into a union of tuples that contains all possible argument combinations for all of the functions.
+        // This leads to an unresolvable type error
+        // More details on the issue, see: https://github.com/microsoft/TypeScript/issues/49700
+        const event: AnalyticsEvent = (builder[key] as AnyFn)(...args);
 
-      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(),
-        },
+        params.sender.send({ event, metadata: METADATA });
       };
+    });
 
-      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 };
+    return wrapper;
   },
 });

package/src/analytics/index.ts

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

package/src/analytics/schema/cloudhome-event-functions.ts

@@ -0,0 +1,247 @@
+ 
+/* eslint-disable camelcase */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// AUTO-GENERATED FILE. DO NOT EDIT.
+import type { AnalyticsEvent, DefaultContext, EventFunctionArgs, GeneratedStaticFields, SchemaStaticFields } from "../types";
+import { toSnakeCaseDeep } from "../utils/toSnakeCaseDeep";
+
+/**
+ * Fired when the user clicks Run from the deployments page
+ */
+export const adHocExecutionStartedDeploymentsPage = <T extends DefaultContext>(ctx: T) => (): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "adhoc_execution_started",
+    event_source: "cloudhome",
+    event_display_name: "Ad Hoc Execution Started",
+    interaction: {
+      location: "main_area",
+      page: "deployments",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData } };
+
+  return event;
+};
+
+/**
+ * Fired when the user clicks Run in the ad hoc execution panel
+ */
+export const adHocExecutionStartedExecutionPanel = <T extends DefaultContext>(ctx: T) => (): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "adhoc_execution_started",
+    event_source: "cloudhome",
+    event_display_name: "Ad Hoc Execution Started",
+    interaction: {
+      location: "contextual_side_panel",
+      page: "workflow_details",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData } };
+
+  return event;
+};
+
+/**
+ * Fired when the user clicks Run from the workflow page
+ */
+export const adHocExecutionStartedWorkflowPage = <T extends DefaultContext>(ctx: T) => (): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "adhoc_execution_started",
+    event_source: "cloudhome",
+    event_display_name: "Ad Hoc Execution Started",
+    interaction: {
+      location: "main_area",
+      page: "workflow_details",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData } };
+
+  return event;
+};
+
+/**
+ * Fired when the user creates a new secret by clicking Create in the side panel on the team secrets page
+ */
+export const secretCreatedTeamSecrets = <T extends DefaultContext>(ctx: T) => (): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "secret_created",
+    event_source: "cloudhome",
+    event_display_name: "Secret Created",
+    interaction: {
+      location: "contextual_side_panel",
+      page: "secrets",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData } };
+
+  return event;
+};
+
+/**
+ * Fired when the user creates a new secret by clicking Create in the side panel on the personal secrets page
+ */
+export const secretCreatedMySecrets = <T extends DefaultContext>(ctx: T) => (): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "secret_created",
+    event_source: "cloudhome",
+    event_display_name: "Secret Created",
+    interaction: {
+      location: "contextual_side_panel",
+      page: "my_secrets",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData } };
+
+  return event;
+};
+
+/**
+ * Fired when the user clicks the Create button in the deployment creation side panel
+ */
+export const deploymentCreated = <T extends DefaultContext>(ctx: T) => (eventData: EventFunctionArgs<"deploymentCreated">): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "deployment_created",
+    event_source: "cloudhome",
+    event_display_name: "Deployment Created",
+    interaction: {
+      location: "contextual_side_panel",
+      page: "deployments",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData, payload: { ...toSnakeCaseDeep(eventData as Record<string, any>) } } };
+
+  return event;
+};
+
+/**
+ * Fired when the user shares a deployment via the access management side panel on the deployments page
+ */
+export const deploymentSharedDeploymentsAccessPanel = <T extends DefaultContext>(ctx: T) => (eventData: EventFunctionArgs<"deploymentSharedDeploymentsAccessPanel">): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "deployment_shared",
+    event_source: "cloudhome",
+    event_display_name: "Deployment Shared",
+    interaction: {
+      location: "contextual_side_panel",
+      page: "deployments",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData, payload: { ...toSnakeCaseDeep(eventData as Record<string, any>) } } };
+
+  return event;
+};
+
+/**
+ * Fired when the user shares a deployment via the sharing popup on the deployments page
+ */
+export const deploymentSharedDeploymentsSharingPopup = <T extends DefaultContext>(ctx: T) => (eventData: EventFunctionArgs<"deploymentSharedDeploymentsSharingPopup">): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "deployment_shared",
+    event_source: "cloudhome",
+    event_display_name: "Deployment Shared",
+    interaction: {
+      location: "module",
+      page: "deployments",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData, payload: { ...toSnakeCaseDeep(eventData as Record<string, any>) } } };
+
+  return event;
+};
+
+/**
+ * Fired when the user shares a deployment via the access management side panel on the workflow page
+ */
+export const deploymentSharedWorkflowAccessPanel = <T extends DefaultContext>(ctx: T) => (eventData: EventFunctionArgs<"deploymentSharedWorkflowAccessPanel">): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "deployment_shared",
+    event_source: "cloudhome",
+    event_display_name: "Deployment Shared",
+    interaction: {
+      location: "contextual_side_panel",
+      page: "workflow_details",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData, payload: { ...toSnakeCaseDeep(eventData as Record<string, any>) } } };
+
+  return event;
+};
+
+/**
+ * Fired when the user shares a deployment via the sharing popup on the workflow page
+ */
+export const deploymentSharedWorkflowSharingPopup = <T extends DefaultContext>(ctx: T) => (eventData: EventFunctionArgs<"deploymentSharedWorkflowSharingPopup">): AnalyticsEvent => {
+  const staticData = {
+    ...toSnakeCaseDeep(ctx),
+    unique_event_id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    event_name: "deployment_shared",
+    event_source: "cloudhome",
+    event_display_name: "Deployment Shared",
+    interaction: {
+      location: "module",
+      page: "workflow_details",
+      trigger: "user",
+      type: "click",
+    },
+  } satisfies SchemaStaticFields & GeneratedStaticFields;
+
+  const event = { id: staticData.event_name, data: { ...staticData, payload: { ...toSnakeCaseDeep(eventData as Record<string, any>) } } };
+
+  return event;
+};
+