@flightdev/analytics 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+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,363 @@
+# @flight-framework/analytics
+
+Privacy-focused, universal analytics for Flight Framework. Works with any analytics provider through adapters.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Adapters](#adapters)
+- [Core API](#core-api)
+- [React Integration](#react-integration)
+- [Server-Side Tracking](#server-side-tracking)
+- [Privacy and Consent](#privacy-and-consent)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Features
+
+- Single API for multiple analytics providers
+- Privacy-first design with consent management
+- Automatic page view tracking
+- Server-side event tracking
+- Type-safe event definitions
+- Batching and retry logic
+- React hooks for easy integration
+- GDPR/CCPA compliant consent handling
+
+---
+
+## Installation
+
+```bash
+npm install @flight-framework/analytics
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { createAnalytics } from '@flight-framework/analytics';
+import { plausible } from '@flight-framework/analytics/plausible';
+
+const analytics = createAnalytics(plausible({
+    domain: 'example.com',
+}));
+
+// Track page view
+analytics.trackPageview('/about');
+
+// Track custom event
+analytics.trackEvent('signup', { plan: 'pro', source: 'landing' });
+
+// Identify user (for providers that support it)
+analytics.identify('user_123', { email: 'user@example.com' });
+```
+
+---
+
+## Adapters
+
+### Plausible (Privacy-Focused)
+
+Simple, privacy-friendly analytics without cookies.
+
+```typescript
+import { plausible } from '@flight-framework/analytics/plausible';
+
+const adapter = plausible({
+    domain: 'example.com',
+    apiHost: 'https://plausible.io',  // Or self-hosted
+    hashMode: false,                   // Hash-based routing
+});
+```
+
+### PostHog (Product Analytics)
+
+Full-featured product analytics with session recording.
+
+```typescript
+import { posthog } from '@flight-framework/analytics/posthog';
+
+const adapter = posthog({
+    apiKey: process.env.POSTHOG_API_KEY,
+    host: 'https://app.posthog.com',  // Or self-hosted
+    autocapture: true,
+    sessionRecording: true,
+});
+```
+
+### Google Analytics 4
+
+```typescript
+import { ga4 } from '@flight-framework/analytics/ga4';
+
+const adapter = ga4({
+    measurementId: 'G-XXXXXXXXXX',
+    debug: process.env.NODE_ENV === 'development',
+});
+```
+
+### Mixpanel
+
+```typescript
+import { mixpanel } from '@flight-framework/analytics/mixpanel';
+
+const adapter = mixpanel({
+    token: process.env.MIXPANEL_TOKEN,
+    debug: false,
+});
+```
+
+### Amplitude
+
+```typescript
+import { amplitude } from '@flight-framework/analytics/amplitude';
+
+const adapter = amplitude({
+    apiKey: process.env.AMPLITUDE_API_KEY,
+    serverZone: 'US',  // or 'EU'
+});
+```
+
+### Multiple Providers
+
+Send events to multiple providers simultaneously:
+
+```typescript
+import { multi } from '@flight-framework/analytics/multi';
+
+const analytics = createAnalytics(multi([
+    plausible({ domain: 'example.com' }),
+    posthog({ apiKey: '...' }),
+]));
+```
+
+---
+
+## Core API
+
+### trackPageview(path, properties?)
+
+Track a page view:
+
+```typescript
+analytics.trackPageview('/products/widget');
+
+// With additional properties
+analytics.trackPageview('/products/widget', {
+    referrer: document.referrer,
+    title: document.title,
+});
+```
+
+### trackEvent(name, properties?)
+
+Track a custom event:
+
+```typescript
+// Simple event
+analytics.trackEvent('button_click');
+
+// With properties
+analytics.trackEvent('purchase', {
+    product_id: 'prod_123',
+    price: 49.99,
+    currency: 'USD',
+});
+```
+
+### identify(userId, traits?)
+
+Identify a user for user-level analytics:
+
+```typescript
+analytics.identify('user_123', {
+    email: 'user@example.com',
+    plan: 'pro',
+    company: 'Acme Inc',
+    signupDate: new Date(),
+});
+```
+
+### reset()
+
+Clear user identity (on logout):
+
+```typescript
+analytics.reset();
+```
+
+---
+
+## React Integration
+
+### AnalyticsProvider
+
+Wrap your app with the provider:
+
+```tsx
+import { AnalyticsProvider } from '@flight-framework/analytics/react';
+
+function App() {
+    return (
+        <AnalyticsProvider client={analytics}>
+            <Routes />
+        </AnalyticsProvider>
+    );
+}
+```
+
+### useAnalytics Hook
+
+```tsx
+import { useAnalytics } from '@flight-framework/analytics/react';
+
+function SignupButton() {
+    const { trackEvent } = useAnalytics();
+    
+    return (
+        <button onClick={() => trackEvent('signup_click', { location: 'header' })}>
+            Sign Up
+        </button>
+    );
+}
+```
+
+### usePageview Hook
+
+Automatic page view tracking:
+
+```tsx
+import { usePageview } from '@flight-framework/analytics/react';
+
+function Page() {
+    usePageview();  // Tracks on mount and route changes
+    
+    return <div>...</div>;
+}
+```
+
+### TrackEvent Component
+
+Declarative event tracking:
+
+```tsx
+import { TrackEvent } from '@flight-framework/analytics/react';
+
+function PricingPage() {
+    return (
+        <>
+            <TrackEvent name="pricing_view" properties={{ variant: 'A' }} />
+            <h1>Pricing</h1>
+        </>
+    );
+}
+```
+
+---
+
+## Server-Side Tracking
+
+Track events from your server or API routes:
+
+```typescript
+import { createServerAnalytics } from '@flight-framework/analytics/server';
+
+const serverAnalytics = createServerAnalytics(posthog({
+    apiKey: process.env.POSTHOG_API_KEY,
+}));
+
+// In your API handler
+export async function POST(request: Request) {
+    const { userId, action } = await request.json();
+    
+    await serverAnalytics.trackEvent('api_action', {
+        action,
+        userId,
+        ip: request.headers.get('x-forwarded-for'),
+    });
+    
+    return Response.json({ success: true });
+}
+```
+
+---
+
+## Privacy and Consent
+
+### Consent Management
+
+```typescript
+const analytics = createAnalytics(adapter, {
+    consent: {
+        required: true,      // Wait for consent before tracking
+        cookieName: 'consent',
+        defaultValue: false,
+    },
+});
+
+// User gives consent
+analytics.setConsent(true);
+
+// Check consent status
+if (analytics.hasConsent()) {
+    // Track
+}
+```
+
+### React Consent Hook
+
+```tsx
+import { useConsent } from '@flight-framework/analytics/react';
+
+function CookieBanner() {
+    const { hasConsent, setConsent } = useConsent();
+    
+    if (hasConsent) return null;
+    
+    return (
+        <div className="cookie-banner">
+            <p>We use analytics to improve our site.</p>
+            <button onClick={() => setConsent(true)}>Accept</button>
+            <button onClick={() => setConsent(false)}>Decline</button>
+        </div>
+    );
+}
+```
+
+---
+
+## API Reference
+
+### createAnalytics Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean` | `false` | Log events to console |
+| `disabled` | `boolean` | `false` | Disable all tracking |
+| `consent.required` | `boolean` | `false` | Require consent before tracking |
+| `batch.enabled` | `boolean` | `true` | Batch events |
+| `batch.size` | `number` | `10` | Max events per batch |
+| `batch.timeout` | `number` | `5000` | Flush timeout in ms |
+
+### Analytics Methods
+
+| Method | Description |
+|--------|-------------|
+| `trackPageview(path, props?)` | Track page view |
+| `trackEvent(name, props?)` | Track custom event |
+| `identify(userId, traits?)` | Identify user |
+| `reset()` | Clear user identity |
+| `setConsent(value)` | Update consent |
+| `hasConsent()` | Check consent status |
+
+---
+
+## License
+
+MIT

package/dist/adapters/plausible.d.ts

@@ -0,0 +1,13 @@
+import { AnalyticsAdapterFactory } from '../index.js';
+
+/**
+ * Plausible Analytics Adapter
+ */
+
+interface PlausibleConfig {
+    domain: string;
+    apiHost?: string;
+}
+declare const plausible: AnalyticsAdapterFactory<PlausibleConfig>;
+
+export { type PlausibleConfig, plausible as default, plausible };

package/dist/adapters/plausible.js

@@ -0,0 +1,36 @@
+// src/adapters/plausible.ts
+var plausible = (config) => {
+  const { domain, apiHost = "https://plausible.io" } = config;
+  async function send(eventName, props) {
+    try {
+      await fetch(`${apiHost}/api/event`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          domain,
+          name: eventName,
+          url: typeof window !== "undefined" ? window.location.href : "",
+          referrer: typeof document !== "undefined" ? document.referrer : "",
+          screen_width: typeof window !== "undefined" ? window.innerWidth : void 0,
+          props
+        })
+      });
+    } catch {
+    }
+  }
+  const adapter = {
+    name: "plausible",
+    trackPageview(_data) {
+      send("pageview");
+    },
+    trackEvent(data) {
+      send(data.name, data.props);
+    }
+  };
+  return adapter;
+};
+var plausible_default = plausible;
+export {
+  plausible_default as default,
+  plausible
+};

package/dist/adapters/posthog.d.ts

@@ -0,0 +1,13 @@
+import { AnalyticsAdapterFactory } from '../index.js';
+
+/**
+ * PostHog Analytics Adapter
+ */
+
+interface PostHogConfig {
+    apiKey: string;
+    apiHost?: string;
+}
+declare const posthog: AnalyticsAdapterFactory<PostHogConfig>;
+
+export { type PostHogConfig, posthog as default, posthog };

package/dist/adapters/posthog.js

@@ -0,0 +1,44 @@
+// src/adapters/posthog.ts
+var posthog = (config) => {
+  const { apiKey, apiHost = "https://app.posthog.com" } = config;
+  let distinctId = `anon_${Math.random().toString(36).slice(2)}`;
+  async function capture(event, properties) {
+    try {
+      await fetch(`${apiHost}/capture/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          api_key: apiKey,
+          event,
+          properties: { distinct_id: distinctId, ...properties },
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      });
+    } catch {
+    }
+  }
+  const adapter = {
+    name: "posthog",
+    trackPageview(data) {
+      capture("$pageview", { $current_url: data.url, $referrer: data.referrer });
+    },
+    trackEvent(data) {
+      capture(data.name, data.props);
+    },
+    identify(userId, traits) {
+      distinctId = userId;
+      if (traits) {
+        capture("$identify", { $set: traits });
+      }
+    },
+    setUserId(userId) {
+      distinctId = userId ?? `anon_${Math.random().toString(36).slice(2)}`;
+    }
+  };
+  return adapter;
+};
+var posthog_default = posthog;
+export {
+  posthog_default as default,
+  posthog
+};

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @flightdev/analytics - Agnostic Analytics
+ *
+ * @example
+ * ```typescript
+ * import { createAnalytics } from '@flightdev/analytics';
+ * import { plausible } from '@flightdev/analytics/plausible';
+ *
+ * const analytics = createAnalytics(plausible({
+ *   domain: 'example.com',
+ * }));
+ *
+ * analytics.trackPageview('/home');
+ * analytics.trackEvent('signup', { plan: 'pro' });
+ * ```
+ */
+interface PageviewData {
+    url: string;
+    referrer?: string;
+    deviceWidth?: number;
+}
+interface EventData {
+    name: string;
+    props?: Record<string, string | number | boolean>;
+    revenue?: {
+        amount: number;
+        currency: string;
+    };
+}
+interface AnalyticsAdapter {
+    readonly name: string;
+    trackPageview(data: PageviewData): void;
+    trackEvent(data: EventData): void;
+    identify?(userId: string, traits?: Record<string, unknown>): void;
+    setUserId?(userId: string | null): void;
+}
+type AnalyticsAdapterFactory<TConfig = unknown> = (config: TConfig) => AnalyticsAdapter;
+interface AnalyticsService {
+    readonly adapter: AnalyticsAdapter;
+    trackPageview(url: string, options?: Omit<PageviewData, 'url'>): void;
+    trackEvent(name: string, props?: Record<string, string | number | boolean>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    reset(): void;
+}
+declare function createAnalytics(adapter: AnalyticsAdapter): AnalyticsService;
+declare function getDeviceType(width: number): 'mobile' | 'tablet' | 'desktop';
+declare function parseUTMParams(url: string): Record<string, string>;
+
+export { type AnalyticsAdapter, type AnalyticsAdapterFactory, type AnalyticsService, type EventData, type PageviewData, createAnalytics, getDeviceType, parseUTMParams };

package/dist/index.js

@@ -0,0 +1,37 @@
+// src/index.ts
+function createAnalytics(adapter) {
+  return {
+    adapter,
+    trackPageview(url, options) {
+      adapter.trackPageview({ url, ...options });
+    },
+    trackEvent(name, props) {
+      adapter.trackEvent({ name, props });
+    },
+    identify(userId, traits) {
+      adapter.identify?.(userId, traits);
+    },
+    reset() {
+      adapter.setUserId?.(null);
+    }
+  };
+}
+function getDeviceType(width) {
+  if (width < 768) return "mobile";
+  if (width < 1024) return "tablet";
+  return "desktop";
+}
+function parseUTMParams(url) {
+  const params = new URL(url).searchParams;
+  const utm = {};
+  for (const key of ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"]) {
+    const value = params.get(key);
+    if (value) utm[key] = value;
+  }
+  return utm;
+}
+export {
+  createAnalytics,
+  getDeviceType,
+  parseUTMParams
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@flightdev/analytics",
+  "version": "0.0.2",
+  "description": "Agnostic analytics for Flight Framework. Choose your backend: Plausible, Umami, PostHog, or custom.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plausible": {
+      "types": "./dist/adapters/plausible.d.ts",
+      "import": "./dist/adapters/plausible.js"
+    },
+    "./posthog": {
+      "types": "./dist/adapters/posthog.d.ts",
+      "import": "./dist/adapters/posthog.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}