general documentation updated - broken links adjusted; obsolete files deleted; connector-specific documentations

Author: tsutomi

.github/README.md

@@ -6,16 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![NuGet](https://img.shields.io/badge/NuGet-Available-blue)](https://www.nuget.org/)
 
-A modern, extensible messaging framework for .NET that provides a unified abstraction layer for various messaging providers including SMS, email, and push notifications. The framework offers strong type safety, comprehensive validation, and flexible connector architecture.
+A modern, extensible messaging framework for .NET that provides a unified abstraction layer for various messaging providers including SMS, email, WhatsApp, and push notifications. The framework offers strong type safety, comprehensive validation, and flexible connector architecture.
 
 ## 🚀 Motivation
 
-Modern applications often need to send notifications through multiple channels (SMS, email, push notifications, webhooks). Each provider has different APIs, authentication methods, and message formats. The Deveel Messaging Framework solves this by:
+Modern applications often need to send notifications through multiple channels (SMS, email, WhatsApp, push notifications, webhooks). Each provider has different APIs, authentication methods, and message formats. The Deveel Messaging Framework solves this by:
 
 - **Unified API**: Single interface for all messaging providers
 - **Type Safety**: Strongly-typed endpoints and configurations prevent runtime errors
 - **Extensibility**: Easy to add new providers and message types
 - **Validation**: Built-in message and configuration validation
+- **Webhook Support**: Comprehensive webhook handling for message receiving and status updates
 - **Testability**: Comprehensive mocking and testing support
 - **Performance**: Async/await throughout with efficient resource usage
 
@@ -25,8 +26,9 @@ Modern applications often need to send notifications through multiple channels (
 |---------|-------------|-------|
 | `Deveel.Messaging.Abstractions` | Core messaging abstractions and models | [![NuGet](https://img.shields.io/nuget/v/Deveel.Messaging.Abstractions.svg)](https://www.nuget.org/packages/Deveel.Messaging.Abstractions/) |
 | `Deveel.Messaging.Connector.Abstractions` | Base classes and interfaces for connectors | [![NuGet](https://img.shields.io/nuget/v/Deveel.Messaging.Connector.Abstractions.svg)](https://www.nuget.org/packages/Deveel.Messaging.Connector.Abstractions/) |
-| `Deveel.Messaging.Connector.Twilio` | Twilio SMS connector implementation | [![NuGet](https://img.shields.io/nuget/v/Deveel.Messaging.Connector.Twilio.svg)](https://www.nuget.org/packages/Deveel.Messaging.Connector.Twilio/) |
+| `Deveel.Messaging.Connector.Twilio` | Twilio SMS & WhatsApp connector implementation | [![NuGet](https://img.shields.io/nuget/v/Deveel.Messaging.Connector.Twilio.svg)](https://www.nuget.org/packages/Deveel.Messaging.Connector.Twilio/) |
 | `Deveel.Messaging.Connector.Sendgrid` | SendGrid email connector implementation | [![NuGet](https://img.shields.io/nuget/v/Deveel.Messaging.Connector.Sendgrid.svg)](https://www.nuget.org/packages/Deveel.Messaging.Connector.Sendgrid/) |
+| `Deveel.Messaging.Connector.Firebase` | Firebase Cloud Messaging (FCM) push notification connector | [![NuGet](https://img.shields.io/nuget/v/Deveel.Messaging.Connector.Firebase.svg)](https://www.nuget.org/packages/Deveel.Messaging.Connector.Firebase/) |
 
 ## 🔧 Installation
 
@@ -43,11 +45,14 @@ dotnet add package Deveel.Messaging.Connector.Abstractions
 ### Install Provider-Specific Connectors
 
 ```bash
-# Twilio SMS connector
+# Twilio SMS & WhatsApp connector
 dotnet add package Deveel.Messaging.Connector.Twilio
 
 # SendGrid email connector
 dotnet add package Deveel.Messaging.Connector.Sendgrid
+
+# Firebase Cloud Messaging (FCM) push notifications
+dotnet add package Deveel.Messaging.Connector.Firebase
 ```
 
 ## 🏁 Quick Start
@@ -98,11 +103,12 @@ if (result.IsSuccess)
 }
 ```
 
-### 3. SMS Example with Twilio
+### 3. SMS & WhatsApp with Twilio
 
 ```csharp
+// SMS
 var smsSchema = new ChannelSchema("Twilio", "SMS", "2.1.0")
-    .WithCapabilities(ChannelCapability.SendMessages | ChannelCapability.MessageStatusQuery)
+    .WithCapabilities(ChannelCapability.SendMessages | ChannelCapability.MessageStatusQuery | ChannelCapability.ReceiveMessages)
     .AddParameter(new ChannelParameter("AccountSid", ParameterType.String) { IsRequired = true })
     .AddParameter(new ChannelParameter("AuthToken", ParameterType.String) { IsRequired = true, IsSensitive = true })
     .AddContentType(MessageContentType.PlainText)
@@ -115,9 +121,56 @@ var smsMessage = new MessageBuilder()
     .WithTextContent("Your verification code is: 123456")
     .Message;
 
-var twilioConnector = new TwilioConnector(smsSchema);
-await twilioConnector.InitializeAsync(cancellationToken);
-var smsResult = await twilioConnector.SendMessageAsync(smsMessage, cancellationToken);
+// WhatsApp Business
+var whatsAppSchema = new ChannelSchema("Twilio", "WhatsApp", "2.1.0")
+    .WithCapabilities(
+        ChannelCapability.SendMessages | 
+        ChannelCapability.ReceiveMessages | 
+        ChannelCapability.MessageStatusQuery |
+        ChannelCapability.Templates |
+        ChannelCapability.MediaAttachments)
+    .AddParameter(new ChannelParameter("AccountSid", ParameterType.String) { IsRequired = true })
+    .AddParameter(new ChannelParameter("AuthToken", ParameterType.String) { IsRequired = true, IsSensitive = true })
+    .AddContentType(MessageContentType.PlainText)
+    .AddContentType(MessageContentType.Template)
+    .AddContentType(MessageContentType.Media)
+    .AllowsMessageEndpoint(EndpointType.PhoneNumber);
+
+var whatsAppMessage = new MessageBuilder()
+    .WithId("whatsapp-notification-001")
+    .WithPhoneSender("whatsapp:+1234567890")
+    .WithPhoneReceiver("whatsapp:+0987654321")
+    .WithTextContent("Hello from WhatsApp Business!")
+    .Message;
+```
+
+### 4. Push Notifications with Firebase
+
+```csharp
+var firebaseSchema = new ChannelSchema("Firebase", "Push", "1.0.0")
+    .WithCapabilities(
+        ChannelCapability.SendMessages | 
+        ChannelCapability.BulkMessaging |
+        ChannelCapability.Templates |
+        ChannelCapability.HealthCheck)
+    .AddParameter(new ChannelParameter("ProjectId", ParameterType.String) { IsRequired = true })
+    .AddParameter(new ChannelParameter("ServiceAccountKey", ParameterType.String) { IsRequired = true, IsSensitive = true })
+    .AddContentType(MessageContentType.PlainText)
+    .AllowsMessageEndpoint(EndpointType.DeviceId)
+    .AllowsMessageEndpoint(EndpointType.Topic);
+
+var pushMessage = new MessageBuilder()
+    .WithId("push-notification-001")
+    .WithDeviceReceiver("device-token-123")
+    .WithTextContent("You have a new message!")
+    .WithProperty("Title", "New Message")
+    .WithProperty("ImageUrl", "https://example.com/notification-image.png")
+    .WithProperty("ClickAction", "OPEN_MESSAGE")
+    .Message;
+
+var firebaseConnector = new FirebasePushConnector(firebaseSchema);
+await firebaseConnector.InitializeAsync(cancellationToken);
+var pushResult = await firebaseConnector.SendMessageAsync(pushMessage, cancellationToken);
 ```
 
 ## 🎯 Core Features
@@ -130,6 +183,8 @@ Use the `EndpointType` enumeration for type-safe endpoint configuration:
 // Type-safe endpoint creation
 var emailEndpoint = Endpoint.EmailAddress("user@example.com");
 var phoneEndpoint = Endpoint.PhoneNumber("+1234567890");
+var deviceEndpoint = Endpoint.DeviceId("firebase-device-token");
+var topicEndpoint = Endpoint.Topic("news-updates");
 var webhookEndpoint = Endpoint.Url("https://api.example.com/webhook");
 
 // Builder pattern with type safety
@@ -148,15 +203,59 @@ Support for various content types and templating:
 // HTML content
 .WithHtmlContent("<h1>Welcome</h1><p>{{username}}, thanks for joining!</p>")
 
-// Template content with parameters
+// Template content with parameters (WhatsApp Business, Firebase)
 .WithTemplateContent("welcome-template", new { username = "John", company = "Acme Corp" })
 
+// Media content with attachments
+.WithMediaContent("https://example.com/image.jpg", "image/jpeg", "Welcome Image")
+
 // Multipart content with attachments
 .WithMultipartContent(content => content
     .AddTextPart("Please find the report attached.")
     .AddAttachment("report.pdf", pdfBytes, "application/pdf"))
 ```
 
+### Webhook Support for Message Receiving
+
+The framework now includes comprehensive webhook support for receiving messages and status updates:
+
+```csharp
+// Receive incoming messages via webhook
+public class MessageWebhookController : ControllerBase
+{
+    [HttpPost("webhook/twilio/sms")]
+    public async Task<IActionResult> ReceiveSms([FromForm] Dictionary<string, string> formData)
+    {
+        var messageSource = MessageSource.FromFormData(formData);
+        var result = await _twilioConnector.ReceiveMessagesAsync(messageSource, cancellationToken);
+        
+        if (result.IsSuccess)
+        {
+            foreach (var message in result.Value.Messages)
+            {
+                await ProcessIncomingMessage(message);
+            }
+        }
+        
+        return Ok();
+    }
+
+    [HttpPost("webhook/twilio/status")]
+    public async Task<IActionResult> ReceiveStatus([FromForm] Dictionary<string, string> formData)
+    {
+        var messageSource = MessageSource.FromFormData(formData);
+        var result = await _twilioConnector.ReceiveMessageStatusAsync(messageSource, cancellationToken);
+        
+        if (result.IsSuccess)
+        {
+            await ProcessStatusUpdate(result.Value);
+        }
+        
+        return Ok();
+    }
+}
+```
+
 ### Connector Capabilities
 
 Declare and validate connector capabilities:
@@ -165,14 +264,33 @@ Declare and validate connector capabilities:
 var schema = new ChannelSchema("Provider", "Type", "1.0.0")
     .WithCapabilities(
         ChannelCapability.SendMessages |        // Can send messages
-        ChannelCapability.ReceiveMessages |     // Can receive messages
+        ChannelCapability.ReceiveMessages |     // Can receive messages via webhooks
         ChannelCapability.MessageStatusQuery |  // Can track delivery status
         ChannelCapability.BulkMessaging |       // Supports batch operations
         ChannelCapability.Templates |           // Supports templating
         ChannelCapability.MediaAttachments |    // Supports file attachments
         ChannelCapability.HealthCheck)          // Provides health monitoring
 ```
 
+### Batch Processing and Performance
+
+```csharp
+// Send multiple messages efficiently
+var batch = new MessageBatch(messages);
+var batchResult = await connector.SendBatchAsync(batch, cancellationToken);
+
+// Firebase multicast for efficient push notifications
+var tokens = new[] { "token1", "token2", "token3" };
+var multicastMessages = tokens.Select(token => 
+    new MessageBuilder()
+        .WithDeviceReceiver(token)
+        .WithTextContent("Broadcast message")
+        .Message);
+
+var batch = new MessageBatch(multicastMessages);
+var result = await firebaseConnector.SendBatchAsync(batch, cancellationToken);
+```
+
 ### Error Handling and Results
 
 Comprehensive error handling with detailed result objects:
@@ -208,13 +326,13 @@ public class CustomConnector : ChannelConnectorBase
         return ConnectorResult<bool>.Success(true);
     }
 
-    protected override async Task<ConnectorResult<MessageResult>> SendMessageCoreAsync(
+    protected override async Task<ConnectorResult<SendResult>> SendMessageCoreAsync(
         IMessage message, CancellationToken cancellationToken)
     {
         // Implement your message sending logic
         var messageId = await SendToProvider(message);
-        return ConnectorResult<MessageResult>.Success(
-            new MessageResult(messageId, MessageStatus.Sent));
+        return ConnectorResult<SendResult>.Success(
+            new SendResult(message.Id, messageId));
     }
 
     // Implement other abstract methods...
@@ -230,6 +348,35 @@ public class CustomConnector : ChannelConnectorBase
 - **[Endpoint Type Safety Guide](docs/EndpointType-Usage.md)** - Working with typed endpoints
 - **[Migration Guide](docs/migration-guide.md)** - Upgrading from previous versions
 
+## 🌟 Latest Features & Improvements
+
+### Firebase Cloud Messaging Support
+- **NEW**: Complete Firebase Cloud Messaging (FCM) connector
+- **Push Notifications**: Device tokens and topic messaging
+- **Multicast Support**: Efficient batch delivery to multiple devices
+- **Platform-Specific**: Android, iOS (APNS), and Web Push configurations
+- **Rich Notifications**: Images, actions, and custom data payloads
+
+### Enhanced WhatsApp Business Integration
+- **Webhook Support**: Complete JSON and form-data webhook handling
+- **Message Receiving**: Incoming message processing with WhatsApp-specific fields
+- **Status Updates**: Real-time delivery status tracking including read receipts
+- **Interactive Elements**: Button responses, list selections, and template interactions
+- **Business Features**: Profile names, business display names, and verified accounts
+- **Media Support**: Images, documents, audio, and video attachments
+
+### Improved Message Processing
+- **Batch Operations**: Efficient bulk message sending across all connectors
+- **Status Tracking**: Comprehensive message status queries and webhook updates
+- **Template Support**: WhatsApp Business templates and Firebase notification templates
+- **Content Types**: Enhanced support for media, templates, and multipart content
+
+### Performance & Reliability
+- **Connection Pooling**: Optimized HTTP client usage
+- **Health Monitoring**: Built-in health checks for all connectors
+- **Error Resilience**: Improved error handling and retry mechanisms
+- **Resource Management**: Better async patterns and disposal handling
+
 ## 🔗 GitHub Packages
 
 This project publishes packages to both NuGet.org and GitHub Packages. To use GitHub Packages:
@@ -251,15 +398,16 @@ dotnet add package Deveel.Messaging.Abstractions --source github-deveel
 
 ## 🧪 Testing
 
-The framework includes comprehensive test suites:
+The framework includes comprehensive test suites with over 500 tests:
 
 ```bash
 # Run all tests
 dotnet test
 
-# Run tests for specific project
+# Run tests for specific connectors
 dotnet test test/Deveel.Messaging.Abstractions.XUnit
 dotnet test test/Deveel.Messaging.Connector.Twilio.XUnit
+dotnet test test/Deveel.Messaging.Connector.Firebase.XUnit
 
 # Run with coverage
 dotnet test --collect:"XPlat Code Coverage"
@@ -271,7 +419,7 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ### Development Requirements
 
-- **.NET 8.0 SDK** or later
+- **.NET 8.0 SDK** or later (.NET 9.0 recommended)
 - **Visual Studio 2022** or **VS Code** with C# extension
 - **Git** for source control