feat: analytics engine and providers

Author: twlite

.github/workflows/publish-dev.yaml

@@ -58,6 +58,7 @@ jobs:
             "@commandkit/i18n:packages/i18n"
             "@commandkit/devtools:packages/devtools"
             "@commandkit/cache:packages/cache"
+            "@commandkit/analytics:packages/analytics"
           )
 
           for entry in "${PACKAGES[@]}"; do
@@ -78,6 +79,7 @@ jobs:
             "@commandkit/i18n"
             "@commandkit/devtools"
             "@commandkit/cache"
+            "@commandkit/analytics"
           )
 
           for pkg in "${PACKAGES[@]}"; do

packages/analytics/README.md

@@ -0,0 +1,74 @@
+# `@commandkit/analytics`
+
+Analytics providers for CommandKit.
+
+## Installation
+
+```sh
+npm install @commandkit/analytics
+```
+
+## Usage
+
+This package provides a commandkit plugin that automatically registers the analytics provider with the commandkit instance.
+
+### PostHog
+
+```js
+import { posthog } from '@commandkit/analytics/posthog';
+
+export default defineConfig({
+  plugins: [
+    posthog({
+      posthogOptions: {
+        apiKey: 'YOUR_POSTHOG_API_KEY',
+        options?: PostHogOptions
+      }
+    })
+  ],
+});
+```
+
+### Umami
+
+```js
+import { umami } from '@commandkit/analytics/umami';
+
+export default defineConfig({
+  plugins: [
+    umami({
+      umamiOptions: {
+        hostUrl: 'YOUR_UMAMI_HOST_URL',
+        websiteId?: 'YOUR_UMAMI_WEBSITE_ID',
+        sessionId?: 'YOUR_UMAMI_SESSION_ID',
+        userAgent?: 'YOUR_UMAMI_USER_AGENT',
+      }
+    })
+  ],
+});
+```
+
+### Tracking events
+
+```js
+import { track } from 'commandkit/analytics';
+
+await track({
+  name: 'YOUR_EVENT_NAME',
+  id?: 'YOUR_UNIQUE_ID',
+  data: {...}
+});
+```
+
+### Disabling analytics per-request scope
+
+The `noAnalytics` function can be used to disable analytics for a specific request. This can be useful if you want to disable analytics for a specific user or guild, etc.
+
+```js
+import { noAnalytics } from 'commandkit/analytics';
+
+// call inside command or event or middlewares
+if (someCondition) {
+  noAnalytics();
+}
+```

packages/analytics/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@commandkit/analytics",
+  "version": "0.1.0",
+  "description": "Analytics providers for CommandKit",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./umami": {
+      "import": "./dist/umami/index.js",
+      "types": "./dist/umami/index.d.ts"
+    },
+    "./posthog": {
+      "import": "./dist/posthog/index.js",
+      "types": "./dist/posthog/index.d.ts"
+    }
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/underctrl-io/commandkit.git"
+  },
+  "keywords": [
+    "commandkit",
+    "analytics"
+  ],
+  "author": "twilight <[email protected]>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/underctrl-io/commandkit/issues"
+  },
+  "homepage": "https://github.com/underctrl-io/commandkit#readme",
+  "devDependencies": {
+    "@umami/node": "^0.4.0",
+    "commandkit": "workspace:*",
+    "posthog-node": "^4.18.0",
+    "tsconfig": "workspace:*",
+    "typescript": "^5.7.3"
+  }
+}

packages/analytics/src/posthog/index.ts

@@ -0,0 +1,8 @@
+import { PostHogPlugin, PostHogPluginOptions } from './plugin';
+
+export function posthog(options: PostHogPluginOptions) {
+  return new PostHogPlugin(options);
+}
+
+export * from './plugin';
+export * from './provider';

packages/analytics/src/posthog/plugin.ts

@@ -0,0 +1,35 @@
+import { CommandKitPluginRuntime, RuntimePlugin } from 'commandkit/plugin';
+import { PostHog, PostHogOptions } from 'posthog-node';
+import { PostHogProvider } from './provider';
+
+export interface PostHogPluginOptions {
+  posthogOptions: {
+    apiKey: string;
+    options?: PostHogOptions;
+  };
+}
+
+export class PostHogPlugin extends RuntimePlugin<PostHogPluginOptions> {
+  public readonly name = 'PostHog';
+
+  private provider: PostHogProvider | null = null;
+
+  public async activate(ctx: CommandKitPluginRuntime): Promise<void> {
+    const posthog = new PostHog(
+      this.options.posthogOptions.apiKey,
+      this.options.posthogOptions.options,
+    );
+
+    this.provider = new PostHogProvider(posthog);
+
+    ctx.commandkit.analytics.registerProvider(this.provider);
+  }
+
+  public async deactivate(ctx: CommandKitPluginRuntime): Promise<void> {
+    if (!this.provider) return;
+
+    await this.provider.posthog.shutdown();
+
+    ctx.commandkit.analytics.removeProvider(this.provider);
+  }
+}

packages/analytics/src/posthog/provider.ts

@@ -0,0 +1,40 @@
+import { PostHog } from 'posthog-node';
+import {
+  AnalyticsEngine,
+  AnalyticsEvent,
+  AnalyticsProvider,
+  IdentifyEvent,
+} from 'commandkit/analytics';
+
+export class PostHogProvider implements AnalyticsProvider {
+  public readonly name = 'PostHog';
+  public constructor(public readonly posthog: PostHog) {}
+
+  public async identify(
+    engine: AnalyticsEngine,
+    event: IdentifyEvent,
+  ): Promise<void> {
+    const client = engine.commandkit.client;
+
+    this.posthog.identify({
+      ...event,
+      distinctId: event.id ?? client.user?.id ?? 'commandkit',
+    });
+  }
+
+  public async track(
+    engine: AnalyticsEngine,
+    event: AnalyticsEvent,
+  ): Promise<void> {
+    const client = engine.commandkit.client;
+
+    this.posthog.capture({
+      distinctId:
+        'id' in event && typeof event.id === 'string'
+          ? event.id
+          : (client.user?.id ?? 'commandkit'),
+      event: event.name,
+      properties: event.data,
+    });
+  }
+}

packages/analytics/src/umami/index.ts

@@ -0,0 +1,8 @@
+import { UmamiPlugin, UmamiPluginOptions } from './plugin';
+
+export function umami(options: UmamiPluginOptions) {
+  return new UmamiPlugin(options);
+}
+
+export * from './plugin';
+export * from './provider';

packages/analytics/src/umami/plugin.ts

@@ -0,0 +1,26 @@
+import { UmamiOptions, Umami } from '@umami/node';
+import { CommandKitPluginRuntime, RuntimePlugin } from 'commandkit/plugin';
+import { UmamiProvider } from './provider';
+
+export interface UmamiPluginOptions {
+  umamiOptions: UmamiOptions;
+}
+
+export class UmamiPlugin extends RuntimePlugin<UmamiPluginOptions> {
+  public readonly name = 'Umami';
+
+  private provider: UmamiProvider | null = null;
+
+  public async activate(ctx: CommandKitPluginRuntime): Promise<void> {
+    const umami = new Umami(this.options.umamiOptions);
+
+    this.provider = new UmamiProvider(umami);
+
+    ctx.commandkit.analytics.registerProvider(this.provider);
+  }
+
+  public async deactivate(ctx: CommandKitPluginRuntime): Promise<void> {
+    if (!this.provider) return;
+    ctx.commandkit.analytics.removeProvider(this.provider);
+  }
+}

packages/analytics/src/umami/provider.ts

@@ -0,0 +1,28 @@
+import { Umami } from '@umami/node';
+import {
+  AnalyticsEngine,
+  AnalyticsEvent,
+  AnalyticsProvider,
+  IdentifyEvent,
+} from 'commandkit/analytics';
+
+export class UmamiProvider implements AnalyticsProvider {
+  public readonly name = 'Umami';
+  public constructor(public readonly umami: Umami) {}
+
+  public async identify(
+    engine: AnalyticsEngine,
+    event: IdentifyEvent,
+  ): Promise<void> {
+    void engine;
+    await this.umami.identify(event);
+  }
+
+  public async track(
+    engine: AnalyticsEngine,
+    event: AnalyticsEvent,
+  ): Promise<void> {
+    void engine;
+    await this.umami.track(event.name, event.data);
+  }
+}

packages/analytics/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "tsconfig/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "declaration": true,
+    "inlineSourceMap": true,
+    "target": "ES2020",
+    "module": "CommonJS",
+    "noEmit": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}