@ooneex/analytics 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ooneex
+
+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,420 @@
+# @ooneex/analytics
+
+A comprehensive TypeScript/JavaScript analytics library with PostHog integration for tracking user events and behavior. This package provides a clean, type-safe interface for capturing analytics events with support for user properties, groups, and custom event data.
+
+![Bun](https://img.shields.io/badge/Bun-Compatible-orange?style=flat-square&logo=bun)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)
+![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
+
+## Features
+
+✅ **PostHog Integration** - Seamless PostHog analytics integration
+
+✅ **Type-Safe** - Full TypeScript support with proper type definitions
+
+✅ **Environment Configuration** - Flexible API key and host configuration
+
+✅ **Event Tracking** - Track user events with custom properties and groups
+
+✅ **User Properties** - Attach custom properties to user events
+
+✅ **Group Analytics** - Support for group-based analytics tracking
+
+✅ **Error Handling** - Comprehensive error handling with custom exceptions
+
+✅ **Bun Runtime** - Optimized for Bun runtime environment
+
+✅ **Zero Config** - Works out of the box with environment variables
+
+## Installation
+
+### Bun
+```bash
+bun add @ooneex/analytics
+```
+
+## Setup
+
+### Environment Variables
+
+Set the following environment variables in your project:
+
+```bash
+# Required: Your PostHog API key
+ANALYTICS_POSTHOG_API_KEY=your_posthog_api_key_here
+
+# Optional: PostHog host (defaults to https://eu.i.posthog.com)
+ANALYTICS_POSTHOG_HOST=https://eu.i.posthog.com
+```
+
+### Configuration Options
+
+You can also configure the analytics adapter programmatically:
+
+```typescript
+import { PostHogAdapter } from '@ooneex/analytics';
+
+// Using constructor options (overrides environment variables)
+const analytics = new PostHogAdapter({
+  apiKey: 'your_api_key',
+  host: 'https://your-posthog-instance.com'
+});
+
+// Using environment variables only
+const analytics = new PostHogAdapter();
+```
+
+## Usage
+
+### Basic Event Tracking
+
+```typescript
+import { PostHogAdapter } from '@ooneex/analytics';
+
+const analytics = new PostHogAdapter();
+
+// Track a simple event
+analytics.capture({
+  id: 'user_123',
+  event: 'button_clicked',
+  properties: {
+    buttonId: 'signup-btn',
+    page: '/landing'
+  }
+});
+```
+
+### Advanced Event Tracking with Groups
+
+```typescript
+import { PostHogAdapter } from '@ooneex/analytics';
+
+const analytics = new PostHogAdapter();
+
+// Track event with user properties and groups
+analytics.capture({
+  id: 'user_123',
+  event: 'feature_used',
+  properties: {
+    feature: 'advanced_search',
+    sessionDuration: 1200,
+    actionsCount: 15,
+    source: 'web_app'
+  },
+  groups: {
+    company: 'acme_corp',
+    plan: 'enterprise'
+  }
+});
+```
+
+### E-commerce Tracking
+
+```typescript
+// Track purchase events
+analytics.capture({
+  id: 'user_123',
+  event: 'purchase_completed',
+  properties: {
+    orderId: 'order_456',
+    revenue: 99.99,
+    currency: 'USD',
+    products: ['product_1', 'product_2'],
+    paymentMethod: 'credit_card',
+    discount: 10.00
+  },
+  groups: {
+    store: 'online',
+    region: 'us_west'
+  }
+});
+```
+
+### User Signup Tracking
+
+```typescript
+// Track user registration
+analytics.capture({
+  id: 'user_123',
+  event: 'user_signup',
+  properties: {
+    email: 'user@example.com',
+    source: 'google_ads',
+    plan: 'free',
+    referrer: 'https://example.com'
+  },
+  groups: {
+    company: 'new_company'
+  }
+});
+```
+
+### Custom Implementation
+
+```typescript
+import { IAnalytics, PostHogAdapterCaptureType } from '@ooneex/analytics';
+
+class CustomAnalytics implements IAnalytics {
+  capture(options: PostHogAdapterCaptureType): void {
+    // Custom analytics implementation
+    console.log('Tracking event:', options.event, 'for user:', options.id);
+
+    // You can extend or modify the tracking logic here
+  }
+}
+```
+
+## API Reference
+
+### `PostHogAdapter` Class
+
+The main analytics adapter class that implements PostHog integration.
+
+#### Constructor
+
+```typescript
+new PostHogAdapter(options?: { apiKey?: string; host?: string })
+```
+
+**Parameters:**
+- `options.apiKey` - PostHog API key (optional, can use `ANALYTICS_POSTHOG_API_KEY` env var)
+- `options.host` - PostHog host URL (optional, defaults to `https://eu.i.posthog.com`)
+
+**Throws:** `AnalyticsException` if no API key is provided
+
+**Example:**
+```typescript
+// Using environment variables
+const analytics = new PostHogAdapter();
+
+// Using constructor options
+const analytics = new PostHogAdapter({
+  apiKey: 'phc_your_key_here',
+  host: 'https://app.posthog.com'
+});
+```
+
+#### Methods
+
+##### `capture(options: PostHogAdapterCaptureType): void`
+
+Captures an analytics event with user properties and groups.
+
+**Parameters:**
+- `options.id` - Unique user identifier (required)
+- `options.event` - Event name (required)
+- `options.properties` - Custom event properties (optional)
+- `options.groups` - Group associations (optional)
+
+**Example:**
+```typescript
+analytics.capture({
+  id: 'user_123',
+  event: 'page_viewed',
+  properties: {
+    page: '/dashboard',
+    loadTime: 1.2,
+    userAgent: 'Chrome/91.0'
+  },
+  groups: {
+    company: 'acme_corp',
+    team: 'marketing'
+  }
+});
+```
+
+### Types
+
+#### `IAnalytics`
+
+Interface defining the analytics contract.
+
+```typescript
+interface IAnalytics {
+  capture: (options: PostHogAdapterCaptureType) => void;
+}
+```
+
+#### `PostHogAdapterCaptureType`
+
+Type definition for capture event data.
+
+```typescript
+type PostHogAdapterCaptureType = {
+  id: string;                              // User identifier
+  event: string;                           // Event name
+  properties?: Record<string, unknown>;    // Custom properties
+  groups?: Record<string, string | number>; // Group associations
+};
+```
+
+### Error Handling
+
+#### `AnalyticsException`
+
+Custom exception class for analytics-related errors.
+
+```typescript
+import { AnalyticsException } from '@ooneex/analytics';
+
+try {
+  const analytics = new PostHogAdapter(); // Missing API key
+} catch (error) {
+  if (error instanceof AnalyticsException) {
+    console.error('Analytics Error:', error.message);
+    // Handle analytics-specific error
+  }
+}
+```
+
+**Common Error Scenarios:**
+- Missing PostHog API key
+- Invalid configuration options
+- Network connectivity issues
+
+## Environment Setup
+
+### Required Environment Variables
+
+```bash
+# PostHog API Key (required)
+ANALYTICS_POSTHOG_API_KEY=phc_your_api_key_here
+```
+
+### Optional Environment Variables
+
+```bash
+# PostHog Host (optional, defaults to EU instance)
+ANALYTICS_POSTHOG_HOST=https://app.posthog.com
+
+# For US instance
+ANALYTICS_POSTHOG_HOST=https://us.i.posthog.com
+
+# For self-hosted instance
+ANALYTICS_POSTHOG_HOST=https://your-posthog-instance.com
+```
+
+## Best Practices
+
+### Event Naming
+
+Use consistent, descriptive event names:
+
+```typescript
+// ✅ Good
+analytics.capture({
+  id: 'user_123',
+  event: 'button_clicked',
+  properties: { button: 'signup' }
+});
+
+// ❌ Avoid
+analytics.capture({
+  id: 'user_123',
+  event: 'click',
+  properties: { what: 'something' }
+});
+```
+
+### Property Structure
+
+Keep properties flat and meaningful:
+
+```typescript
+// ✅ Good
+analytics.capture({
+  id: 'user_123',
+  event: 'purchase_completed',
+  properties: {
+    orderId: 'order_456',
+    revenue: 99.99,
+    currency: 'USD',
+    itemCount: 3
+  }
+});
+
+// ❌ Avoid deeply nested objects
+analytics.capture({
+  id: 'user_123',
+  event: 'purchase_completed',
+  properties: {
+    order: {
+      details: {
+        nested: {
+          data: 'value'
+        }
+      }
+    }
+  }
+});
+```
+
+### Error Handling
+
+Always handle potential configuration errors:
+
+```typescript
+import { PostHogAdapter, AnalyticsException } from '@ooneex/analytics';
+
+try {
+  const analytics = new PostHogAdapter();
+
+  analytics.capture({
+    id: 'user_123',
+    event: 'app_started'
+  });
+} catch (error) {
+  if (error instanceof AnalyticsException) {
+    console.error('Analytics configuration error:', error.message);
+    // Fallback analytics or silent failure
+  }
+}
+```
+
+## Runtime Support
+
+This package is optimized for **Bun runtime only**. It leverages Bun-specific features and environment variable access patterns.
+
+### Bun Environment
+
+```typescript
+// Automatic environment variable access
+const analytics = new PostHogAdapter(); // Uses Bun.env.ANALYTICS_POSTHOG_API_KEY
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `bun install`
+3. Run tests: `bun run test`
+4. Build the project: `bun run build`
+
+### Guidelines
+
+- Write tests for new features
+- Follow the existing code style
+- Update documentation for API changes
+- Ensure all tests pass before submitting PR
+- Test with Bun runtime environment
+
+### Running Tests
+
+```bash
+# Run all tests
+bun run test
+
+# Run tests in watch mode
+bun run test:watch
+```
+
+---
+
+Made with ❤️ by the Ooneex team

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { Exception } from "@ooneex/exception";
+declare class AnalyticsException extends Exception {
+	constructor(message: string, data?: Record<string, unknown>);
+}
+type AnalyticsClassType = new (...args: any[]) => IAnalytics;
+interface IAnalytics {
+	capture: (options: PostHogAdapterCaptureType) => void;
+}
+type PostHogAdapterCaptureType = {
+	id: string;
+	event: string;
+	properties?: Record<string, unknown>;
+	groups?: Record<string, string | number>;
+};
+declare class PostHogAdapter implements IAnalytics {
+	private client;
+	constructor(options?: {
+		apiKey?: string;
+		host?: string;
+	});
+	capture<T extends PostHogAdapterCaptureType>(options: T): void;
+}
+export { PostHogAdapterCaptureType, PostHogAdapter, IAnalytics, AnalyticsException, AnalyticsClassType };

package/dist/index.js

@@ -0,0 +1,4 @@
+// @bun
+import{Exception as o}from"@ooneex/exception";import{HttpStatus as s}from"@ooneex/http-status";class r extends o{constructor(t,e={}){super(t,{status:s.Code.InternalServerError,data:e});this.name="AnalyticsException"}}import{PostHog as i}from"posthog-node";class n{client=null;constructor(t){let e=t?.apiKey||Bun.env.ANALYTICS_POSTHOG_API_KEY;if(!e)throw new r("PostHog API key is required. Please provide an API key either through the constructor options or set the ANALYTICS_POSTHOG_API_KEY environment variable.");if(t?.apiKey)this.client=new i(e,{host:t.host||Bun.env.ANALYTICS_POSTHOG_HOST||"https://eu.i.posthog.com"})}capture(t){this.client?.capture({distinctId:t.id,event:t.event,properties:{$set:t.properties},timestamp:new Date,...t.groups&&{groups:t.groups}}),this.client?.shutdown()}}export{n as PostHogAdapter,r as AnalyticsException};
+
+//# debugId=D94B37C63C67FF1064756E2164756E21

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["src/AnalyticsException.ts", "src/PostHogAdapter.ts"],
+  "sourcesContent": [
+    "import { Exception } from \"@ooneex/exception\";\nimport { HttpStatus } from \"@ooneex/http-status\";\n\nexport class AnalyticsException extends Exception {\n  constructor(message: string, data: Record<string, unknown> = {}) {\n    super(message, {\n      status: HttpStatus.Code.InternalServerError,\n      data,\n    });\n\n    this.name = \"AnalyticsException\";\n  }\n}\n",
+    "import { PostHog } from \"posthog-node\";\nimport { AnalyticsException } from \"./AnalyticsException\";\nimport type { IAnalytics, PostHogAdapterCaptureType } from \"./types\";\n\nexport class PostHogAdapter implements IAnalytics {\n  private client: PostHog | null = null;\n\n  constructor(options?: { apiKey?: string; host?: string }) {\n    const apiKey = options?.apiKey || Bun.env.ANALYTICS_POSTHOG_API_KEY;\n\n    if (!apiKey) {\n      throw new AnalyticsException(\n        \"PostHog API key is required. Please provide an API key either through the constructor options or set the ANALYTICS_POSTHOG_API_KEY environment variable.\",\n      );\n    }\n\n    if (options?.apiKey) {\n      this.client = new PostHog(apiKey, {\n        host: options.host || Bun.env.ANALYTICS_POSTHOG_HOST || \"https://eu.i.posthog.com\",\n      });\n    }\n  }\n\n  public capture<T extends PostHogAdapterCaptureType>(options: T): void {\n    this.client?.capture({\n      distinctId: options.id,\n      event: options.event,\n      properties: {\n        $set: options.properties,\n      },\n      timestamp: new Date(),\n      ...(options.groups && { groups: options.groups }),\n    });\n    this.client?.shutdown();\n  }\n}\n"
+  ],
+  "mappings": ";AAAA,oBAAS,0BACT,qBAAS,4BAEF,MAAM,UAA2B,CAAU,CAChD,WAAW,CAAC,EAAiB,EAAgC,CAAC,EAAG,CAC/D,MAAM,EAAS,CACb,OAAQ,EAAW,KAAK,oBACxB,MACF,CAAC,EAED,KAAK,KAAO,qBAEhB,CCZA,kBAAS,qBAIF,MAAM,CAAqC,CACxC,OAAyB,KAEjC,WAAW,CAAC,EAA8C,CACxD,IAAM,EAAS,GAAS,QAAU,IAAI,IAAI,0BAE1C,GAAI,CAAC,EACH,MAAM,IAAI,EACR,0JACF,EAGF,GAAI,GAAS,OACX,KAAK,OAAS,IAAI,EAAQ,EAAQ,CAChC,KAAM,EAAQ,MAAQ,IAAI,IAAI,wBAA0B,0BAC1D,CAAC,EAIE,OAA4C,CAAC,EAAkB,CACpE,KAAK,QAAQ,QAAQ,CACnB,WAAY,EAAQ,GACpB,MAAO,EAAQ,MACf,WAAY,CACV,KAAM,EAAQ,UAChB,EACA,UAAW,IAAI,QACX,EAAQ,QAAU,CAAE,OAAQ,EAAQ,MAAO,CACjD,CAAC,EACD,KAAK,QAAQ,SAAS,EAE1B",
+  "debugId": "D94B37C63C67FF1064756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ooneex/analytics",
+  "description": "",
+  "version": "0.0.1",
+  "type": "module",
+  "private": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test tests",
+    "build": "bunup",
+    "lint": "tsgo --noEmit && bunx biome lint",
+    "publish:prod": "bun publish --access public",
+    "publish:pack": "bun pm pack --destination ./dist",
+    "publish:dry": "bun publish --dry-run"
+  },
+  "devDependencies": {},
+  "peerDependencies": {},
+  "dependencies": {
+    "@ooneex/exception": "0.0.1",
+    "@ooneex/http-status": "0.0.1",
+    "posthog-node": "^5.11.0"
+  }
+}