@trakoo/emitkit 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 trakoo
+
+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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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,41 @@
+# @trakoo/emitkit
+
+EmitKit server provider for [trakoo](https://www.npmjs.com/package/trakoo), the typed, provider-agnostic analytics library.
+
+## Installation
+
+```bash
+pnpm add trakoo @trakoo/emitkit @emitkit/js@next
+```
+
+## Usage
+
+`appEvents` is your event registry, created with `defineEvents()` from `trakoo`.
+
+```typescript title="lib/server-analytics.ts"
+import { createServerAnalytics } from 'trakoo/server';
+import { EmitKitServerProvider } from '@trakoo/emitkit/server';
+import { appEvents } from './events';
+
+export const serverAnalytics = createServerAnalytics({
+  events: appEvents,
+  providers: [
+    new EmitKitServerProvider({
+      apiKey: process.env.EMITKIT_API_KEY!,
+      channelName: 'general',
+      categoryChannelMap: {
+        user: 'user-activity',
+        conversion: 'revenue'
+      }
+    })
+  ]
+});
+```
+
+EmitKit is server-only. To send browser events to it, forward them through trakoo's [Proxy provider](https://trakoo.co/docs/providers/proxy).
+
+The provider also sends page views, as silent events. EmitKit allows 100 requests per minute per API key by default, so if you only want explicit events in your feeds, register it as `{ provider: new EmitKitServerProvider({ ... }), exclude: ['pageView'] }`.
+
+## Documentation
+
+https://trakoo.co/docs/providers/emitkit

package/dist/server.d.ts

@@ -0,0 +1,104 @@
+import { BaseAnalyticsProvider, type BaseEvent, type EventContext } from "trakoo";
+/**
+ * Configuration for EmitKit server provider
+ */
+export interface EmitKitServerConfig {
+    /**
+     * Your EmitKit API key (starts with emitkit_)
+     */
+    apiKey: string;
+    /**
+     * Request timeout in milliseconds. A request that fails or times out is not
+     * retried.
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Default channel name for events
+     * @default 'general'
+     */
+    channelName?: string;
+    /**
+     * Map event categories to specific EmitKit channels.
+     * Allows automatic routing of events to appropriate channels based on category.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   'user': 'user-activity',
+     *   'engagement': 'product-usage',
+     *   'error': 'alerts',
+     *   'conversion': 'revenue'
+     * }
+     * ```
+     *
+     * Channel resolution priority:
+     * 1. Event property `__emitkit_channel` (highest priority)
+     * 2. Category mapping via `categoryChannelMap`
+     * 3. Default `channelName` (fallback, default: 'general')
+     */
+    categoryChannelMap?: Record<string, string>;
+    /**
+     * Send notification for events
+     * @default true
+     */
+    notify?: boolean;
+    /**
+     * Display style for events
+     * @default 'notification'
+     */
+    displayAs?: "message" | "notification";
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Enable/disable the provider
+     */
+    enabled?: boolean;
+}
+export declare class EmitKitServerProvider extends BaseAnalyticsProvider {
+    name: string;
+    private client?;
+    private initialized;
+    private config;
+    constructor(config: EmitKitServerConfig);
+    initialize(): Promise<void>;
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    track(event: BaseEvent, context?: EventContext): Promise<void>;
+    pageView(properties?: Record<string, unknown>, context?: EventContext): Promise<void>;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Request context attached to event metadata. EmitKit shows metadata in
+     * team feeds and notifications, so the visitor IP address (which proxy
+     * ingestion adds to `device`) is never forwarded.
+     */
+    private getContextMetadata;
+    /**
+     * Describe an SDK failure for logs. EmitKit errors add their error code,
+     * HTTP status, and request id, which tell auth, validation, and rate-limit
+     * failures apart; the message and response body are never logged.
+     */
+    private describeError;
+    /**
+     * Format event action into a human-readable title
+     * Converts: "user_signed_up" -> "User Signed Up"
+     */
+    private formatEventTitle;
+    /**
+     * Generate a description for the event
+     */
+    private getEventDescription;
+    /**
+     * Get an appropriate icon for the event category
+     */
+    private getEventIcon;
+    /**
+     * Resolve the channel name for an event based on priority:
+     * 1. Event property __emitkit_channel (highest priority)
+     * 2. Category mapping via categoryChannelMap
+     * 3. Default channelName (fallback, default: 'general')
+     */
+    private resolveChannelName;
+}

package/dist/server.js

@@ -0,0 +1,314 @@
+import { BaseAnalyticsProvider, } from "trakoo";
+const DEFAULT_TIMEOUT = 5000;
+/** Identifies trakoo as the sender of each event in EmitKit. */
+const EVENT_SOURCE = "trakoo";
+export class EmitKitServerProvider extends BaseAnalyticsProvider {
+    name = "EmitKit-Server";
+    client;
+    initialized = false;
+    config;
+    constructor(config) {
+        super({ debug: config.debug, enabled: config.enabled });
+        this.config = config;
+    }
+    async initialize() {
+        if (!this.isEnabled())
+            return;
+        if (this.initialized)
+            return;
+        // Validate config has required fields
+        if (!this.config.apiKey || typeof this.config.apiKey !== "string") {
+            throw new Error("EmitKit requires an apiKey");
+        }
+        if (!this.config.apiKey.startsWith("emitkit_")) {
+            console.warn("[EmitKit-Server] API key should start with 'emitkit_'. Double check your configuration.");
+        }
+        try {
+            // Dynamically import the EmitKit SDK
+            const { EmitKit } = await import("@emitkit/js");
+            this.client = new EmitKit({
+                apiKey: this.config.apiKey,
+                timeout: this.config.timeout ?? DEFAULT_TIMEOUT,
+                // The SDK's retries would hold a caller for several timeouts, so a
+                // failed request is reported once `timeout` has passed instead.
+                maxRetries: 0,
+            });
+            this.initialized = true;
+            this.log("Initialized successfully");
+        }
+        catch (error) {
+            console.error(`[EmitKit-Server] Failed to initialize (${this.getErrorClass(error)})`);
+            throw error;
+        }
+    }
+    async identify(userId, traits) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        // Extract email from traits; EmitKit rejects non-string aliases.
+        const email = typeof traits?.email === "string" && traits.email ? traits.email : userId;
+        // Build aliases array - EmitKit supports multiple identifiers
+        const aliases = [];
+        // Add userId as primary alias
+        if (userId) {
+            aliases.push(userId);
+        }
+        // Add email if different from userId
+        if (email && email !== userId) {
+            aliases.push(email);
+        }
+        // Add any custom alias fields from traits
+        if (traits?.username && typeof traits.username === "string") {
+            aliases.push(traits.username);
+        }
+        try {
+            await this.client.identify({
+                userId,
+                // EmitKit merges these into the stored properties.
+                ...(traits && { properties: asJsonObject(traits) }),
+                aliases: aliases.length > 0 ? aliases : undefined,
+            });
+            this.log("Identified user");
+        }
+        catch (error) {
+            console.error(`[EmitKit-Server] Failed to identify user (${this.describeError(error)})`);
+        }
+    }
+    async track(event, context) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        // Server providers use only identity supplied on the current call.
+        const userId = context?.user?.email || context?.user?.userId || event.userId;
+        // Generate event title from action (convert snake_case to Title Case)
+        const title = this.formatEventTitle(event.action);
+        // Build metadata from event properties and context
+        // Strip __emitkit_channel from properties as it's internal routing metadata
+        const { __emitkit_channel, ...cleanProperties } = event.properties || {};
+        const metadata = {
+            ...cleanProperties,
+            category: event.category,
+            timestamp: event.timestamp || Date.now(),
+            ...(event.sessionId && { sessionId: event.sessionId }),
+            ...this.getContextMetadata(context),
+        };
+        // Extract tags from category
+        const tags = [];
+        if (event.category) {
+            tags.push(event.category);
+        }
+        // Add any custom tags from properties
+        if (cleanProperties?.tags &&
+            Array.isArray(cleanProperties.tags) &&
+            cleanProperties.tags.every((t) => typeof t === "string")) {
+            tags.push(...cleanProperties.tags);
+        }
+        const uniqueTags = [...new Set(tags)];
+        // Determine channel name using resolution logic
+        const channelName = this.resolveChannelName(event);
+        try {
+            await this.client.events.create({
+                channelName,
+                title,
+                description: this.getEventDescription(event, context),
+                icon: this.getEventIcon(event.category),
+                tags: uniqueTags.length > 0 ? uniqueTags : undefined,
+                metadata: asJsonObject(metadata),
+                userId: userId || null,
+                notify: this.config.notify ?? true,
+                displayAs: this.config.displayAs || "notification",
+                source: EVENT_SOURCE,
+            });
+            this.log("Tracked event");
+        }
+        catch (error) {
+            console.error(`[EmitKit-Server] Failed to track event (${this.describeError(error)})`);
+            throw error;
+        }
+    }
+    async pageView(properties, context) {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        // Page views may only use identity supplied in the current context.
+        const userId = context?.user?.email || context?.user?.userId;
+        // Strip __emitkit_channel from properties if present
+        const { __emitkit_channel, ...cleanProperties } = properties || {};
+        // Build page view metadata
+        const metadata = {
+            ...cleanProperties,
+            date: new Date().toISOString(),
+            ...this.getContextMetadata(context),
+        };
+        // Create a synthetic event for channel resolution
+        // Page views use 'navigation' category
+        const syntheticEvent = {
+            action: "page_view",
+            category: "navigation",
+            properties: properties || {},
+        };
+        // Determine channel name using resolution logic
+        const channelName = this.resolveChannelName(syntheticEvent);
+        try {
+            await this.client.events.create({
+                channelName,
+                title: "Page View",
+                description: context?.page?.path || "User viewed a page",
+                icon: "👁️",
+                tags: ["page_view", "navigation"],
+                metadata: asJsonObject(metadata),
+                userId: userId || null,
+                notify: false, // Don't notify for page views by default
+                displayAs: "message",
+                source: EVENT_SOURCE,
+            });
+            this.log("Tracked page view");
+        }
+        catch (error) {
+            console.error(`[EmitKit-Server] Failed to track page view (${this.describeError(error)})`);
+        }
+    }
+    async reset() {
+        if (!this.isEnabled() || !this.initialized || !this.client)
+            return;
+        this.log("Reset called; server provider has no retained identity");
+    }
+    async shutdown() {
+        // EmitKit SDK doesn't require explicit shutdown
+        // Events are sent immediately (not batched)
+        this.client = undefined;
+        this.initialized = false;
+        this.log("Shutdown complete");
+    }
+    // ============================================================================
+    // Helper Methods
+    // ============================================================================
+    /**
+     * Request context attached to event metadata. EmitKit shows metadata in
+     * team feeds and notifications, so the visitor IP address (which proxy
+     * ingestion adds to `device`) is never forwarded.
+     */
+    getContextMetadata(context) {
+        const device = context?.device && withoutIp(context.device);
+        const server = context?.server && withoutIp(context.server);
+        return {
+            ...(context?.page && {
+                page: {
+                    url: context.page.url,
+                    host: context.page.host,
+                    path: context.page.path,
+                    title: context.page.title,
+                    protocol: context.page.protocol,
+                    referrer: context.page.referrer,
+                    ...(context.page.search && { search: context.page.search }),
+                },
+            }),
+            ...(device && Object.keys(device).length > 0 && { device }),
+            ...(context?.utm && { utm: context.utm }),
+            ...(server && Object.keys(server).length > 0 && { server }),
+        };
+    }
+    /**
+     * Describe an SDK failure for logs. EmitKit errors add their error code,
+     * HTTP status, and request id, which tell auth, validation, and rate-limit
+     * failures apart; the message and response body are never logged.
+     */
+    describeError(error) {
+        const errorClass = this.getErrorClass(error);
+        try {
+            if (!(error instanceof Error) || error.name !== "EmitKitError") {
+                return errorClass;
+            }
+            const code = Reflect.get(error, "code");
+            const status = Reflect.get(error, "status");
+            const requestId = Reflect.get(error, "requestId");
+            return [
+                error.name,
+                typeof code === "string" ? code : undefined,
+                // The SDK reports status 0 when no response arrived.
+                typeof status === "number" && status > 0 ? status : undefined,
+                typeof requestId === "string" ? `request ${requestId}` : undefined,
+            ]
+                .filter((part) => part !== undefined)
+                .join(" ");
+        }
+        catch {
+            // Error description must never replace the original failure.
+            return errorClass;
+        }
+    }
+    /**
+     * Format event action into a human-readable title
+     * Converts: "user_signed_up" -> "User Signed Up"
+     */
+    formatEventTitle(action) {
+        return action
+            .split("_")
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(" ");
+    }
+    /**
+     * Generate a description for the event
+     */
+    getEventDescription(event, context) {
+        // Use explicit description from properties if available
+        if (event.properties?.description &&
+            typeof event.properties.description === "string") {
+            return event.properties.description;
+        }
+        // Generate default description based on category
+        const categoryDescriptions = {
+            engagement: "User interaction event",
+            user: "User lifecycle event",
+            navigation: "Navigation event",
+            error: "Error or exception occurred",
+            performance: "Performance metric",
+            conversion: "Conversion event",
+        };
+        return categoryDescriptions[event.category] || undefined;
+    }
+    /**
+     * Get an appropriate icon for the event category
+     */
+    getEventIcon(category) {
+        const categoryIcons = {
+            engagement: "👆",
+            user: "👤",
+            navigation: "🧭",
+            error: "❌",
+            performance: "⚡",
+            conversion: "💰",
+        };
+        return categoryIcons[category];
+    }
+    /**
+     * Resolve the channel name for an event based on priority:
+     * 1. Event property __emitkit_channel (highest priority)
+     * 2. Category mapping via categoryChannelMap
+     * 3. Default channelName (fallback, default: 'general')
+     */
+    resolveChannelName(event, defaultChannel) {
+        // Priority 1: Check for explicit channel override in properties
+        if (event.properties?.__emitkit_channel &&
+            typeof event.properties.__emitkit_channel === "string") {
+            return event.properties.__emitkit_channel;
+        }
+        // Priority 2: Check category mapping
+        if (this.config.categoryChannelMap && event.category) {
+            const mappedChannel = this.config.categoryChannelMap[event.category];
+            if (mappedChannel) {
+                return mappedChannel;
+            }
+        }
+        // Priority 3: Use default channel
+        return defaultChannel || this.config.channelName || "general";
+    }
+}
+/**
+ * The SDK types metadata and properties as JSON values and serializes them
+ * with `JSON.stringify`, so trakoo's properties pass through unchanged.
+ */
+function asJsonObject(value) {
+    return value;
+}
+function withoutIp(block) {
+    const { ip: _ip, ...rest } = block;
+    return rest;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@trakoo/emitkit",
+  "version": "0.0.0",
+  "description": "EmitKit provider for trakoo",
+  "type": "module",
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "analytics",
+    "trakoo",
+    "emitkit",
+    "typescript"
+  ],
+  "author": "Chris Jayden <https://github.com/multiplehats>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/multiplehats/trakoo.git",
+    "directory": "packages/emitkit"
+  },
+  "bugs": {
+    "url": "https://github.com/multiplehats/trakoo/issues"
+  },
+  "homepage": "https://trakoo.co/docs/providers/emitkit",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@emitkit/js": "^3.0.0-next.0",
+    "trakoo": "^1.2.1"
+  },
+  "devDependencies": {
+    "@emitkit/js": "^3.0.0-next.0",
+    "trakoo": "1.2.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}