diff --git a/NOTIFICATION_LOGIC.md b/NOTIFICATION_LOGIC.md new file mode 100644 index 0000000..be1ba42 --- /dev/null +++ b/NOTIFICATION_LOGIC.md @@ -0,0 +1,140 @@ +# 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 diff --git a/includes/Core/Notifications/NotificationManager.php b/includes/Core/Notifications/NotificationManager.php new file mode 100644 index 0000000..eefbd99 --- /dev/null +++ b/includes/Core/Notifications/NotificationManager.php @@ -0,0 +1,174 @@ +