npm package: @plainapps/analytics-core
Description: Privacy-focused, cookie-free analytics tracking library
Author: Plain Web Analytics
Latest version: 1.0.2

# @plainapps/analytics-core

Privacy-focused, cookie-free analytics tracking library. This core package provides the base functionality for all framework-specific implementations.

## Features

- 🔒 **Privacy-first**: Cookie-free tracking using IP hashing
- 🚀 **Lightweight**: < 2KB gzipped
- 📦 **Tree-shakable**: Only import what you need
- 💪 **TypeScript**: Full type definitions included
- 🌐 **Universal**: Works in any JavaScript environment

## Installation

```bash
npm install @plainapps/analytics-core
# or
yarn add @plainapps/analytics-core
# or
pnpm add @plainapps/analytics-core
```

## Quick Start

```typescript
import { init, event, goal } from '@plainapps/analytics-core';

// Initialize with your site key
init({ siteId: 'pwa_site_abc123' });

// Track custom events
event('signup', { plan: 'pro' });

// Track goal conversions
goal('purchase', { revenue: 9900 }); // revenue in cents
```

## API Reference

### Configuration

```typescript
interface AnalyticsConfig {
  siteId: string;           // Required: Your site key (pwa_site_*)
  apiEndpoint?: string;     // Custom API endpoint
  autoPageview?: boolean;   // Auto-track pageview on init (default: true)
  hashMode?: boolean;       // Track hash changes as pageviews (default: false)
  debug?: boolean;          // Enable debug logging (default: false)
}
```

### Functions

#### `init(config: AnalyticsConfig): void`

Initialize analytics with your configuration.

```typescript
init({
  siteId: 'pwa_site_abc123',
  autoPageview: true,
  debug: false
});
```

#### `pageview(url?: string): void`

Manually track a pageview. If no URL is provided, uses the current page URL.

```typescript
// Track current page
pageview();

// Track specific URL (e.g., for SPAs)
pageview('/dashboard');
```

#### `event(name: string, properties?: EventProperties): void`

Track a custom event with optional properties.

```typescript
event('button_click', {
  button: 'signup',
  location: 'header'
});
```

#### `goal(goalId: string, options?: GoalOptions): void`

Track a goal conversion with optional revenue and properties.

```typescript
goal('purchase', {
  revenue: 9900,  // in cents
  properties: {
    plan: 'pro',
    period: 'annual'
  }
});
```

#### `setEnabled(enabled: boolean): void`

Enable or disable tracking (e.g., for user opt-out).

```typescript
// Disable tracking
setEnabled(false);

// Re-enable tracking
setEnabled(true);
```

#### `isInitialized(): boolean`

Check if analytics has been initialized.

#### `getConfig(): AnalyticsConfig | null`

Get the current configuration.

### Creating Multiple Instances

For advanced use cases, you can create multiple analytics instances:

```typescript
import { createAnalytics } from '@plainapps/analytics-core';

const analytics1 = createAnalytics();
analytics1.init({ siteId: 'site1' });

const analytics2 = createAnalytics();
analytics2.init({ siteId: 'site2' });
```

## Framework Libraries

For easier integration with popular frameworks:

- [@plainapps/analytics-react](../react) - React hooks and components
- [@plainapps/analytics-vue](../vue) - Vue 3 composables and plugin
- [@plainapps/analytics-svelte](../svelte) - Svelte stores and components
- [@plainapps/analytics-angular](../angular) - Angular service and directives

## License

MIT