Feature: Extensible notification system for syndication events

[GaryJones]

Overview

Implement an extensible notification system that alerts administrators when syndication events occur. This feature was partially implemented in the unreleased 2.1 branch and is being reimplemented with modern architecture patterns.

Background

The 2.1 branch contained a notification system (Syndication_Notifier class) that supported email and Slack notifications. This issue captures the requirements for a fresh implementation using service-oriented architecture with support for additional notification channels.

Requirements

Notification Events

The system should support notifications for the following events (hooks already exist in develop):

Event	Hook	Parameters
New post pushed	syn_post_push_new_post	$result, $post_ID, $site, $transport_type, $client, $info
Post updated (push)	syn_post_push_edit_post	$result, $post_ID, $site, $transport_type, $client, $info
Post deleted (push)	syn_post_push_delete_post	$result, $ext_ID, $post_ID, $site_ID, $transport_type, $client
New post pulled	syn_post_pull_new_post	$result, $post, $site, $transport_type, $client
Post updated (pull)	syn_post_pull_edit_post	$result, $post, $site, $transport_type, $client

Notification Channels

Built-in channels:

• Email: Send HTML emails via wp_mail()
• Slack: Send messages via incoming webhook URL

Extensibility requirement: The architecture must allow third-party developers to register additional notification channels (e.g., Microsoft Teams, Discord, PagerDuty, custom webhooks) without modifying core plugin code.

Configuration

Global settings (under Push Syndication → Settings):

• Enable/disable each notification channel independently
• Per-channel configuration:
  • Email: recipient address(es)
  • Slack: webhook URL
• Per-channel event selection (which events trigger notifications)

Notification Content

Each notification should include:

• Event type (created/updated/deleted)
• Post title and link to edit screen
• Endpoint name and link
• Success/failure status
• Error message (if applicable)
• Timestamp

Architecture

Suggested service-oriented design:

┌─────────────────────────────────────────────────────────┐
│                 NotificationService                      │
│  - Listens to syndication hooks                         │
│  - Creates NotificationEvent value objects              │
│  - Dispatches to registered channels                    │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│            NotificationChannelInterface                  │
│  + send(NotificationEvent $event): bool                 │
│  + get_id(): string                                     │
│  + get_label(): string                                  │
│  + render_settings(): void                              │
│  + is_configured(): bool                                │
└─────────────────────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   ┌────────────┐  ┌────────────┐  ┌────────────┐
   │EmailChannel│  │SlackChannel│  │  Future    │
   └────────────┘  └────────────┘  │ Channels   │
                                   └────────────┘

Value Objects:

• NotificationEvent: Immutable object containing event type, post data, endpoint data, result, timestamp
• NotificationResult: Success/failure with optional error message

Extensibility hook:

// Third-party developers can add channels:
add_filter( 'syn_notification_channels', function( array $channels ): array {
    $channels[] = new My_Custom_Channel();
    return $channels;
} );

Acceptance Criteria

• NotificationService class listens to all syndication event hooks
• EmailChannel sends HTML emails with event details
• SlackChannel sends formatted messages to webhook URL
• Settings UI allows enabling/disabling channels and selecting events
• syn_notification_channels filter allows registering custom channels
• Unit tests for NotificationService and value objects
• Integration tests for email and Slack delivery
• Failed notifications are logged via Syndication_Logger

Out of Scope

• Per-endpoint notification settings (future enhancement)
• Notification batching/digest mode (future enhancement)
• Retry logic for failed notifications (future enhancement)

References

• Original feature request: v2: Syndication UI #113
• 2.1 branch implementation: includes/class-syndication-notifier.php
• 2.1 settings implementation: includes/admin/class-settings-screen.php