npm package: @mirawision/gator
Description: A lightweight Google Analytics 4 tracking library for TypeScript, providing a simple and type-safe way to implement GA4 event tracking with support for generic events and triggers.
Author: Yelysei Lukin
Latest version: 1.0.0

# GAtor

A lightweight Google Analytics 4 tracking library for TypeScript, providing a simple and type-safe way to implement GA4 event tracking with support for generic events and triggers.

## Features

- 🎯 **Type-safe GA4 tracking** - Full TypeScript support with proper type definitions
- 🔄 **Generic events** - Automatically trigger additional events based on action patterns
- 🛡️ **Error handling** - Graceful error handling for all GA operations
- 📦 **Lightweight** - Minimal bundle size with no unnecessary dependencies
- 🚀 **Easy integration** - Simple API that works with any React or vanilla JS project

## Installation

```bash
npm install @mirawision/gator react-ga4
```

## Quick Start

```typescript
import { GAtor } from '@mirawision/gator';

// Initialize GAtor with your GA4 tracking ID
const gator = new GAtor({
  trackingId: 'G-XXXXXXXXXX'
});

// Track a page view
gator.trackPageView();

// Track an event
gator.trackEvent({
  category: 'User Interaction',
  action: 'button_click',
  label: 'signup_button'
});
```

## API Reference

### GAtor Constructor

```typescript
new GAtor(config: GAtorConfig)
```

**Parameters:**
- `config.trackingId` (string, required): Your Google Analytics 4 tracking ID
- `config.events` (GAEventMap, optional): Predefined event functions
- `config.genericEvents` (GenericGAEvent[], optional): Generic events that trigger based on action patterns

### Methods

#### `trackPageView()`
Tracks the current page view using the current URL.

#### `trackEvent(event: GAEvent)`
Tracks a custom event.

**Parameters:**
- `event.category` (string, required): Event category
- `event.action` (string, required): Event action
- `event.label` (string, optional): Event label
- `event[key]` (any, optional): Additional custom parameters

### Types

#### GAEvent
```typescript
interface GAEvent {
  category: string;
  action: string;
  label?: string;
  [key: string]: any;
}
```

#### GenericGAEvent
```typescript
interface GenericGAEvent {
  event: GAEvent;
  triggers: string[];
}
```

#### GAEventMap
```typescript
type GAEventMap = {
  [key: string]: GAEventFunction | GAEventMap;
};
```

## Advanced Usage

### Predefined Events

```typescript
const gator = new GAtor({
  trackingId: 'G-XXXXXXXXXX',
  events: {
    buttonClick: () => ({
      category: 'UI',
      action: 'button_click',
      label: 'cta_button'
    }),
    formSubmit: () => ({
      category: 'Form',
      action: 'form_submit',
      label: 'contact_form'
    })
  }
});

// Use predefined events
gator.trackEvent(gator.events.buttonClick());
```

### Generic Events

```typescript
const gator = new GAtor({
  trackingId: 'G-XXXXXXXXXX',
  genericEvents: [
    {
      event: {
        category: 'User Interaction',
        action: 'page_interaction'
      },
      triggers: ['click', 'scroll', 'hover']
    }
  ]
});

// This will trigger both the original event and the generic event
gator.trackEvent({
  category: 'UI',
  action: 'click',
  label: 'navigation_menu'
});
```

### Custom Parameters

```typescript
gator.trackEvent({
  category: 'E-commerce',
  action: 'purchase',
  label: 'premium_plan',
  value: 99.99,
  currency: 'USD',
  transaction_id: 'txn_12345'
});
```

## Error Handling

GAtor includes comprehensive error handling to ensure your application continues to work even if Google Analytics is unavailable:

- Initialization errors are caught and logged
- Event tracking errors are caught and logged
- Missing window object is handled gracefully
- All errors are logged to console for debugging

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you have any questions or need help, please open an issue on GitHub or contact us at [support@mirawision.com](mailto:support@mirawision.com).