Save this content to: .claude/skills/ranetrace-event-tracking/SKILL.md

# Ranetrace event tracking

## When to use this skill

Use this skill when implementing custom event tracking for analytics, e-commerce metrics, user behavior tracking, or any application-specific events.

## Facades

- `Ranetrace::trackEvent(string $eventName, array $properties = [], int|string|null $userId = null, bool $validate = true)`: low-level tracking (`$userId` accepts int or string for UUID models; `$validate: false` skips snake_case name validation)
- `RanetraceEvents`: convenience methods with built-in validation

## Standard event constants

The `EventTracker` class provides constants for common events:

```php
use Ranetrace\Laravel\Events\EventTracker;

EventTracker::PRODUCT_ADDED_TO_CART  // 'product_added_to_cart'
EventTracker::PRODUCT_REMOVED_FROM_CART
EventTracker::CART_VIEWED
EventTracker::CHECKOUT_STARTED
EventTracker::CHECKOUT_COMPLETED
EventTracker::SALE                    // 'sale'
EventTracker::USER_REGISTERED         // 'user_registered'
EventTracker::USER_LOGGED_IN
EventTracker::USER_LOGGED_OUT
EventTracker::PAGE_VIEW
EventTracker::SEARCH
EventTracker::NEWSLETTER_SIGNUP
EventTracker::CONTACT_FORM_SUBMITTED
```

## Convenience methods

### E-commerce

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

// Track a sale
RanetraceEvents::sale(
    orderId: 'ORD-123',
    totalAmount: 99.99,
    products: [['id' => 'PROD-1', 'name' => 'Widget', 'price' => 49.99]],
    currency: 'EUR',
);

// Track product added to cart
RanetraceEvents::productAddedToCart(
    productId: 'PROD-1',
    productName: 'Widget',
    price: 49.99,
    quantity: 2,
    category: 'Electronics',
);
```

### User actions

```php
// Track user registration (auto-detects authenticated user if $userId is null)
RanetraceEvents::userRegistered(userId: $user->id);

// Track user login
RanetraceEvents::userLoggedIn();

// Track a specific page view (distinct from website analytics)
RanetraceEvents::pageView('pricing-page');
```

### Custom events

```php
// Custom event with validation (enforces naming rules)
RanetraceEvents::custom('feature_toggled', [
    'feature' => 'dark_mode',
    'enabled' => true,
]);

// Custom event without validation (advanced use only)
RanetraceEvents::customUnsafe('My.Custom.Event', $properties);
```

## Event naming rules

Event names are validated by default and must:
- Use `snake_case` format (lowercase with underscores)
- Be 3-50 characters long
- Start with a letter
- Only contain letters, numbers, and underscores

An invalid name throws an `InvalidArgumentException`. `RanetraceEvents::custom()` and `Ranetrace::trackEvent()` both check on every call, whether or not capture is on, so a bad name fails locally rather than first in production. `validate: false` on `trackEvent()` skips the check.

Valid: `user_registered`, `checkout_completed`, `feature_toggled`
Invalid: `UserRegistered`, `a`, `123_event`, `my-event`

## Configuration

```php
// config/ranetrace.php
'events' => [
    'enabled' => env('RANETRACE_EVENTS_ENABLED', true),
    'queue' => env('RANETRACE_EVENTS_QUEUE', true),
    'queue_name' => env('RANETRACE_EVENTS_QUEUE_NAME', null), // unset: the connection's default queue
    'timeout' => env('RANETRACE_EVENTS_TIMEOUT', 10),
],
```

## What gets captured

Each event includes:
- Event name and custom properties
- Authenticated user (auto-detected or explicitly provided)
- Timestamp
- Current URL
- User agent hash and session ID hash (privacy-first, no raw values stored)

## Testing

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