whatshooked/EVENT_LOGGER.md

# Event Logger Configuration

The event logger allows you to persist all system events to various storage targets for auditing, debugging, and analytics.

## Configuration

Add the `event_logger` section to your `config.json`:

```json
{
  "event_logger": {
    "enabled": true,
    "targets": ["file", "sqlite", "postgres"],
    "file_dir": "./data/events",
    "table_name": "event_logs"
  },
  "database": {
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "whatshooked",
    "password": "your_password_here",
    "database": "whatshooked",
    "sqlite_path": "./data/events.db"
  }
}
```

## Configuration Options

### event_logger

- **enabled** (boolean): Enable or disable event logging
  - Default: `false`

- **targets** (array): List of storage targets to use. Options:
  - `"file"` - Store events as JSON files in organized directories
  - `"sqlite"` - Store events in a local SQLite database
  - `"postgres"` or `"postgresql"` - Store events in PostgreSQL database

- **file_dir** (string): Base directory for file-based event storage
  - Default: `"./data/events"`
  - Events are organized as: `{file_dir}/{event_type}/{YYYYMMDD}/{HH_MM_SS}_{event_type}.json`

- **table_name** (string): Database table name for storing events
  - Default: `"event_logs"`

### database

Database configuration is shared with the event logger when using `sqlite` or `postgres` targets.

For **SQLite**:
- `sqlite_path`: Path to SQLite database file (e.g., `"./data/events.db"`)
- If not specified, defaults to `"./data/events.db"`

For **PostgreSQL**:
- `type`: `"postgres"`
- `host`: Database host (e.g., `"localhost"`)
- `port`: Database port (e.g., `5432`)
- `username`: Database username
- `password`: Database password
- `database`: Database name

## Storage Targets

### File Target

Events are stored as JSON files in an organized directory structure:

```
./data/events/
├── message.received/
│   ├── 20231225/
│   │   ├── 14_30_45_message.received.json
│   │   ├── 14_31_12_message.received.json
│   │   └── 14_32_00_message.received.json
│   └── 20231226/
│       └── 09_15_30_message.received.json
├── message.sent/
│   └── 20231225/
│       └── 14_30_50_message.sent.json
└── whatsapp.connected/
    └── 20231225/
        └── 14_00_00_whatsapp.connected.json
```

Each file contains the complete event data:
```json
{
  "type": "message.received",
  "timestamp": "2023-12-25T14:30:45Z",
  "data": {
    "account_id": "acc1",
    "from": "+1234567890",
    "message": "Hello, world!",
    ...
  }
}
```

### SQLite Target

Events are stored in a SQLite database with the following schema:

```sql
CREATE TABLE event_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_type TEXT NOT NULL,
    timestamp DATETIME NOT NULL,
    data TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_event_logs_type_timestamp
ON event_logs(event_type, timestamp);
```

### PostgreSQL Target

Events are stored in PostgreSQL with JSONB support for efficient querying:

```sql
CREATE TABLE event_logs (
    id SERIAL PRIMARY KEY,
    event_type VARCHAR(100) NOT NULL,
    timestamp TIMESTAMP NOT NULL,
    data JSONB NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_event_logs_type_timestamp
ON event_logs(event_type, timestamp);
```

## Event Types

The following event types are logged:

### WhatsApp Connection Events
- `whatsapp.connected`
- `whatsapp.disconnected`
- `whatsapp.pair.success`
- `whatsapp.pair.failed`
- `whatsapp.qr.code`
- `whatsapp.qr.timeout`
- `whatsapp.qr.error`
- `whatsapp.pair.event`

### Message Events
- `message.received`
- `message.sent`
- `message.failed`
- `message.delivered`
- `message.read`

### Hook Events
- `hook.triggered`
- `hook.success`
- `hook.failed`

## Examples

### Enable File Logging Only
```json
{
  "event_logger": {
    "enabled": true,
    "targets": ["file"],
    "file_dir": "./logs/events"
  }
}
```

### Enable SQLite Logging Only
```json
{
  "event_logger": {
    "enabled": true,
    "targets": ["sqlite"]
  },
  "database": {
    "sqlite_path": "./data/whatshooked.db"
  }
}
```

### Enable Multiple Targets
```json
{
  "event_logger": {
    "enabled": true,
    "targets": ["file", "sqlite", "postgres"],
    "file_dir": "./data/events",
    "table_name": "event_logs"
  },
  "database": {
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "whatshooked",
    "password": "securepassword",
    "database": "whatshooked",
    "sqlite_path": "./data/events.db"
  }
}
```

## Querying Events

### SQLite Query Examples

```sql
-- Get all message events from the last 24 hours
SELECT * FROM event_logs
WHERE event_type LIKE 'message.%'
  AND timestamp > datetime('now', '-1 day')
ORDER BY timestamp DESC;

-- Count events by type
SELECT event_type, COUNT(*) as count
FROM event_logs
GROUP BY event_type
ORDER BY count DESC;
```

### PostgreSQL Query Examples

```sql
-- Get all message events with specific sender
SELECT * FROM event_logs
WHERE event_type = 'message.received'
  AND data->>'from' = '+1234567890'
ORDER BY timestamp DESC;

-- Find events with specific data fields
SELECT event_type, timestamp, data
FROM event_logs
WHERE data @> '{"account_id": "acc1"}'
ORDER BY timestamp DESC
LIMIT 100;
```

## Performance Considerations

- **File Target**: Suitable for low to medium event volumes. Easy to backup and archive.
- **SQLite Target**: Good for single-server deployments. Supports moderate event volumes.
- **PostgreSQL Target**: Best for high-volume deployments and complex queries. Supports concurrent access.

You can enable multiple targets simultaneously to balance immediate access (file) with queryability (database).