d365fo-client 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

d365fo_client/models.py

@@ -4,7 +4,7 @@ import hashlib
 import json
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from enum import Enum
+from enum import Enum, StrEnum
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
 
@@ -12,9 +12,19 @@ from .utils import get_environment_cache_directory
 
 if TYPE_CHECKING:
     from typing import ForwardRef
+    from .credential_sources import CredentialSource
 
 
-class EntityCategory(Enum):
+def _ensure_str_for_json(field):
+    """Ensure field is JSON-serializable as string.
+    
+    StrEnum fields automatically serialize as strings, but this handles
+    the edge case where a field might be None or already a string.
+    """
+    return field  # StrEnum automatically converts to string, None stays None
+
+
+class EntityCategory(StrEnum):
     """D365 F&O Entity Categories"""
 
     MASTER = "Master"
@@ -25,7 +35,7 @@ class EntityCategory(Enum):
     PARAMETERS = "Parameters"
 
 
-class ODataXppType(Enum):
+class ODataXppType(StrEnum):
     """D365 F&O OData XPP Types"""
 
     CONTAINER = "Container"
@@ -42,7 +52,7 @@ class ODataXppType(Enum):
     VOID = "Void"
 
 
-class ODataBindingKind(Enum):
+class ODataBindingKind(StrEnum):
     """D365 F&O Action Binding Types"""
 
     BOUND_TO_ENTITY_INSTANCE = "BoundToEntityInstance"
@@ -50,16 +60,19 @@ class ODataBindingKind(Enum):
     UNBOUND = "Unbound"
 
 
-class SyncStrategy(Enum):
+class SyncStrategy(StrEnum):
     """Metadata synchronization strategies"""
 
     FULL = "full"
     INCREMENTAL = "incremental"
     ENTITIES_ONLY = "entities_only"
+    LABELS_ONLY = "labels_only"
     SHARING_MODE = "sharing_mode"
+    FULL_WITHOUT_LABELS = "full_without_labels"
+
 
 
-class Cardinality(Enum):
+class Cardinality(StrEnum):
     """Navigation Property Cardinality"""
 
     SINGLE = "Single"
@@ -71,6 +84,7 @@ class FOClientConfig:
     """Configuration for F&O Client"""
 
     base_url: str
+    auth_mode: Optional[str] = "defaut" # default | client_credentials
     client_id: Optional[str] = None
     client_secret: Optional[str] = None
     tenant_id: Optional[str] = None
@@ -89,6 +103,8 @@ class FOClientConfig:
     max_memory_cache_size: int = 1000
     # Cache-first behavior configuration
     use_cache_first: bool = True
+    # Credential source configuration
+    credential_source: Optional["CredentialSource"] = None
 
     def __post_init__(self):
         """Post-initialization to set default cache directory if not provided."""
@@ -191,7 +207,7 @@ class PublicEntityActionInfo:
     def to_dict(self) -> Dict[str, Any]:
         return {
             "name": self.name,
-            "binding_kind": self.binding_kind.value,  # Convert enum to string value
+            "binding_kind": self.binding_kind,  # StrEnum automatically serializes as string
             "parameters": [param.to_dict() for param in self.parameters],
             "return_type": self.return_type.to_dict() if self.return_type else None,
             "field_lookup": self.field_lookup,
@@ -221,7 +237,7 @@ class DataEntityInfo:
             "label_text": self.label_text,
             "data_service_enabled": self.data_service_enabled,
             "data_management_enabled": self.data_management_enabled,
-            "entity_category": self.entity_category.value if self.entity_category else None,
+            "entity_category": self.entity_category,  # StrEnum automatically serializes as string
             "is_read_only": self.is_read_only,
         }
 
@@ -438,7 +454,7 @@ class NavigationPropertyInfo:
             "name": self.name,
             "related_entity": self.related_entity,
             "related_relation_name": self.related_relation_name,
-            "cardinality": self.cardinality.value,  # Convert enum to string value
+            "cardinality": self.cardinality,  # StrEnum automatically serializes as string
             "constraints": [constraint.to_dict() for constraint in self.constraints],
         }
 
@@ -503,7 +519,7 @@ class ActionInfo:
     def to_dict(self) -> Dict[str, Any]:
         return {
             "name": self.name,
-            "binding_kind": self.binding_kind.value,  # Serialize enum as string value
+            "binding_kind": self.binding_kind,  # StrEnum automatically serializes as string
             "entity_name": self.entity_name,
             "entity_set_name": self.entity_set_name,
             "parameters": [param.to_dict() for param in self.parameters],
@@ -729,9 +745,9 @@ class GlobalVersionInfo:
     first_seen_at: datetime
     last_used_at: datetime
     reference_count: int
-    sample_modules: List[ModuleVersionInfo] = field(
+    modules: List[ModuleVersionInfo] = field(
         default_factory=list
-    )  # Sample for debugging
+    )  # Modules for debugging
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for JSON serialization"""
@@ -742,7 +758,7 @@ class GlobalVersionInfo:
             "first_seen_at": self.first_seen_at.isoformat(),
             "last_used_at": self.last_used_at.isoformat(),
             "reference_count": self.reference_count,
-            "sample_modules": [module.to_dict() for module in self.sample_modules],
+            "modules": [module.to_dict() for module in self.modules],
         }
 
 
@@ -860,3 +876,15 @@ class SyncResult:
     action_count: int
     enumeration_count: int
     label_count: int
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            "success": self.success,
+            "error": self.error,
+            "duration_ms": self.duration_ms,
+            "entity_count": self.entity_count,
+            "action_count": self.action_count,
+            "enumeration_count": self.enumeration_count,
+            "label_count": self.label_count
+        }

d365fo_client/profile_manager.py

@@ -7,13 +7,15 @@ import logging
 import os
 from dataclasses import asdict
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 import yaml
 
 from .config import ConfigManager
 from .models import FOClientConfig
 from .profiles import Profile
+if TYPE_CHECKING:
+    from .credential_sources import CredentialSource
 
 logger = logging.getLogger(__name__)
 
@@ -76,6 +78,8 @@ class ProfileManager:
         language: str = "en-US",
         cache_dir: Optional[str] = None,
         description: Optional[str] = None,
+        credential_source: Optional["CredentialSource"] = None
+
     ) -> bool:
         """Create a new profile.
 
@@ -93,6 +97,7 @@ class ProfileManager:
             language: Default language code
             cache_dir: Cache directory path
             description: Profile description (stored separately from CLI profile)
+            credential_source: Credential source configuration
 
         Returns:
             True if created successfully
@@ -120,6 +125,7 @@ class ProfileManager:
                 cache_dir=cache_dir,
                 description=description,
                 output_format="table",  # Default for CLI compatibility
+                credential_source=credential_source
             )
 
             self.config_manager.save_profile(profile)

d365fo_client/profiles.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 if TYPE_CHECKING:
     from .models import FOClientConfig
+    from .credential_sources import CredentialSource
 
 logger = logging.getLogger(__name__)
 
@@ -24,8 +25,10 @@ class Profile:
     client_id: Optional[str] = None
     client_secret: Optional[str] = None
     tenant_id: Optional[str] = None
+    use_default_credentials: Optional[bool] = None  # None means derive from auth_mode
     verify_ssl: bool = True
     timeout: int = 60
+    credential_source: Optional["CredentialSource"] = None
 
     # Cache settings
     use_label_cache: bool = True
@@ -43,18 +46,26 @@ class Profile:
         """Convert profile to FOClientConfig."""
         from .models import FOClientConfig
 
+        # Determine use_default_credentials: explicit setting takes precedence over auth_mode
+        if self.use_default_credentials is not None:
+            use_default_creds = self.use_default_credentials
+        else:
+            use_default_creds = self.auth_mode == "default"
+
         return FOClientConfig(
             base_url=self.base_url,
+            auth_mode=self.auth_mode,
             client_id=self.client_id,
             client_secret=self.client_secret,
             tenant_id=self.tenant_id,
-            use_default_credentials=self.auth_mode == "default",
+            use_default_credentials=use_default_creds,
             timeout=self.timeout,
             verify_ssl=self.verify_ssl,
             use_label_cache=self.use_label_cache,
             label_cache_expiry_minutes=self.label_cache_expiry_minutes,
             use_cache_first=self.use_cache_first,
             metadata_cache_dir=self.cache_dir,
+            credential_source=self.credential_source,
         )
 
     def validate(self) -> List[str]:
@@ -100,6 +111,7 @@ class Profile:
             "client_id": None,
             "client_secret": None,
             "tenant_id": None,
+            "use_default_credentials": None,
             "verify_ssl": True,
             "timeout": 60,
             "use_label_cache": True,
@@ -108,6 +120,7 @@ class Profile:
             "cache_dir": None,
             "language": "en-US",
             "output_format": "table",
+            "credential_source": None,
         }
 
         for key, default_value in defaults.items():
@@ -119,6 +132,16 @@ class Profile:
             k: v for k, v in migrated_data.items() if k in cls.__dataclass_fields__
         }
 
+        # Handle credential_source deserialization
+        if "credential_source" in valid_params and valid_params["credential_source"] is not None:
+            from .credential_sources import CredentialSource
+            credential_source_data = valid_params["credential_source"]
+            try:
+                valid_params["credential_source"] = CredentialSource.from_dict(credential_source_data)
+            except Exception as e:
+                logger.error(f"Error deserializing credential_source: {e}")
+                valid_params["credential_source"] = None
+
         try:
             return cls(**valid_params)
         except Exception as e:
@@ -151,6 +174,10 @@ class Profile:
         data = asdict(self)
         data.pop("name", None)
 
+        # Handle credential_source serialization
+        if self.credential_source is not None:
+            data["credential_source"] = self.credential_source.to_dict()
+
         return data
 
     def clone(self, name: str, **overrides) -> "Profile":

d365fo_client/sync_models.py

@@ -0,0 +1,181 @@
+"""Enhanced sync models for progress reporting and session management."""
+
+import uuid
+from datetime import datetime, timezone
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Dict, List, Optional, Callable, Set
+
+from .models import SyncStrategy, SyncResult
+
+
+class SyncStatus(StrEnum):
+    """Sync operation status"""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    PAUSED = "paused"
+
+
+class SyncPhase(StrEnum):
+    """Detailed sync phases"""
+    INITIALIZING = "initializing"
+    VERSION_CHECK = "version_check"
+    ENTITIES = "entities"
+    SCHEMAS = "schemas"
+    ENUMERATIONS = "enumerations"
+    LABELS = "labels"
+    INDEXING = "indexing"
+    FINALIZING = "finalizing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class SyncActivity:
+    """Individual sync activity within a phase"""
+    name: str
+    status: SyncStatus
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    progress_percent: float = 0.0
+    items_processed: int = 0
+    items_total: Optional[int] = None
+    current_item: Optional[str] = None
+    error: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            "name": self.name,
+            "status": self.status,
+            "start_time": self.start_time.isoformat() if self.start_time else None,
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "progress_percent": self.progress_percent,
+            "items_processed": self.items_processed,
+            "items_total": self.items_total,
+            "current_item": self.current_item,
+            "error": self.error
+        }
+
+
+@dataclass
+class SyncSession:
+    """Complete sync session with detailed tracking"""
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    global_version_id: int = 0
+    strategy: SyncStrategy = SyncStrategy.FULL
+    status: SyncStatus = SyncStatus.PENDING
+    
+    # Overall progress
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    estimated_completion: Optional[datetime] = None
+    progress_percent: float = 0.0
+    
+    # Current state
+    current_phase: SyncPhase = SyncPhase.INITIALIZING
+    current_activity: Optional[str] = None
+    
+    # Phase tracking
+    phases: Dict[SyncPhase, SyncActivity] = field(default_factory=dict)
+    
+    # Results
+    result: Optional[SyncResult] = None
+    error: Optional[str] = None
+    
+    # Metadata
+    initiated_by: str = "system"  # user, system, scheduled, mcp
+    can_cancel: bool = True
+    
+    # Collected label IDs during sync for efficient label processing
+    collected_label_ids: Set[str] = field(default_factory=set)
+    
+    def get_overall_progress(self) -> float:
+        """Calculate overall progress across all phases"""
+        if not self.phases:
+            return 0.0
+            
+        total_weight = len(self.phases)
+        completed_weight = sum(
+            1.0 if activity.status == SyncStatus.COMPLETED 
+            else activity.progress_percent / 100.0
+            for activity in self.phases.values()
+        )
+        return min(100.0, (completed_weight / total_weight) * 100.0)
+    
+    def get_current_activity_detail(self) -> Optional[SyncActivity]:
+        """Get current running activity details"""
+        if self.current_phase in self.phases:
+            return self.phases[self.current_phase]
+        return None
+    
+    def estimate_remaining_time(self) -> Optional[int]:
+        """Estimate remaining time in seconds"""
+        if not self.start_time or self.progress_percent <= 0:
+            return None
+            
+        elapsed = (datetime.now(timezone.utc) - self.start_time).total_seconds()
+        if self.progress_percent >= 100:
+            return 0
+            
+        estimated_total = elapsed / (self.progress_percent / 100.0)
+        return max(0, int(estimated_total - elapsed))
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            "session_id": self.session_id,
+            "global_version_id": self.global_version_id,
+            "strategy": self.strategy,
+            "status": self.status,
+            "start_time": self.start_time.isoformat() if self.start_time else None,
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "estimated_completion": self.estimated_completion.isoformat() if self.estimated_completion else None,
+            "progress_percent": self.progress_percent,
+            "current_phase": self.current_phase,
+            "current_activity": self.current_activity,
+            "phases": {
+                phase.value: activity.to_dict()
+                for phase, activity in self.phases.items()
+            },
+            "result": self.result.to_dict() if self.result and hasattr(self.result, 'to_dict') else None,
+            "error": self.error,
+            "initiated_by": self.initiated_by,
+            "can_cancel": self.can_cancel,
+            "estimated_remaining_seconds": self.estimate_remaining_time()
+        }
+
+
+@dataclass
+class SyncSessionSummary:
+    """Lightweight sync session summary for listing"""
+    session_id: str
+    global_version_id: int
+    strategy: SyncStrategy
+    status: SyncStatus
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    progress_percent: float = 0.0
+    current_phase: SyncPhase = SyncPhase.INITIALIZING
+    current_activity: Optional[str] = None
+    initiated_by: str = "system"
+    duration_seconds: Optional[int] = None
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            "session_id": self.session_id,
+            "global_version_id": self.global_version_id,
+            "strategy": self.strategy,
+            "status": self.status,
+            "start_time": self.start_time.isoformat() if self.start_time else None,
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "progress_percent": self.progress_percent,
+            "current_phase": self.current_phase,
+            "current_activity": self.current_activity,
+            "initiated_by": self.initiated_by,
+            "duration_seconds": self.duration_seconds
+        }

{d365fo_client-0.2.1.dist-info → d365fo_client-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: d365fo-client
-Version: 0.2.1
+Version: 0.2.3
 Summary: Microsoft Dynamics 365 Finance & Operations client
 Author-email: Muhammad Afzaal <mo@thedataguy.pro>
 License-Expression: MIT
@@ -22,6 +22,7 @@ License-File: LICENSE
 Requires-Dist: aiohttp>=3.10.0
 Requires-Dist: aiofiles>=24.1.0
 Requires-Dist: azure-identity>=1.19.0
+Requires-Dist: azure-keyvault-secrets>=4.8.0
 Requires-Dist: requests>=2.32.0
 Requires-Dist: aiosqlite>=0.19.0
 Requires-Dist: cachetools>=6.1.0
@@ -50,7 +51,7 @@ A comprehensive Python client library and MCP server for Microsoft Dynamics 365
 - 🏷️ **Label Operations V2**: Multilingual label caching with performance improvements and async support
 - 🔍 **Advanced Querying**: Support for all OData query parameters ($select, $filter, $expand, etc.)
 - ⚡ **Action Execution**: Execute bound and unbound OData actions with comprehensive parameter handling
-- 🔒 **Authentication**: Azure AD integration with default credentials and service principal support
+- 🔒 **Authentication**: Azure AD integration with default credentials, service principal, and Azure Key Vault support
 - 💾 **Intelligent Caching**: Cross-environment cache sharing with module-based version detection
 - 🌐 **Async/Await**: Modern async/await patterns with optimized session management
 - 📝 **Type Hints**: Full type annotation support with enhanced data models
@@ -58,6 +59,8 @@ A comprehensive Python client library and MCP server for Microsoft Dynamics 365
 - 🖥️ **Comprehensive CLI**: Hierarchical command-line interface for all D365 F&O operations
 - 🧪 **Multi-tier Testing**: Mock, sandbox, and live integration testing framework (17/17 tests passing)
 - 📋 **Metadata Scripts**: PowerShell and Python utilities for entity, enumeration, and action discovery
+- 🔐 **Enhanced Credential Management**: Support for Azure Key Vault and multiple credential sources
+- 📊 **Advanced Sync Management**: Session-based synchronization with detailed progress tracking
 
 ## Installation
 
@@ -73,6 +76,13 @@ uv sync  # Installs with exact dependencies from uv.lock
 
 **Note**: The package includes MCP (Model Context Protocol) dependencies by default, enabling AI assistant integration. Both `d365fo-client` CLI and `d365fo-mcp-server` commands will be available after installation.
 
+**Breaking Change in v0.2.3**: Environment variable names have been updated for consistency:
+- `AZURE_CLIENT_ID` → `D365FO_CLIENT_ID`
+- `AZURE_CLIENT_SECRET` → `D365FO_CLIENT_SECRET`  
+- `AZURE_TENANT_ID` → `D365FO_TENANT_ID`
+
+Please update your environment variables accordingly when upgrading.
+
 ## Quick Start
 
 ## Command Line Interface (CLI)
@@ -158,9 +168,9 @@ profiles:
     
   development:
     base_url: "https://dev.dynamics.com" 
-    client_id: "${AZURE_CLIENT_ID}"
-    client_secret: "${AZURE_CLIENT_SECRET}"
-    tenant_id: "${AZURE_TENANT_ID}"
+    client_id: "${D365FO_CLIENT_ID}"
+    client_secret: "${D365FO_CLIENT_SECRET}"
+    tenant_id: "${D365FO_TENANT_ID}"
     use_cache_first: true
 
 default_profile: "development"
@@ -262,7 +272,14 @@ config = FOClientConfig(
     use_default_credentials=False
 )
 
-# Option 3: With custom settings
+# Option 3: Azure Key Vault integration (New in v0.2.3)
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    credential_source="keyvault",  # Use Azure Key Vault for credentials
+    keyvault_url="https://your-keyvault.vault.azure.net/"
+)
+
+# Option 4: With custom settings
 config = FOClientConfig(
     base_url="https://your-fo-environment.dynamics.com",
     use_default_credentials=True,
@@ -462,7 +479,9 @@ d365fo-client/
 │       ├── metadata.py          # Legacy metadata operations
 │       ├── metadata_api.py      # Metadata API client
 │       ├── metadata_cache.py    # Metadata caching layer V2
-│       ├── metadata_sync.py     # Metadata synchronization V2
+│       ├── metadata_sync.py     # Metadata synchronization V2 with session management
+│       ├── sync_session.py      # Enhanced sync session management (New in v0.2.3)
+│       ├── credential_manager.py # Credential source management (New in v0.2.3)
 │       ├── labels.py            # Label operations V2
 │       ├── profiles.py          # Profile data models
 │       ├── profile_manager.py   # Profile management
@@ -519,6 +538,8 @@ d365fo-client/
 | `client_secret` | str | None | Azure AD client secret |
 | `tenant_id` | str | None | Azure AD tenant ID |
 | `use_default_credentials` | bool | True | Use Azure Default Credential |
+| `credential_source` | str | "environment" | Credential source: "environment", "keyvault" |
+| `keyvault_url` | str | None | Azure Key Vault URL for credential storage |
 | `verify_ssl` | bool | False | Verify SSL certificates |
 | `timeout` | int | 30 | Request timeout in seconds |
 | `metadata_cache_dir` | str | Platform-specific user cache | Metadata cache directory |
@@ -619,9 +640,9 @@ cp tests/integration/.env.template tests/integration/.env
 # Edit .env file with your settings:
 INTEGRATION_TEST_LEVEL=sandbox
 D365FO_SANDBOX_BASE_URL=https://your-test.dynamics.com
-AZURE_CLIENT_ID=your-client-id
-AZURE_CLIENT_SECRET=your-client-secret
-AZURE_TENANT_ID=your-tenant-id
+D365FO_CLIENT_ID=your-client-id
+D365FO_CLIENT_SECRET=your-client-secret
+D365FO_TENANT_ID=your-tenant-id
 ```
 
 #### Available Commands
@@ -707,9 +728,9 @@ pip install d365fo-client
 
 # Set up environment variables
 export D365FO_BASE_URL="https://your-environment.dynamics.com"
-export AZURE_CLIENT_ID="your-client-id"          # Optional with default credentials
-export AZURE_CLIENT_SECRET="your-client-secret"  # Optional with default credentials  
-export AZURE_TENANT_ID="your-tenant-id"          # Optional with default credentials
+export D365FO_CLIENT_ID="your-client-id"          # Optional with default credentials
+export D365FO_CLIENT_SECRET="your-client-secret"  # Optional with default credentials  
+export D365FO_TENANT_ID="your-tenant-id"          # Optional with default credentials
 
 # Start the MCP server
 d365fo-mcp-server
@@ -857,9 +878,19 @@ For service principal authentication:
 
 ```bash
 export D365FO_BASE_URL="https://your-environment.dynamics.com"
-export AZURE_CLIENT_ID="your-client-id"
-export AZURE_CLIENT_SECRET="your-client-secret"
-export AZURE_TENANT_ID="your-tenant-id"
+export D365FO_CLIENT_ID="your-client-id"
+export D365FO_CLIENT_SECRET="your-client-secret"
+export D365FO_TENANT_ID="your-tenant-id"
+d365fo-mcp-server
+```
+
+#### Azure Key Vault Integration (New in v0.2.3)
+For secure credential storage using Azure Key Vault:
+
+```bash
+export D365FO_BASE_URL="https://your-environment.dynamics.com"
+export D365FO_CREDENTIAL_SOURCE="keyvault"
+export D365FO_KEYVAULT_URL="https://your-keyvault.vault.azure.net/"
 d365fo-mcp-server
 ```
 
@@ -1032,7 +1063,7 @@ tail -f ~/.d365fo-mcp/logs/mcp-server.log
 az account show
 
 # Test with explicit credentials
-export AZURE_CLIENT_ID="your-client-id"
+export D365FO_CLIENT_ID="your-client-id"
 # ... set other variables
 d365fo-mcp-server
 ```