@commandkit/analytics 0.1.0-dev.20250605135449

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2025 Avraj Sahota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/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();
+}
+```

package/dist/posthog/index.d.ts

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

package/dist/posthog/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.posthog = posthog;
+const plugin_1 = require("./plugin");
+function posthog(options) {
+    return new plugin_1.PostHogPlugin(options);
+}
+__exportStar(require("./plugin"), exports);
+__exportStar(require("./provider"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcG9zdGhvZy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7O0FBRUEsMEJBRUM7QUFKRCxxQ0FBK0Q7QUFFL0QsU0FBZ0IsT0FBTyxDQUFDLE9BQTZCO0lBQ25ELE9BQU8sSUFBSSxzQkFBYSxDQUFDLE9BQU8sQ0FBQyxDQUFDO0FBQ3BDLENBQUM7QUFFRCwyQ0FBeUI7QUFDekIsNkNBQTJCIn0=

package/dist/posthog/plugin.d.ts

@@ -0,0 +1,14 @@
+import { CommandKitPluginRuntime, RuntimePlugin } from 'commandkit/plugin';
+import { PostHogOptions } from 'posthog-node';
+export interface PostHogPluginOptions {
+    posthogOptions: {
+        apiKey: string;
+        options?: PostHogOptions;
+    };
+}
+export declare class PostHogPlugin extends RuntimePlugin<PostHogPluginOptions> {
+    readonly name = "PostHog";
+    private provider;
+    activate(ctx: CommandKitPluginRuntime): Promise<void>;
+    deactivate(ctx: CommandKitPluginRuntime): Promise<void>;
+}

package/dist/posthog/plugin.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostHogPlugin = void 0;
+const plugin_1 = require("commandkit/plugin");
+const posthog_node_1 = require("posthog-node");
+const provider_1 = require("./provider");
+class PostHogPlugin extends plugin_1.RuntimePlugin {
+    constructor() {
+        super(...arguments);
+        this.name = 'PostHog';
+        this.provider = null;
+    }
+    async activate(ctx) {
+        const posthog = new posthog_node_1.PostHog(this.options.posthogOptions.apiKey, this.options.posthogOptions.options);
+        this.provider = new provider_1.PostHogProvider(posthog);
+        ctx.commandkit.analytics.registerProvider(this.provider);
+    }
+    async deactivate(ctx) {
+        if (!this.provider)
+            return;
+        await this.provider.posthog.shutdown();
+        ctx.commandkit.analytics.removeProvider(this.provider);
+    }
+}
+exports.PostHogPlugin = PostHogPlugin;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2luLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3Bvc3Rob2cvcGx1Z2luLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLDhDQUEyRTtBQUMzRSwrQ0FBdUQ7QUFDdkQseUNBQTZDO0FBUzdDLE1BQWEsYUFBYyxTQUFRLHNCQUFtQztJQUF0RTs7UUFDa0IsU0FBSSxHQUFHLFNBQVMsQ0FBQztRQUV6QixhQUFRLEdBQTJCLElBQUksQ0FBQztJQW9CbEQsQ0FBQztJQWxCUSxLQUFLLENBQUMsUUFBUSxDQUFDLEdBQTRCO1FBQ2hELE1BQU0sT0FBTyxHQUFHLElBQUksc0JBQU8sQ0FDekIsSUFBSSxDQUFDLE9BQU8sQ0FBQyxjQUFjLENBQUMsTUFBTSxFQUNsQyxJQUFJLENBQUMsT0FBTyxDQUFDLGNBQWMsQ0FBQyxPQUFPLENBQ3BDLENBQUM7UUFFRixJQUFJLENBQUMsUUFBUSxHQUFHLElBQUksMEJBQWUsQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUU3QyxHQUFHLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxnQkFBZ0IsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUM7SUFDM0QsQ0FBQztJQUVNLEtBQUssQ0FBQyxVQUFVLENBQUMsR0FBNEI7UUFDbEQsSUFBSSxDQUFDLElBQUksQ0FBQyxRQUFRO1lBQUUsT0FBTztRQUUzQixNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsT0FBTyxDQUFDLFFBQVEsRUFBRSxDQUFDO1FBRXZDLEdBQUcsQ0FBQyxVQUFVLENBQUMsU0FBUyxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUM7SUFDekQsQ0FBQztDQUNGO0FBdkJELHNDQXVCQyJ9

package/dist/posthog/provider.d.ts

@@ -0,0 +1,9 @@
+import { PostHog } from 'posthog-node';
+import { AnalyticsEngine, AnalyticsEvent, AnalyticsProvider, IdentifyEvent } from 'commandkit/analytics';
+export declare class PostHogProvider implements AnalyticsProvider {
+    readonly posthog: PostHog;
+    readonly name = "PostHog";
+    constructor(posthog: PostHog);
+    identify(engine: AnalyticsEngine, event: IdentifyEvent): Promise<void>;
+    track(engine: AnalyticsEngine, event: AnalyticsEvent): Promise<void>;
+}

package/dist/posthog/provider.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostHogProvider = void 0;
+class PostHogProvider {
+    constructor(posthog) {
+        this.posthog = posthog;
+        this.name = 'PostHog';
+    }
+    async identify(engine, event) {
+        const client = engine.commandkit.client;
+        this.posthog.identify({
+            ...event,
+            distinctId: event.id ?? client.user?.id ?? 'commandkit',
+        });
+    }
+    async track(engine, event) {
+        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,
+        });
+    }
+}
+exports.PostHogProvider = PostHogProvider;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJvdmlkZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcG9zdGhvZy9wcm92aWRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFRQSxNQUFhLGVBQWU7SUFFMUIsWUFBbUMsT0FBZ0I7UUFBaEIsWUFBTyxHQUFQLE9BQU8sQ0FBUztRQURuQyxTQUFJLEdBQUcsU0FBUyxDQUFDO0lBQ3FCLENBQUM7SUFFaEQsS0FBSyxDQUFDLFFBQVEsQ0FDbkIsTUFBdUIsRUFDdkIsS0FBb0I7UUFFcEIsTUFBTSxNQUFNLEdBQUcsTUFBTSxDQUFDLFVBQVUsQ0FBQyxNQUFNLENBQUM7UUFFeEMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUM7WUFDcEIsR0FBRyxLQUFLO1lBQ1IsVUFBVSxFQUFFLEtBQUssQ0FBQyxFQUFFLElBQUksTUFBTSxDQUFDLElBQUksRUFBRSxFQUFFLElBQUksWUFBWTtTQUN4RCxDQUFDLENBQUM7SUFDTCxDQUFDO0lBRU0sS0FBSyxDQUFDLEtBQUssQ0FDaEIsTUFBdUIsRUFDdkIsS0FBcUI7UUFFckIsTUFBTSxNQUFNLEdBQUcsTUFBTSxDQUFDLFVBQVUsQ0FBQyxNQUFNLENBQUM7UUFFeEMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUM7WUFDbkIsVUFBVSxFQUNSLElBQUksSUFBSSxLQUFLLElBQUksT0FBTyxLQUFLLENBQUMsRUFBRSxLQUFLLFFBQVE7Z0JBQzNDLENBQUMsQ0FBQyxLQUFLLENBQUMsRUFBRTtnQkFDVixDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUMsSUFBSSxFQUFFLEVBQUUsSUFBSSxZQUFZLENBQUM7WUFDdkMsS0FBSyxFQUFFLEtBQUssQ0FBQyxJQUFJO1lBQ2pCLFVBQVUsRUFBRSxLQUFLLENBQUMsSUFBSTtTQUN2QixDQUFDLENBQUM7SUFDTCxDQUFDO0NBQ0Y7QUEvQkQsMENBK0JDIn0=

package/dist/umami/index.d.ts

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

package/dist/umami/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.umami = umami;
+const plugin_1 = require("./plugin");
+function umami(options) {
+    return new plugin_1.UmamiPlugin(options);
+}
+__exportStar(require("./plugin"), exports);
+__exportStar(require("./provider"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdW1hbWkvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUVBLHNCQUVDO0FBSkQscUNBQTJEO0FBRTNELFNBQWdCLEtBQUssQ0FBQyxPQUEyQjtJQUMvQyxPQUFPLElBQUksb0JBQVcsQ0FBQyxPQUFPLENBQUMsQ0FBQztBQUNsQyxDQUFDO0FBRUQsMkNBQXlCO0FBQ3pCLDZDQUEyQiJ9

package/dist/umami/plugin.d.ts

@@ -0,0 +1,11 @@
+import { UmamiOptions } from '@umami/node';
+import { CommandKitPluginRuntime, RuntimePlugin } from 'commandkit/plugin';
+export interface UmamiPluginOptions {
+    umamiOptions: UmamiOptions;
+}
+export declare class UmamiPlugin extends RuntimePlugin<UmamiPluginOptions> {
+    readonly name = "Umami";
+    private provider;
+    activate(ctx: CommandKitPluginRuntime): Promise<void>;
+    deactivate(ctx: CommandKitPluginRuntime): Promise<void>;
+}

package/dist/umami/plugin.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UmamiPlugin = void 0;
+const node_1 = require("@umami/node");
+const plugin_1 = require("commandkit/plugin");
+const provider_1 = require("./provider");
+class UmamiPlugin extends plugin_1.RuntimePlugin {
+    constructor() {
+        super(...arguments);
+        this.name = 'Umami';
+        this.provider = null;
+    }
+    async activate(ctx) {
+        const umami = new node_1.Umami(this.options.umamiOptions);
+        this.provider = new provider_1.UmamiProvider(umami);
+        ctx.commandkit.analytics.registerProvider(this.provider);
+    }
+    async deactivate(ctx) {
+        if (!this.provider)
+            return;
+        ctx.commandkit.analytics.removeProvider(this.provider);
+    }
+}
+exports.UmamiPlugin = UmamiPlugin;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2luLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3VtYW1pL3BsdWdpbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSxzQ0FBa0Q7QUFDbEQsOENBQTJFO0FBQzNFLHlDQUEyQztBQU0zQyxNQUFhLFdBQVksU0FBUSxzQkFBaUM7SUFBbEU7O1FBQ2tCLFNBQUksR0FBRyxPQUFPLENBQUM7UUFFdkIsYUFBUSxHQUF5QixJQUFJLENBQUM7SUFjaEQsQ0FBQztJQVpRLEtBQUssQ0FBQyxRQUFRLENBQUMsR0FBNEI7UUFDaEQsTUFBTSxLQUFLLEdBQUcsSUFBSSxZQUFLLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxZQUFZLENBQUMsQ0FBQztRQUVuRCxJQUFJLENBQUMsUUFBUSxHQUFHLElBQUksd0JBQWEsQ0FBQyxLQUFLLENBQUMsQ0FBQztRQUV6QyxHQUFHLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxnQkFBZ0IsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUM7SUFDM0QsQ0FBQztJQUVNLEtBQUssQ0FBQyxVQUFVLENBQUMsR0FBNEI7UUFDbEQsSUFBSSxDQUFDLElBQUksQ0FBQyxRQUFRO1lBQUUsT0FBTztRQUMzQixHQUFHLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxjQUFjLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxDQUFDO0lBQ3pELENBQUM7Q0FDRjtBQWpCRCxrQ0FpQkMifQ==

package/dist/umami/provider.d.ts

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

package/dist/umami/provider.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UmamiProvider = void 0;
+class UmamiProvider {
+    constructor(umami) {
+        this.umami = umami;
+        this.name = 'Umami';
+    }
+    async identify(engine, event) {
+        void engine;
+        await this.umami.identify(event);
+    }
+    async track(engine, event) {
+        void engine;
+        await this.umami.track(event.name, event.data);
+    }
+}
+exports.UmamiProvider = UmamiProvider;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJvdmlkZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdW1hbWkvcHJvdmlkZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBUUEsTUFBYSxhQUFhO0lBRXhCLFlBQW1DLEtBQVk7UUFBWixVQUFLLEdBQUwsS0FBSyxDQUFPO1FBRC9CLFNBQUksR0FBRyxPQUFPLENBQUM7SUFDbUIsQ0FBQztJQUU1QyxLQUFLLENBQUMsUUFBUSxDQUNuQixNQUF1QixFQUN2QixLQUFvQjtRQUVwQixLQUFLLE1BQU0sQ0FBQztRQUNaLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLENBQUM7SUFDbkMsQ0FBQztJQUVNLEtBQUssQ0FBQyxLQUFLLENBQ2hCLE1BQXVCLEVBQ3ZCLEtBQXFCO1FBRXJCLEtBQUssTUFBTSxDQUFDO1FBQ1osTUFBTSxJQUFJLENBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQUMsSUFBSSxFQUFFLEtBQUssQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUNqRCxDQUFDO0NBQ0Y7QUFuQkQsc0NBbUJDIn0=

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@commandkit/analytics",
+  "version": "0.1.0-dev.20250605135449",
+  "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"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/underctrl-io/commandkit.git"
+  },
+  "keywords": [
+    "commandkit",
+    "analytics"
+  ],
+  "author": "twilight <hello@twlite.dev>",
+  "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",
+    "posthog-node": "^4.18.0",
+    "typescript": "^5.7.3",
+    "commandkit": "1.0.0-dev.20250605135449",
+    "tsconfig": "0.0.0-dev.20250605135449"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc"
+  }
+}