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

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.

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.

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:

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:

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.

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:

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.

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

// 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

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

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

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

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