docs: update @SInCE tags to 2.1.0 for new features

Author: miguelcolmenares

CHANGELOG.md

@@ -9,6 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Granular Alert Preferences**: Per-submission failure alerts with granular control
+  - New `alert_types` setting structure with `threshold` and `individual` options
+  - `maybe_send_individual_alert()` triggers when a submission permanently fails after all retries
+  - Individual alerts are event-driven (no cooldown) vs rate-limited threshold alerts
+  - Privacy-first design: alert emails contain only error metadata (form name, endpoint, timestamp, response code, error message) - never user-submitted form data
+  - Spam prevention: transient flag per log_id prevents duplicate alerts on retry
+  - UI: "Alert Types" section with nested checkboxes for threshold and individual alerts
+  - Threshold settings reorganized under clear subheading
+  - Backward compatible: threshold alerts enabled by default, individual disabled
+  - Integrated in `LogsController::handle_retry_action()` for retry exhaustion and max limit scenarios
+
 - **Response Action Hook (`cf7_api_after_response`)**: New filter hook for extending plugin functionality
   - Fires after each API response is received (success or failure)
   - Provides complete response data (status code, headers, body, parsed JSON, duration)

docs/API_REFERENCE.md

@@ -624,6 +624,31 @@ Handles plugin activation, deactivation, and lifecycle.
 | `uninstall()` | `void` | Plugin uninstallation handler |
 | `create_tables()` | `void` | Create database tables |
 
+### Config\Settings
+
+Plugin settings management with singleton pattern.
+
+```php
+use SilverAssist\ContactFormToAPI\Config\Settings;
+
+$settings = Settings::instance();
+$is_enabled = $settings->is_alerts_enabled();
+```
+
+#### Methods
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `instance()` | `Settings` | Get singleton instance |
+| `get(string $key, $default)` | `mixed` | Get setting value |
+| `set(string $key, $value)` | `bool` | Set setting value |
+| `is_alerts_enabled()` | `bool` | Check if alerts are enabled globally |
+| `get_alert_types()` | `array` | Get alert types configuration (since 2.1.0) |
+| `is_threshold_alerts_enabled()` | `bool` | Check if threshold alerts are enabled (since 2.1.0) |
+| `is_individual_alerts_enabled()` | `bool` | Check if individual alerts are enabled (since 2.1.0) |
+| `get_alert_recipients()` | `string` | Get comma-separated alert recipients |
+| `is_encryption_enabled()` | `bool` | Check if encryption is enabled |
+
 ### Service\Logging\LogWriter
 
 Create and update log entries.
@@ -743,6 +768,45 @@ $encrypted = $encryption->encrypt($data);
 $decrypted = $encryption->decrypt($encrypted);
 ```
 
+### Service\Notification\EmailAlertService
+
+Email alert service for monitoring API errors.
+
+**Since**: 1.3.0 (Individual alerts added in 2.1.0)
+
+```php
+use SilverAssist\ContactFormToAPI\Service\Notification\EmailAlertService;
+
+$alerts = EmailAlertService::instance();
+$alerts->check_and_alert(); // Threshold-based alerts
+$alerts->maybe_send_individual_alert($log_id, $form_id); // Individual failure alerts
+```
+
+#### Methods
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `instance()` | `EmailAlertService` | Get singleton instance |
+| `check_and_alert()` | `void` | Check error rates and send threshold alerts |
+| `maybe_send_individual_alert(int $log_id, int $form_id)` | `void` | Send individual failure alert if enabled (since 2.1.0) |
+
+#### Individual Failure Alerts
+
+Individual failure alerts (added in 2.1.0) notify administrators immediately when a submission permanently fails after exhausting all retries.
+
+**Features**:
+- Event-driven (no cooldown like threshold alerts)
+- Privacy-first: emails contain only error metadata, never user-submitted form data
+- Spam prevention: transient flag per log_id prevents duplicate alerts
+
+**Alert email includes**:
+- Site name and form title
+- API endpoint URL
+- Timestamp
+- HTTP response code
+- Error message
+- Link to view full log details
+
 ### Controller\ContactForm\SubmissionController
 
 CF7 submission controller handling hook registration.
@@ -993,6 +1057,6 @@ class LoggingServiceTest extends TestCase {
 
 ---
 
-**Document Version**: 2.0.0  
-**Last Updated**: January 25, 2026  
+**Document Version**: 2.1.0  
+**Last Updated**: January 26, 2026  
 **Maintained By**: Silver Assist Development Team

includes/Config/Settings.php

@@ -356,7 +356,7 @@ public function is_encryption_enabled(): bool {
 	/**
 	 * Get alert types configuration
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @return array{threshold: bool, individual: bool} Alert types configuration.
 	 */
 	public function get_alert_types(): array {
@@ -381,7 +381,7 @@ public function get_alert_types(): array {
 	/**
 	 * Check if threshold alerts are enabled
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @return bool
 	 */
 	public function is_threshold_alerts_enabled(): bool {
@@ -392,7 +392,7 @@ public function is_threshold_alerts_enabled(): bool {
 	/**
 	 * Check if individual failure alerts are enabled
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @return bool
 	 */
 	public function is_individual_alerts_enabled(): bool {

includes/Controller/Admin/LogsController.php

@@ -515,6 +515,7 @@ private function get_log_by_id( int $log_id ): ?array {
 	 *
 	 * Fetches statistics from LogStatistics service based on current filters.
 	 *
+	 * @since 2.1.0
 	 * @return array{stats: array<string, mixed>, date_context: string} Statistics and date context.
 	 */
 	private function get_statistics_data(): array {
@@ -544,6 +545,7 @@ private function get_statistics_data(): array {
 	/**
 	 * Get date context label for statistics
 	 *
+	 * @since 2.1.0
 	 * @param string      $date_filter Date filter type.
 	 * @param string|null $date_start  Start date.
 	 * @param string|null $date_end    End date.
@@ -578,6 +580,7 @@ private function get_date_context_label( string $date_filter, ?string $date_star
 	 *
 	 * Converts date filter type to start/end date strings.
 	 *
+	 * @since 2.1.0
 	 * @return array{filter: string, start: string|null, end: string|null} Date range parameters.
 	 */
 	private function get_date_range_from_filter(): array {
@@ -632,6 +635,7 @@ private function get_date_range_from_filter(): array {
 	/**
 	 * Get custom date range from request parameters
 	 *
+	 * @since 2.1.0
 	 * @param string $date_start Start date.
 	 * @param string $date_end   End date.
 	 * @return array{filter: string, start: string|null, end: string|null} Custom date range.
@@ -861,7 +865,7 @@ private function get_filtered_logs(): array {
 	 * Triggers an individual failure alert for a log entry if the feature is enabled.
 	 * Gets the form_id from the log and passes it to the EmailAlertService.
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @param int $log_id Log entry ID.
 	 * @return void
 	 */

includes/Controller/Admin/SettingsController.php

@@ -323,7 +323,7 @@ private function sanitize_email_recipients( string $input ): string {
 	/**
 	 * Sanitize alert types array
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @param array<string, mixed> $post_data POST data array.
 	 * @return array{threshold: bool, individual: bool} Sanitized alert types.
 	 */

includes/Service/Logging/LogReader.php

@@ -222,7 +222,7 @@ public function decrypt_log_fields( array $log ): array {
 	 * Retrieves a list of forms that have at least one log entry.
 	 * Includes form ID and title, with graceful handling for deleted forms.
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @return array<int, array{form_id: string, post_title: string|null}> Array of forms with logs.
 	 */
 	public function get_forms_with_logs(): array {

includes/Service/Notification/EmailAlertService.php

@@ -380,7 +380,7 @@ public function send_test_email( string $recipient ): bool {
 	 * Called when a submission permanently fails after exhausting all retries.
 	 * Checks settings and sends alert if individual alerts are enabled.
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @param int $log_id  Log entry ID.
 	 * @param int $form_id Contact Form 7 form ID.
 	 * @return void
@@ -416,7 +416,7 @@ public function maybe_send_individual_alert( int $log_id, int $form_id ): void {
 	 *
 	 * Sends an email notification for a single submission that failed permanently.
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @param int $log_id  Log entry ID.
 	 * @param int $form_id Contact Form 7 form ID.
 	 * @return void
@@ -490,7 +490,7 @@ private function send_individual_failure_alert( int $log_id, int $form_id ): voi
 	/**
 	 * Build individual failure alert email body HTML
 	 *
-	 * @since 2.0.0
+	 * @since 2.1.0
 	 * @param array<string, mixed> $log        Log entry data.
 	 * @param string               $form_title Form title.
 	 * @return string HTML email body.

phpstan-bootstrap.php

@@ -5,6 +5,7 @@
  * Defines WordPress constants that are not included in the stubs.
  * These constants are defined in wp-includes/default-constants.php
  *
+ * @since   2.1.0
  * @package ContactFormToAPI
  */
 

tests/Unit/Service/Api/ApiClientHookTest.php

@@ -2,6 +2,7 @@
 /**
  * Tests for ApiClient cf7_api_after_response hook
  *
+ * @since   2.1.0
  * @package SilverAssist\ContactFormToAPI\Tests\Unit\Service\Api
  */