npm package: @jakobinn/llamametrics
Description: Client-side analytics tracker.
Latest version: 0.2.12

# Llamametrics Analytics SDK

A lightweight, multi-platform analytics client for Web, React Native, and Node.js.

This package uses a modern **multi-entry-point architecture**. You should import the client from the path specific to your environment.

## Installation

```bash
npm install @jakobinn/llamametrics
```

## Usage

### For Web (React.js / Next.js / Vanilla JS)

This entry point is optimized for browsers and includes automatic tracking for UTM parameters (`?trc11`) and referrers.

```typescript
import { createWebAnalytics } from '@jakobinn/llamametrics/web';

const analytics = createWebAnalytics({
  apiKey: 'YOUR_API_KEY',
  // host optional in browser: defaults to current origin => POST /api/v1/track
  debug: false,
});

analytics.track('SCREEN_VIEW', 'HOME_PAGE_LOADED', { userId: 'user_123' });
analytics.feedback('FEATURE_RATING', 'FEATURE_MODAL', { rating: 5, text: 'Great!' });
await analytics.flush();
```

**Note:** The web adapter automatically attaches a referrer plugin that tracks campaign clicks (`?trc11` parameter) and external referrers once per session.

### For React Native

This entry point is optimized for the React Native environment, using `AsyncStorage` (optional) and platform-specific APIs.

```typescript
import { createReactNativeAnalytics } from '@jakobinn/llamametrics/react-native';

const analytics = createReactNativeAnalytics({
  apiKey: 'YOUR_API_KEY',
  host: 'https://your-analytics-server.com', // REQUIRED for React Native
  // All auto-detection enabled by default
  autoDetectEnvironment: true,
  enableDeviceInfo: true,
  enableNetworkInfo: true,
  enableLocalization: true,
  mobileOptimized: true,
});

analytics.track('INTERACTION', 'BUTTON_TAPPED', { screen: 'Home' });
```

**Advanced React Native Usage:**

```typescript
import { AnalyticsJJClient, type ReactNativeAnalyticsConfig } from '@jakobinn/llamametrics/react-native';

// Custom configuration
const config: ReactNativeAnalyticsConfig = {
  apiKey: 'YOUR_API_KEY',
  host: 'https://your-analytics-server.com',
  environment: 'production', // Manual override
  mobileOptimized: true,
  enableDeviceInfo: true,
};

const analytics = new AnalyticsJJClient(config);
```

**Quick Setup with Auto-Detection:**

```typescript
import { createAutoAnalytics } from '@jakobinn/llamametrics/react-native';

const analytics = createAutoAnalytics('YOUR_API_KEY', 'https://your-analytics-server.com');
```

### For Node.js (Server-side)

This entry point is designed for server-side usage.

```typescript
import { createNodeAnalytics } from '@jakobinn/llamametrics/node';

const analytics = createNodeAnalytics({
  apiKey: 'YOUR_API_KEY',
  host: 'https://your-analytics-server.com', // REQUIRED for Node.js
  debug: false,
});

analytics.track('SYSTEM', 'JOB_PROCESSED_SUCCESSFULLY', { jobId: 'job_123' });
await analytics.flush();
```

**Server-side Singleton Pattern:**

For serverless environments or when you want a singleton client, use the server entry point:

```typescript
import { getAnalyticsServerClient } from '@jakobinn/llamametrics/node/server';

// Reads configuration from environment variables:
// ANALYTICS_API_KEY and ANALYTICS_HOST
const analytics = getAnalyticsServerClient();

analytics.track('API', 'REQUEST_PROCESSED', { endpoint: '/api/users' });
```

**Environment Variables for Server Client:**
- `ANALYTICS_API_KEY` (required): Your API key
- `ANALYTICS_HOST` (required): Your analytics server URL
- `NODE_ENV`: When set to `'development'`, enables debug logging

### For Shared Types and Core Utilities

If you only need to import shared types, constants, or the base client class, you can import them from the core entry point.

```typescript
import type { AnalyticsClientConfig, AnalyticsEventType } from '@jakobinn/llamametrics/core';
import { AnalyticsJJClient } from '@jakobinn/llamametrics/core';

// Or use the default export (same as ./core)
import type { AnalyticsClientConfig } from '@jakobinn/llamametrics';
```

## Entry Points Reference

| Entry Point | Exports | Use Case |
|------------|---------|----------|
| `@jakobinn/llamametrics` (default) | `AnalyticsJJClient`, types, constants | Core functionality (same as `./core`) |
| `@jakobinn/llamametrics/core` | `AnalyticsJJClient`, types, constants | Explicit core imports |
| `@jakobinn/llamametrics/web` | `createWebAnalytics` | Browser/web applications |
| `@jakobinn/llamametrics/react-native` | `createReactNativeAnalytics`, `AnalyticsJJClient`, types | React Native apps |
| `@jakobinn/llamametrics/node` | `createNodeAnalytics` | Node.js server applications |
| `@jakobinn/llamametrics/node/server` | `getAnalyticsServerClient` | Server-side singleton client |

## Configuration

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `apiKey` | `string` | — | **Required.** Sent as `Authorization: Bearer <apiKey>` header. |
| `host` | `string` | `''` | **Browser:** optional (uses current origin). **Node/RN:** **required** (absolute URL). |
| `flushInterval` | `number` | `5000` | Milliseconds after last event before auto-flush. |
| `batchSize` | `number` | `20` | Flush immediately when queue ≥ size. |
| `runtime` | `string` | — | Automatically set by adapter (`'web'`, `'node'`, `'react_native'`). |
| `setUserTimestamp` | `boolean` | `false` | Adds ISO `user_timestamp` to each event. |
| `debug` | `boolean` | `false` | Logs request diagnostics and warnings. |
| `environment` | `'development' \| 'production' \| 'test'` | Auto-detected | Auto-detected from `NODE_ENV` or `__DEV__` (RN). |

**React Native Specific Options:**

| Key | Type | Default | Notes |
|-----|------|---------|-------|
| `autoDetectEnvironment` | `boolean` | `true` | Auto-detect from `__DEV__`. |
| `enableDeviceInfo` | `boolean` | `true` | Auto-detect device info (requires `react-native-device-info`). |
| `enableNetworkInfo` | `boolean` | `true` | Auto-detect network info (requires `@react-native-netinfo/netinfo`). |
| `enableLocalization` | `boolean` | `true` | Auto-detect locale (requires `react-native-localize`). |
| `mobileOptimized` | `boolean` | `true` | Apply mobile-optimized defaults (smaller batches, more frequent flushing). |

## API

### Factory Functions

```typescript
// Web
createWebAnalytics(config: AnalyticsClientConfig): AnalyticsJJClient

// React Native
createReactNativeAnalytics(config: ReactNativeAnalyticsConfig): AnalyticsJJClient
createAutoAnalytics(apiKey: string, host?: string): AnalyticsJJClient

// Node.js
createNodeAnalytics(config: AnalyticsClientConfig): AnalyticsJJClient
getAnalyticsServerClient(): AnalyticsJJClient // From './node/server'
```

### Client Methods

```typescript
class AnalyticsJJClient {
  track(
    eventType: AnalyticsEventType,
    eventName: string,
    properties?: TrackProperties
  ): void;

  feedback(
    eventName: string,
    source: string,
    data?: Partial<FeedbackDataV1>,
    properties?: TrackProperties
  ): void;

  flush(): Promise<void>;
  trackAndFlush(...): Promise<void>;
}
```

**Event Types** (`AnalyticsEventType`):
`CLICKTHROUGH | INTERACTION | SUBMIT | SEARCH | SCREEN_VIEW | SYSTEM | ERROR | SESSION | AUTH | CONVERSION | FEEDBACK | CUSTOM`

**Properties highlights:** `userId`, `email`, `groupId`, `subscriptionStatus`, `isSubscribed`, `data`, `jsonData`, `environment`, `event_name_detailed`, `runtime`, `user_timestamp`, `deviceType`, `windowWidth`, `windowHeight`, `timezone`, `browser`, `os`, `osVersion`.

## Examples

### Web Example

```typescript
import { createWebAnalytics } from '@jakobinn/llamametrics/web';

const analytics = createWebAnalytics({
  apiKey: 'your-api-key',
  debug: true,
});

// Track page views
analytics.track('SCREEN_VIEW', 'HOME_SCREEN_OPENED', {
  userId: 'user_123',
  page: '/home',
});

// Collect feedback
analytics.feedback('FEATURE_RATING', 'FEATURE_MODAL', {
  rating: 5,
  text: 'Love this feature!',
});

// Flush manually
await analytics.flush();
```

### React Native Example

```typescript
import { createReactNativeAnalytics } from '@jakobinn/llamametrics/react-native';

const analytics = createReactNativeAnalytics({
  apiKey: 'your-api-key',
  host: 'https://analytics.example.com',
});

// Track user interactions
analytics.track('INTERACTION', 'BUTTON_TAPPED', {
  buttonId: 'signup-button',
  screen: 'Welcome',
});

// Automatic flushing happens in the background
```

### Node.js Example

```typescript
import { createNodeAnalytics } from '@jakobinn/llamametrics/node';

const analytics = createNodeAnalytics({
  apiKey: process.env.ANALYTICS_API_KEY,
  host: process.env.ANALYTICS_HOST,
});

// Track server events
analytics.track('SYSTEM', 'JOB_COMPLETED', {
  jobId: 'job_123',
  duration: 1500,
});

// Always flush before process exits
await analytics.flush();
```

## 🤖 AI assistance (Cursor)

If you use the Cursor editor, this package ships ready-made **Cursor rule files** to help AI correctly import and use the SDK:

- `docs/cursor-rules/llamametrics.mdc` – master rule for all platforms
- `docs/cursor-rules/llamametrics-web.mdc` – web / Next.js specific usage
- `docs/cursor-rules/llamametrics-rn.mdc` – React Native / Expo specific usage

Copy the relevant file(s) into your app’s `.cursor/rules/` directory (for example, `.cursor/rules/llamametrics-web.mdc`). This teaches Cursor’s AI how to use `@jakobinn/llamametrics` without hallucinating unsupported imports or methods.

## Architecture

This package uses a **monorepo structure** with shared core logic and platform-specific adapters:

- **`packages/core`**: Shared client class, types, constants, and environment adapters
- **`packages/web`**: Browser adapter with referrer/campaign tracking plugin
- **`packages/react-native`**: React Native adapter with device info, network info, and localization support
- **`packages/node`**: Node.js adapter with server-side optimizations

All packages are built together and published as a single npm package with multiple entry points, ensuring optimal bundle sizes and platform-specific optimizations.

## License

MIT