Merge pull request #7 from Devotel/feature/contact-groups-api

feat: implement complete contact groups API

Author: parman-devotel

examples/README.md

@@ -26,6 +26,11 @@ This directory contains comprehensive examples for using the Devo Global Communi
 
 ### 👥 Management Resources
 - **`contacts_example.py`** - 🚧 **Placeholder** (Contact management)
+- **`contact_groups_example.py`** - ✅ **Complete Contact Groups API implementation**
+  - CRUD operations for contact groups
+  - Bulk operations and contact transfer
+  - Search and pagination features
+  - Metadata management and workflow examples
 
 ## 🚀 Getting Started
 
@@ -66,6 +71,9 @@ python examples/rcs_example.py
 python examples/email_example.py
 python examples/whatsapp_example.py
 python examples/contacts_example.py
+
+# Contact groups functionality (fully implemented)
+python examples/contact_groups_example.py
 ```
 
 ## 🌐 Omni-channel Messaging Examples (Fully Implemented)
@@ -145,6 +153,73 @@ The following examples show the structure and planned functionality but are not
 - **RCS**: Rich messaging, cards, carousels, capability checks
 - **Contacts**: CRUD operations, contact management
 
+## 📁 Contact Groups Examples (Fully Implemented)
+
+The contact groups resource is fully implemented with all CRUD operations:
+
+### 🔧 Available Functions
+1. **List Groups** - `client.contact_groups.list()`
+   - Uses GET `/api/v1/contacts-groups`
+   - Pagination and search support
+   - Field filtering capabilities
+
+2. **Create Group** - `client.contact_groups.create()`
+   - Uses POST `/api/v1/contacts-groups`
+   - Metadata and contact assignment
+   - Validation and error handling
+
+3. **Update Group** - `client.contact_groups.update()`
+   - Uses PUT `/api/v1/contacts-groups/{group_id}`
+   - Partial updates with metadata
+   - Flexible field modification
+
+4. **Get Group** - `client.contact_groups.get_by_id()`
+   - Uses GET `/api/v1/contacts-groups/{group_id}`
+   - Complete group information retrieval
+
+5. **Delete Group** - `client.contact_groups.delete_by_id()`
+   - Uses DELETE `/api/v1/contacts-groups/{group_id}`
+   - Individual group deletion with approval
+
+6. **Bulk Delete** - `client.contact_groups.delete_bulk()`
+   - Uses DELETE `/api/v1/contacts-groups`
+   - Multiple group deletion with contact transfer
+
+7. **Search Groups** - `client.contact_groups.search()`
+   - Uses GET `/api/v1/contacts-groups`
+   - Advanced search with field filtering
+
+### 💡 Key Features
+- **Complete CRUD Operations**: Full lifecycle management
+- **Bulk Operations**: Efficient multi-group operations
+- **Contact Transfer**: Safe deletion with contact preservation
+- **Metadata Support**: Custom metadata for business logic
+- **Search & Filter**: Advanced query capabilities
+- **Pagination**: Efficient large dataset handling
+
+### 📝 Example Usage
+```python
+from devo_global_comms_python.models.contact_groups import CreateContactsGroupDto
+
+# Create new contact group
+group_data = CreateContactsGroupDto(
+    name="VIP Customers",
+    description="High-value customers",
+    contact_ids=["contact1", "contact2"],
+    metadata={"priority": "high"}
+)
+group = client.contact_groups.create(group_data)
+
+# List with pagination
+groups = client.contact_groups.list(page=1, limit=10, search="VIP")
+
+# Search groups
+search_results = client.contact_groups.search(
+    query="priority",
+    fields=["name", "description"]
+)
+```
+
 ## 🔧 Configuration Notes
 
 ### Phone Numbers

examples/basic_usage.py

@@ -37,8 +37,12 @@ def main():
         resources.append(("💬 WhatsApp", "Placeholder", "whatsapp_example.py"))
     if hasattr(client, "contacts"):
         resources.append(("👥 Contacts", "Placeholder", "contacts_example.py"))
+    if hasattr(client, "contact_groups"):
+        resources.append(("🗂️  Contact Groups", "Implemented", "contact_groups_example.py"))
     if hasattr(client, "rcs"):
         resources.append(("🎴 RCS", "Placeholder", "rcs_example.py"))
+    if hasattr(client, "messages"):
+        resources.append(("📬 Messages", "Implemented", "omni_channel_example.py"))
 
     for resource, status, example_file in resources:
         print(f"   {resource:<12} - {status:<12} -> {example_file}")
@@ -66,11 +70,13 @@ def main():
     print("\n💡 Getting Started:")
     print("-" * 30)
     print("1. Run individual resource examples:")
-    print("   python examples/sms_example.py         # Complete SMS functionality")
-    print("   python examples/email_example.py       # Email examples (placeholder)")
-    print("   python examples/whatsapp_example.py    # WhatsApp examples (placeholder)")
-    print("   python examples/contacts_example.py    # Contact management (placeholder)")
-    print("   python examples/rcs_example.py         # RCS examples (placeholder)")
+    print("   python examples/sms_example.py              # Complete SMS functionality")
+    print("   python examples/contact_groups_example.py   # Complete Contact Groups functionality")
+    print("   python examples/omni_channel_example.py     # Complete Omni-channel messaging")
+    print("   python examples/email_example.py            # Email examples (placeholder)")
+    print("   python examples/whatsapp_example.py         # WhatsApp examples (placeholder)")
+    print("   python examples/contacts_example.py         # Contact management (placeholder)")
+    print("   python examples/rcs_example.py              # RCS examples (placeholder)")
     print()
     print("2. Quick SMS example:")
     print("   from devo_global_comms_python import DevoClient")
@@ -86,20 +92,24 @@ def main():
     print("-" * 30)
     print("Would you like to run a specific example?")
     print("1. SMS Example (full functionality)")
-    print("2. Email Example (placeholder)")
-    print("3. WhatsApp Example (placeholder)")
-    print("4. Contacts Example (placeholder)")
-    print("5. RCS Example (placeholder)")
+    print("2. Contact Groups Example (full functionality)")
+    print("3. Omni-channel Messaging Example (full functionality)")
+    print("4. Email Example (placeholder)")
+    print("5. WhatsApp Example (placeholder)")
+    print("6. Contacts Example (placeholder)")
+    print("7. RCS Example (placeholder)")
     print("0. Exit")
 
     try:
-        choice = input("\nEnter your choice (0-5): ").strip()
+        choice = input("\nEnter your choice (0-7): ").strip()
         example_files = {
             "1": "sms_example.py",
-            "2": "email_example.py",
-            "3": "whatsapp_example.py",
-            "4": "contacts_example.py",
-            "5": "rcs_example.py",
+            "2": "contact_groups_example.py",
+            "3": "omni_channel_example.py",
+            "4": "email_example.py",
+            "5": "whatsapp_example.py",
+            "6": "contacts_example.py",
+            "7": "rcs_example.py",
         }
 
         if choice in example_files: