# Notification Logic Documentation

## Overview

The notification system has two levels of control:
1. **Global Channel Toggle** - Enable/disable entire channel (Channels page)
2. **Per-Event Channel Toggle** - Enable/disable channel for specific event (Events page)

Both must be enabled for a notification to be sent.

## Toggle Hierarchy

```
┌─────────────────────────────────────────┐
│  Global Channel Toggle (Channels Page)  │
│  - Affects ALL events                   │
│  - Stored in wp_options                 │
│  - woonoow_email_notifications_enabled  │
│  - woonoow_push_notifications_enabled   │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│ Per-Event Channel Toggle (Events Page)  │
│  - Affects specific event only          │
│  - Stored in woonoow_notification_settings│
│  - Independent per event                │
└─────────────────────────────────────────┘
```

## Decision Logic

```php
// Notification will be sent if:
if (channel_globally_enabled && event_channel_enabled) {
    send_notification();
}
```

## Examples

### Example 1: Email Disabled Globally
```
Global Email Toggle: OFF
Event "Order Placed" Email Toggle: ON
Result: ❌ No email sent
```

### Example 2: Email Enabled Globally, Disabled for Event
```
Global Email Toggle: ON
Event "Order Placed" Email Toggle: OFF
Result: ❌ No email sent
```

### Example 3: Both Enabled
```
Global Email Toggle: ON
Event "Order Placed" Email Toggle: ON
Result: ✅ Email sent
```

## Implementation

### NotificationManager Class

Located at: `includes/Core/Notifications/NotificationManager.php`

**Key Methods:**

1. `is_channel_enabled($channel_id)` - Check global channel state
2. `is_event_channel_enabled($event_id, $channel_id)` - Check per-event state
3. `should_send_notification($event_id, $channel_id)` - Validate both
4. `send($event_id, $channel_id, $data)` - Send notification

### Usage Example

```php
use WooNooW\Core\Notifications\NotificationManager;

// Check if notification should be sent
if (NotificationManager::should_send_notification('order_placed', 'email')) {
    NotificationManager::send('order_placed', 'email', [
        'order_id' => 123,
        'customer_email' => 'customer@example.com',
    ]);
}
```

## Frontend Integration

### Channels Page (`Channels.tsx`)

- Shows global enable/disable toggle
- Affects all events
- API: `POST /notifications/channels/toggle`
- Params: `{ channelId, enabled }`

### Events Page (`Events.tsx`)

- Shows per-event channel toggles
- Independent for each event
- API: `POST /notifications/events/update`
- Params: `{ eventId, channels: { [channelId]: { enabled, recipient } } }`

## Storage

### Global Channel State
```php
// Email
get_option('woonoow_email_notifications_enabled', true);

// Push
get_option('woonoow_push_notifications_enabled', true);
```

### Per-Event Channel State
```php
$settings = get_option('woonoow_notification_settings', []);
$settings['order_placed']['channels']['email']['enabled'] = true;
$settings['order_placed']['channels']['email']['recipient'] = 'customer';
```

## Testing Checklist

- [ ] Disable email globally → No emails sent for any event
- [ ] Enable email globally, disable for specific event → Email sent for other events only
- [ ] Enable both → Email sent
- [ ] Same tests for push notifications
- [ ] Toggle persistence across page reloads
- [ ] UI reflects current state correctly
- [ ] Toast notifications on toggle
- [ ] Green icon when enabled, gray when disabled

## Future Enhancements

1. **Batch Operations** - Enable/disable multiple events at once
2. **Channel Priority** - Set fallback channels
3. **Scheduling** - Delay or schedule notifications
4. **Rate Limiting** - Prevent notification spam
5. **Analytics** - Track notification delivery rates