# Event tracking

Event tracking is **on by default** (`events.enabled = true`). Use it to record custom events from anywhere in your application.

## Privacy model

From `Ranetrace::trackEvent()`, each event ships with:

- The event name and properties.
- The authenticated user's ID (or an `int|string $userId` you pass explicitly).
- A timestamp and the request's full URL.
- `user_agent_hash`: the user agent **hashed**, not stored raw.
- `session_id_hash`: the session ID **hashed**.

The IP address is not included in the event payload.

## Tracking a custom event

```php
use Ranetrace\Laravel\Facades\Ranetrace;

Ranetrace::trackEvent('button_clicked', [
    'button_id' => 'header-cta',
    'page' => 'homepage',
]);
```

Full signature:

```php
Ranetrace::trackEvent(
    string $eventName,
    array $properties = [],
    int|string|null $userId = null,
    bool $validate = true,
);
```

By default the event name is validated: it must be lowercase snake_case, start with a letter and be 3 to 50 characters long. A name that fails throws an `InvalidArgumentException`, even while event capture is off, so a bad name surfaces in development rather than in production. `RanetraceEvents::custom()` checks the same way. Pass `validate: false` to skip the check.

## Convenience helpers

The `RanetraceEvents` facade exposes typed helpers (see the `@method` block on `Ranetrace\Laravel\Facades\RanetraceEvents`):

```php
use Ranetrace\Laravel\Facades\RanetraceEvents;

// Sales
RanetraceEvents::sale(
    orderId: 'ORDER-456',
    totalAmount: 89.97,
    products: [
        ['id' => 'PROD-123', 'name' => 'Widget', 'price' => 29.99, 'quantity' => 3],
    ],
    currency: 'USD',
);

// Cart additions
RanetraceEvents::productAddedToCart(
    productId: 'PROD-123',
    productName: 'Widget',
    price: 29.99,
    quantity: 1,
);

// Authentication
RanetraceEvents::userRegistered(userId: $user->id);
RanetraceEvents::userLoggedIn(userId: $user->id);

// Page views (server-recorded)
RanetraceEvents::pageView(pageName: 'pricing');

// Generic custom event
RanetraceEvents::custom('newsletter_signup', ['source' => 'footer']);
```

All helpers accept an `array $additionalProperties = []` as their final argument for ad-hoc fields.

## Testing your setup

```bash
php artisan ranetrace:test-events
```

## Configuration

From `config/ranetrace.php`:

```php
'events' => [
    'enabled' => env('RANETRACE_EVENTS_ENABLED', true),
    'queue' => env('RANETRACE_EVENTS_QUEUE', true),
    'queue_name' => env('RANETRACE_EVENTS_QUEUE_NAME', 'default'),
    'timeout' => env('RANETRACE_EVENTS_TIMEOUT', 10),
],
```

To disable:

```dotenv
RANETRACE_EVENTS_ENABLED=false
```